Generator

How to use the legacy greenDAO generator to create entities and DAO files.

In most cases, we recommended to use the new Gradle plugin instead. However, some advanced features are currently only supported by the generator. For example multiple schemas.

Overview

To learn how to create entities you should have a look at the DaoExampleGenerator project. It contains a single class containing the data model definition in code:

As you can see, you create a Schema object, to which you can add entities. An entity is a class tied to a database table. An entity contains properties, which are mapped to database columns.
Once the schema is completely defined, you can trigger the code generation. This is how Note.java and NoteDao.java files');">the [crayon-584ceab34bb82684127533-i/] and [crayon-584ceab34bb84034823196-i/] files from the DaoExample project where created.

Schema

Entities belong to a schema, so 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 you want the DAO and test classes to go into separate packages, refine your schema like this:

Finally, there are two optional flags to make entities active, and to turn on support for keep sections. 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 add entities to it:

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

Custom types

To map a custom type to one of the supported property types, specify the custom type and a converter when adding a property:

See Custom Types for further details.

Inheritance, Interfaces, and Serializable

Entities may inherit from another non-entity class:

Note: currently it is impossible to have another entity as a super class (there are no polymorphic queries either).

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:

There is a convenience method to make an entity inherit from Serializable:

Javadoc and annotations

You can add Javadoc documentation and Java annotations to entities:

Use \n to create a new line. The Javadoc string will automatically be wrapped in a proper Javadoc comment.

The same is possible for properties of entities, except that you can control it for fields, getters, and setters separately:

The full list of methods offered by PropertyBuilder:

  • codeBeforeField
  • codeBeforeGetter
  • codeBeforeGetterAndSetter
  • codeBeforeSetter
  • javaDocField
  • javaDocGetter
  • javaDocGetterAndSetter
  • javaDocSetter

If you experience encoding issues (like when using a non-US-ASCII language like Chinese), double check your Gradle settings. Maybe you have to add the following line to your Gradle script:

Keep sections

Entity classes are overwritten on each generator run. So to add custom code to your enities use “KEEP” sections.

To enable them, call enableKeepSectionsByDefault() on the schema, or setHasKeepSections(true) on specific entities.

Once you run your generator again, three keep sections are generated inside the entities. Now, you can put your custom code between KEEP [...] and KEEP [...] END:

Do not modify the KEEP comments.

In any case, it is a good idea to backup or commit your custom code in case something goes wrong.

Relations

For an overview over relations, see Relations.

To-One relations (1:1)

To create a to-one relation to another entity (one entity object) add a property for the foreign key (id) value. Use the new property to add the relation:

The generated User entity will now have a Picture property (including getPicture() and setPicture()).

See Modelling To-One Relations for further details.

Relation names and multiple relations

To add additional to-one relations to the same entity, they need to be named:

To-Many relations (1:N)

To add a to-many relation to a list of entities add a foreign key property to that entity, then set up the relation for your entity:

See Resolving and Updating To-Many Relations for further details.

Bi-Directional 1:N Relations

Sometimes you want to navigate 1:N relations in both directions. In greenDAO, you have to add a to-one and a to-many relation to achieve this.

The following example shows the complete modelling of the customer and order entities, we used as an example before. This time, we use the customerId property for creating both relations:

Let’s assume we have an order entity. Using both relations, we could get the customer and all orders the customer has ever made:

Many-to-Many Relations (N:M)

In databases, N:M relations are modeled using a join table. The join table holds entries having rows with foreign keys to each of the relating tables.

While the generator does not support N:M relations directly, you can model the join table as a separate entity. In practice, you often have “relation entities” with additional properties, so you might want to do so anyway.

greenDAO 3 has direct support for n:m relations.

Modelling Tree Relations (Example)

You can model a tree relation by modelling an entity having a to-one and a to-many relation pointing to itself:

The generated entity lets you navigate to its parent and children:

Triggering generation

Once your entity schema is in place, you can trigger the code generation process. In your generator project (a Java project having a static main() method) call:

So, all you need is the schema object and a target directory, which is typically a source folder of your Android project.

To generate the test classes in a separate directory you can specify another directory as a third parameter to generateAll().

More examples

Check out the DaoExampleGenerator project. Also, the DaoGenerator internal sub project may contain useful examples.

Spread the love
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •