Quick Start Guide

Setting up your project


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.

Introduction to Catatumbo Annotations

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.

@PropertyOverrides and @PropertyOverride

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.

Example Code for CRUD Operations

Create your Model Class

We will use the below Person class to demonstrate how to use Catatumbo.


Now that you have your model class, saving or loading Person objects is a snap.

Creating the EntityManager

The first and foremost thing is to create an EntityManager to manage the persistence. The code below shows how to create an EntityManager.


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.

Inserting a Person object

When you run this code, you should see something similar to the below line in your console:

person with ID 5668906396024832 created successfully

Loading (or retrieving) a Person object by ID

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

Updating a Person Object

Deleting a Person by ID

Deleting Person Object


Querying is currently implemented with GQL.

Simple Select All Query

Query with a Filter using Positional Parameters

Query with a Filter using Named Parameters

Pagination Example

Using Builder Pattern for Model Classes

All previous examples used the classic Java Beans pattern for the model class. As of version 2.3.0 of Catatumbo, model classes can also use Builder pattern. Builder pattern is useful if the persistence objects need to be immutable and/or to ensure the state of persistence objects is always valid/consistent.

The example below uses the same Person object from the previous examples, but uses the Builder pattern.


Inserting a Person Object