If you are using Maven, add the following dependency to your project. This will download the Catatumbo JAR file and all other dependencies.
If you are using Gradle, add the following dependency to your project. This will download the Catatumbo JAR file and all other dependencies.
Catatumbo Framework supplies the following annotations to perform object mapping and manage persistence of domain model.
@Entity annotation is used to annotate model classes that need to be
persisted. Can optionally
define the Kind, if it needs to be different than the class name.
The below example marks the Person class as a managed Entity and maps the Person objects to entities of Kind Person in the Google Cloud Datastore.
If you need to map Person objects to entities of Kind People in the Google Cloud Datastore, simply specify the kind as shown below:
@Identifier annotation is used to mark the identifier of your model class.
In a given class, only one
field can have this annotation. The field with this annotation must be of type
String. Identifiers can either be auto generated by the framework or managed by
The example below marks the field id as an identifier and tells that the identifiers have to be automatically generated by the framework, when needed.
If you rather want your application to manage the identifiers (e.g. use email address as the
identifier), you can
simply set the
false as shown below:
By default, all instance variables that have corresponding accessor methods would be persisted by Catatumbo. The property name in the Datastore would be same as the name of the instance variable. If you need to map an instance variable to a different property name in the Cloud Datastore, you would use this annotation. In addition, this annotation controls whether or not a field is indexed.
The example below maps the
firstName field of the
Person entity to
a property named
Use this annotation on any field that should be excluded from mapping and persistence.
Use this annotation on a class that can be embedded into your entities. For example, you might want to create a common class, Address, to store addresses and embed the Address objects in various Entity classes such as Person, Customer, Contact, Employee, etc. When your Entity (e.g. Person) is persisted, all persistable fields from the Address class would also be persisted.
This annotation specifies that the field of a model class is an Embeddable. In the below example, field homeAddress is annotated with @Embedded. The Address class must have an annotation of Embeddable.
These two annotations are specified on the Entity class to override any property definitions of embedded objects. Typically, you would only use these annotations if the embedded objects in the Entity produce duplicate property names. You may also use these annotations to override the index property of the embedded objects. The sample code below resolves the property name conflicts produced by homeAddress and workAddress by overriding the properties of each address.
We will use the below Person class to demonstrate how to use Catatumbo.
@Entityannotation, you are indicating that the
EntityManageris allowed to manage the persistence of Person objects.
@Identifier. In our example, we have indicated that field id is the Identifier.
firstNameis annotated with
@Property. We are also indicating that
firstNamebe mapped to a property named
fnamein the Cloud Datastore.
birthYearfrom being indexed, by specifying
indexed=falseon the corresponding
citizendoes not have any annotations, but it will still be persisted by the
EntityManager. The property name in the Datastore will also be citizen, same as the field name.
Now that you have your model class, saving or loading Person objects is a snap.
The first and foremost thing is to create an
EntityManager to manage the
persistence. The code below
shows how to create an
NoteIf you are planning to run your code on Google App Engine or Google Compute Engine, you may not have to specify the Project Name or Credentials. In some cases, this is also true when running the code outside of App Engine or Compute Engine. In this case, simply create the Default EntityManager as shown below:
Once you have the
EntityManager, you can insert, update, delete, load, run
When you run this code, you should see something similar to the below line in your console:
person with ID 5668906396024832 created successfully
In the above example, we are asking the EntityManager to load an entity with ID 5668906396024832. We are also telling the EntityManager that we are expecting the result to be a Person object. When you run this sample, you should see the below line in console:
First Name: John; Last Name: Doe; Birth Year: 1975; Citizen: true
Querying is currently implemented with GQL.
The example below uses the same Person object from the previous examples, but uses the Builder pattern.
build, to return a Person object.