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.
The @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:
The @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 long, Long or
String. Identifiers can either be auto generated by the framework or managed by the application.
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 autoGenerated to 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
fname.
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.
@Entity annotation, you are indicating that the
EntityManager is allowed to manage the persistence of Person objects.
@Identifier. In our example, we have
indicated that field id is the Identifier.
firstName is annotated with @Property. We are also indicating that
firstName be mapped to a property named fname in the Cloud Datastore.
birthYear from being indexed, by specifying indexed=false
on the corresponding @Property annotation.
citizen does 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 EntityManager.
Note
If 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 queries etc.
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.