Quick Start

Add Dependency

Add Catatumbo as a dependency to your project.

Maven

<dependency>
  <groupId>com.jmethods</groupId>
  <artifactId>catatumbo</artifactId>
  <version>2.3.0</version>
</dependency>

Gradle

dependencies {
    compile 'com.jmethods:catatumbo:2.3.0'
}

Define Model Class

Model classes can either use classic JavaBeans Pattern or Builder Pattern. In either case, note that the model class is annotated with @Entity. Also, the id field is annotated as @Identifier.

Classic JavaBeans Pattern

import java.time.LocalDate;

import com.jmethods.catatumbo.Entity;
import com.jmethods.catatumbo.Identifier;

@Entity
public class Person {
  @Identifier
  private long id;
  private String name;
  private LocalDate birthDate;

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public LocalDate getBirthDate() {
    return birthDate;
  }

  public void setBirthDate(LocalDate birthDate) {
    this.birthDate = birthDate;
  }

}

Builder Pattern

@Entity
public class Person {
  @Identifier
  private final long id;
  private final String name;
  private final LocalDate birthDate;

  private Person(Builder builder) {
    this.id = builder.id;
    this.name = builder.name;
    this.birthDate = builder.birthDate;
  }

  public long getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public LocalDate getBirthDate() {
    return birthDate;
  }

  public static Builder newBuilder() {
    return new Builder();
  }

  public static class Builder {
    private long id;
    private String name;
    private LocalDate birthDate;

    public Builder setId(long id) {
      this.id = id;
      return this;
    }

    public Builder setName(String name) {
      this.name = name;
      return this;
    }

    public Builder setBirthDate(LocalDate birthDate) {
      this.birthDate = birthDate;
      return this;
    }

    public Person build() {
      return new Person(this);
    }

  }

}

Create DAO

Now let's create a simple DAO to create, read, update and delete Person entities.

import com.jmethods.catatumbo.EntityManager;
import com.jmethods.catatumbo.EntityManagerFactory;

public class PersonDAO {

  public static PersonDAO instance = new PersonDAO();
  private EntityManager em;

  private PersonDAO() {
    em = EntityManagerFactory.getInstance().createDefaultEntityManager();
  }

  public Person create(Person person) {
    return em.insert(person);
  }

  public Person update(Person person) {
    return em.update(person);
  }

  public void delete(Person person) {
    em.delete(person);
  }

  public Person read(long id) {
    return em.load(Person.class, id);
  }

}

Insert an Entity

Classic JavaBeans Pattern

import java.time.LocalDate;

import com.jmethods.catatumbo.EntityManagerException;

public class CreatePerson {

  public static void main(String[] args) {
    Person person = new Person();
    person.setName("John Doe");
    person.setBirthDate(LocalDate.of(1990, 2, 15));
    try {
      PersonDAO dao = PersonDAO.getInstance();
      person = dao.create(person);
      System.out.printf("Person entity with ID %d was created successfully", person.getId());
    } catch (EntityManagerException e) {
      e.printStackTrace();
    }
  }

}

Builder Pattern

import java.time.LocalDate;

import com.jmethods.catatumbo.EntityManagerException;

public class CreatePerson {

  public static void main(String[] args) {
    Person person = Person.newBuilder().setName("John Doe").setBirthDate(LocalDate.of(1990, 2, 15))
        .build();
    try {
      PersonDAO dao = PersonDAO.getInstance();
      person = dao.create(person);
      System.out.printf("Person entity with ID %d was created successfully", person.getId());
    } catch (EntityManagerException exp) {
      exp.printStackTrace();
    }
  }

}

When you run either of the CreatePerson programs, a new entity will be created in Google Cloud Datastore. The console should have something like this:

Person entity with ID 5754272234864640 was created successfully

Log into Google Cloud Console and make sure the new Person entity is created as shown below:

Read (or Retrieve) an Entity by ID

import com.jmethods.catatumbo.EntityManagerException;

public class ReadPersonById {
  public static void main(String[] args) {
    try {
      Person person = PersonDAO.getInstance().read(5754272234864640L);
      System.out.printf("ID: %d; Name: %s; Birth Date: %s", person.getId(), person.getName(),
          person.getBirthDate());
    } catch (EntityManagerException exp) {
      exp.printStackTrace();
    }
  }

}

When you run this program, the Person entity with the specified ID will be read from the Google Cloud Datastore and the details are printed to the console as shown below:

ID: 5754272234864640; Name: John Doe; Birth Date: 1990-02-15

Update an Entity

import java.time.LocalDate;

import com.jmethods.catatumbo.EntityManagerException;

public class UpdatePerson {
  public static void main(String[] args) {
    try {
      // Read an existing entity and print the details to the console
      Person person = PersonDAO.getInstance().read(5754272234864640L);
      System.out.printf("[Original] ID: %d; Name: %s; Birth Date: %s%n", person.getId(),
          person.getName(), person.getBirthDate());
      // Change one or more attributes
      person.setName("John Smith");
      person.setBirthDate(LocalDate.now());
      person = PersonDAO.getInstance().update(person);
      System.out.printf("[Updated] ID: %d; Name: %s; Birth Date: %s%n", person.getId(),
          person.getName(), person.getBirthDate());
    } catch (EntityManagerException exp) {
      exp.printStackTrace();
    }
  }

}

Running this program should print the following to the Console:

[Original] ID: 5754272234864640; Name: John Doe; Birth Date: 1990-02-15
[Updated] ID: 5754272234864640; Name: John Smith; Birth Date: 2017-09-29

The screenshot below shows the updated entity:

Delete an Entity

package com.example.catatumbo_wiki.pojo;

import com.jmethods.catatumbo.EntityManagerException;

public class DeletePerson {
  public static void main(String[] args) {
    try {
      // Read an existing entity and print the details to the console
      Person person = PersonDAO.getInstance().read(5754272234864640L);
      System.out.printf("[Original] ID: %d; Name: %s; Birth Date: %s%n", person.getId(),
          person.getName(), person.getBirthDate());
      // Change one or more attributes
      PersonDAO.getInstance().delete(person);
      System.out.printf("Person with ID %d was deleted successfully%n", person.getId());
    } catch (EntityManagerException exp) {
      exp.printStackTrace();
    }
  }

}

Running this program would print the below to the Console.

[Original] ID: 5754272234864640; Name: John Smith; Birth Date: 2017-09-29
Person with ID 5754272234864640 was deleted successfully

The screenshot below illustrates that the entity is deleted from the Google Cloud Datastore: