Modelling entities

The first step to use greenDAO in a project is to create a entity model representing the persistent data used in your application. Based on this model greenDAO generates Java code for the DAO classes.

The model itself is defined using Java code. It is easy: create an Java project based on the DaoExampleGenerator project. Look at the How to get started document for details.

The illustration on the right depicts the meta model. That is the classes used to describe your domain specific model.

Schema

Entities belong to a schema. A schema is the first object you define. Call the constructor with the schema version and the default Java package:

The default Java package is used when greenDAO generates entities, DAOs, and JUnit tests. If those defaults are fine for your project, you are done with the first step.

If you want the DAO and test classes to go into separate packages, can refine your schema like this:

The schema also has two default flags for entities, which can be overridden. The flags tell if entities are active, and if keep sections should be used. Those features are not yet documented; have a look at the test project in the source code distribution.

Entities

Once you have a schema object you can use the schema to add entities to it:

An entity has several settings you can change, and more importantly, you can add properties to an entity:

Besides properties, you can also add to-one and to-many relations to an entity.

Properties and primary keys

The previous entity section showed how you add properties to an entity. The addXXXProperty of the Entity class return an PropertyBuilder object, which can be used to configure the property. For example, use the method columnName to override the default column name and provide your own. To access the property object needed for creating indices and relations, call getProperty() on the PropertyBuilder object.

Current primary key (PK) restrictions: Currently, entities must have a long or Long property as their primary key. This is recommended practice for Android and SQLite. greenDAO is prepared to handle any primary key scenario in the future, but not everything is implemented completely yet. To work around this issue, you can use a long primary key and use an unique index for the intended “key” properties.

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-one and to-many relations are documented on a separate page.

Inheritance, Interfaces, and Serializable

Entities may inherit from another non-entity class. This super class is specified by the setSuperclass(String) method. Note: currently it’s impossible to have another entity as a super class (there are no polymorphic queries either). Example:

Often it is preferable to use interfaces as a common base for entity properties and behavior. For example, if entity A and B share a set of properties, these properties (their getters and setters) can be defined in interface C. This is shown in the following example, which also makes entity B Serializable:

Triggering generation

Once your entity schema is in place, you can trigger the code generation process. In the generator project (a Java project having a static main() method), you need to instantiate DaoGenerator and call one of the generateAll methods:

So, all you need is the schema object and a target directory, which is typically a source folder of your Android project. If you want the test classes to go into another directory, you can specify another directory as the third parameter.

Keep sections

Entity classes are overwritten on each generator run. To allow adding custom code to your enities, greenDAO has “keep” sections. To enable them, use enableKeepSectionsByDefault() on the schema, or setHasKeepSections(true) on selected entities. Once enabled, three keep sections are generated in the entities:

Now, you can put your custom code between KEEP [...] and KEEP [...] END. And don’t touch the KEEP comments. Code inside the keep section is kept during code generation. It’s a good idea to backup or commit your code in case something goes wrong unexpectedly.