Entity Annotation

Use this annotation on a model class to mark it as a persistable entity. The EntityManager provides a variety of methods to work with Entities - such as insert, update, delete and querying. Entity classes may follow the standard JavaBeans pattern or the Builder pattern.

Using the Entity annotation, you can also define the Datastore Kind to which an entity is mapped.

@Entity(kind="people")
public class Person {
}

If the kind attribute is omitted, it defaults to the name of the Class, in this case, Person.

Rules for Entity Classes

Model classes with an annotation of Entity must conform to the following rules. The rules slightly vary depending on whether the Model class is using the JavaBeans pattern or the Builder pattern.

JavaBeans pattern

• Must have a public no-arg constructor.
• Must have exactly one field with an annotation of @Identifier. Refer to the Identifier annotation for further information.
• Each persistable field must have a corresponding public accessor and public mutator method.
• May have no more than one field with @Key annotation which will hold the full key to the entity.
• Field annotated with @Key must have a data type of DatastoreKey.
• The Key field must also have an accessor and mutator method.
• May have no more than one field with @ParentKey annotation which will hold the full key to the parent entity.
• Field annotated with @ParentKey must have a data type of DatastoreKey.
• The Key field must also have an accessor and mutator method.
• May have zero or more embedded objects with an annotation of @Embedded.
• Fields that should not be persisted, but have public accessor and mutator methods, must be annotated with @Ignore annotation.

Example

Person.java

package com.example.catatumbo_wiki.pojo;

import java.time.LocalDate;

import com.jmethods.catatumbo.DatastoreKey;
import com.jmethods.catatumbo.Embedded;
import com.jmethods.catatumbo.Entity;
import com.jmethods.catatumbo.Identifier;
import com.jmethods.catatumbo.Ignore;
import com.jmethods.catatumbo.Key;

@Entity
public class Person {
  @Identifier
  private long id;
  @Key
  private DatastoreKey key;
  private String name;
  private LocalDate birthDate;
  @Ignore
  private int age;
  @Embedded
  private Address address;

  public long getId() {
    return id;
  }

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

  public DatastoreKey getKey() {
    return key;
  }

  public void setKey(DatastoreKey key) {
    this.key = key;
  }

  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;
  }

  public int getAge() {
    return age;
  }

  public void setAge(int age) {
    this.age = age;
  }

  public Address getAddress() {
    return address;
  }

  public void setAddress(Address address) {
    this.address = address;
  }

}

Address.java

import com.jmethods.catatumbo.Embeddable;

@Embeddable
public class Address {
  private String street;
  private String city;
  private String postalCode;

  public String getStreet() {
    return street;
  }

  public void setStreet(String street) {
    this.street = street;
  }

  public String getCity() {
    return city;
  }

  public void setCity(String city) {
    this.city = city;
  }

  public String getPostalCode() {
    return postalCode;
  }

  public void setPostalCode(String postalCode) {
    this.postalCode = postalCode;
  }

}

Builder Pattern

• Must not have a public no-arg constructor. May have a private no-arg constructor or any number of other constructors.
• Must have a static no-arg method that returns a corresponding Builder object. The name of the builder method can be either of the following (in the order of preference):
  • newBuilder
  • builder
• Must have exactly one field with an annotation of @Identifier. Refer to the Identifier annotation for further information.
• Each persistable field must have a corresponding public accessor method.
• Each persistable field must have a corresponding public mutator method in the corresponding Builder class. The name of the mutator method must be one of the following (in the order of preference):
  • setFieldName (e.g. setBirthDate)
  • withFieldName (e.g. withBirthDate)
  • fieldName (e.g. birthDate)
• The mutator methods in the Builder class may have a return type of void or the Builder itself. Returning the Builder helps with method chaining.
• May have no more than one field with @Key annotation which will hold the full key to the entity.
• Field annotated with @Key must have a data type of DatastoreKey.
• The Key field must also have an accessor method.
• May have no more than one field with @ParentKey annotation which will hold the full key to the parent entity.
• Field annotated with @ParentKey must have a data type of DatastoreKey.
• The Key field must also have an accessor method.
• May have zero or more embedded objects with an annotation of @Embedded.
• Fields that should not be persisted must be annotated with @Ignore annotation.

Example

Person.java

import java.time.LocalDate;

import com.jmethods.catatumbo.DatastoreKey;
import com.jmethods.catatumbo.Embedded;
import com.jmethods.catatumbo.Entity;
import com.jmethods.catatumbo.Identifier;
import com.jmethods.catatumbo.Ignore;
import com.jmethods.catatumbo.Key;

@Entity
public class Person {
  @Identifier
  private final long id;
  @Key
  private DatastoreKey key;
  private final String name;
  private final LocalDate birthDate;
  @Ignore
  private int age;
  @Embedded
  private Address address;

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

  public long getId() {
    return id;
  }

  public DatastoreKey getKey() {
    return key;
  }

  public String getName() {
    return name;
  }

  public LocalDate getBirthDate() {
    return birthDate;
  }

  public int getAge() {
    return age;
  }

  public Address getAddress() {
    return address;
  }

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

  public static class Builder {
    private long id;
    private DatastoreKey key;
    private String name;
    private LocalDate birthDate;
    @Embedded
    private Address address;

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

    public void setKey(DatastoreKey key) {
      this.key = key;
    }

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

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

    public void setAddress(Address address) {
      this.address = address;
    }

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

  }

}

Address.java

import com.jmethods.catatumbo.Embeddable;

@Embeddable
public class Address {
  private String street;
  private String city;
  private String postalCode;

  private Address(Builder builder) {
    this.street = builder.street;
    this.city = builder.city;
    this.postalCode = builder.postalCode;
  }

  public String getStreet() {
    return street;
  }

  public String getCity() {
    return city;
  }

  public String getPostalCode() {
    return postalCode;
  }

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

  public static class Builder {
    private String street;
    private String city;
    private String postalCode;

    public String getStreet() {
      return street;
    }

    public void setStreet(String street) {
      this.street = street;
    }

    public String getCity() {
      return city;
    }

    public void setCity(String city) {
      this.city = city;
    }

    public String getPostalCode() {
      return postalCode;
    }

    public void setPostalCode(String postalCode) {
      this.postalCode = postalCode;
    }

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

}