Modelling entities

Contents

To use greenDAO in a project you create an entity model representing the persistent data in your application. Then, based on this model greenDAO generates Java code for the DAO classes.

The model itself is defined using Java classes with annotations.

To use the legacy generator to create your schema, see Generator.

The illustration on the right depicts the meta model that greenDAO is based on.

Schema

You can get started with the greenDAO Gradle plugin without any additional configuration. Though, you should consider setting at least the schema version:

Furthermore, the greendao configuration element supports a host of configuration options:

  • schemaVersion: The current version of the database schema. This is used by the *OpenHelpers classes to migrate between schema versions. If you change your entity/database schema, this value has to be increased. Defaults to 1.
  • daoPackage: The package name for generated DAOs, DaoMaster, and DaoSession. Defaults to the package name of your source entities.
  • targetGenDir: The location where generated sources should be stored at. Defaults to the generated source folder inside the build directory ( build/generated/source/greendao).
  • generateTests: Set to true to automatically generate unit tests.
  • targetGenDirTests: The base directory where generated unit tests should be stored at. Defaults to src/androidTest/java.

Entities and Annotations

greenDAO 3 uses annotations to define schemas and entities. Here is a quick example:

The @Entity annotation turns the Java class User into a database-backed entity. This will also instruct greenDAO to generate the necessary code (for example DAOs).

Note: only Java classes are supported. If you prefer another language like Kotlin, your entity classes must still be Java.

The @Entity Annotation

As you saw in the example above, the @Entity annotation marks a Java class as a presistable entity for greenDAO.

While it is usually fine to go without any additional parameters, you can still configure some details using @Entity:

Note that multiple schemas are currently not supported when using the Gradle plugin. For the time being, continue to use your generator project.

Basic properties

The @Id annotation selects a long/ Long property as the entity ID. In database terms, it’s the primary key. The parameter autoincrement is a flag to make the ID value ever increasing (not reusing old values).

@Property lets you define a non-default column name, which the property is mapped to. If absent, greenDAO will use the field name in a SQL-ish fashion (upper case, underscores instead of camel case, for example customName will become CUSTOM_NAME). Note: you currently can only use inline constants to specify a column name.

@NotNull makes the property a “NOT NULL” column on the database side. Usually it makes sense to mark primitive types (long, int, short, byte) with @NotNull, while having nullable values with wrapper classes (Long, Integer, Short, Byte).

@Transient marks properties to be excluded from persistence. Use those for temporary states, etc. Alternatively, you can also use the transient keyword from Java.

Primary key restrictions

Currently, entities must have a long or Long property as their primary key. This is recommended practice for Android and SQLite.

To work around this, define your key property as an additional property, but create a unique index for it:

Property indexes

Use @Index at a property to create a database index for the corresponding database column. Use the following parameters to customize:

  • name: If you do not like the default name greenDAO generates for the index, you can specify yours here.
  • unique: Adds a UNIQUE constraint to the index, forcing all values to be unique.

@Unique adds a UNIQUE constraint to the database column. Note, that SQLite also implicitly creates an index for it.

Note: To add an index spanning multiple properties, see the documentation for the @Entity annotation.

Defaults

greenDAO tries to work with reasonable defaults, so developers don’t have to configure each and every bit.

For example the table and column name on the database side are derived from the entity and property names. Instead of the camel case style used in Java, the default database names are in uppercase using an underscore to separate word.

For example, a property called creationDate will become a database column CREATION_DATE.

Relations

To learn how to add to-one and to-many relations see Relations.

Triggering generation

Once your entity schema is in place, you can trigger the code generation process by using “Make project” in your IDE. Or by directly executing the greendao Gradle task.

If you encounter errors after changing your entity classes, try to rebuild your project to make sure old generated classes are cleaned.

Modifying generated code

Entity classes in greenDAO 3 are created and edited by the developer. However, during the code generation process greenDAO may augment the source code of entities.

greenDAO will add a @Generated annotation to methods and fields it created, to inform the developer and to prevent any loss of code. In most cases, you should not have to touch code annotated with @Generated.

As a precaution, greenDAO will not overwrite existing code and raise an error if generated code was manually changed:

As the error message implies, there are usually two ways to resolve this:

  • Revert the changes to code annotated with @Generated. Alternatively, you can also delete the changed constructor or method completely. They will be regenerated with the next build.
  • Replace the @Generated annotation with a @Keep annotation. This will tell greenDAO to never touch the annotated code. Keep in mind that your changes might break the contract between the entity and the rest of greenDAO. Also, future releases of greenDAO might expect different code in generated methods. So, be cautious! It’s a good idea to have unit tests in place to avoid trouble.

Keep sections

KEEP sections used in older versions of greenDAO are no longer supported.

However, if the Gradle plugin detects a KEEP FIELDS section it will automatically annotate fields inside with @Transient. Afterwards, the surrounding KEEP FIELDS comments may be removed.

Spread the love