Generator - Open Source by greenrobot

Contents

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

In most cases, we recommend 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:

Schema schema = new Schema(1, "de.greenrobot.daoexample");

Entity note= schema.addEntity("Note");
note.addIdProperty();
note.addStringProperty("text").notNull();
note.addStringProperty("comment");
note.addDateProperty("date");

new DaoGenerator().generateAll(schema, "../DaoExample/src/main/java");

Schema schema = new Schema(1, "de.greenrobot.daoexample");

Entity note= schema.addEntity("Note");

note.addIdProperty();

note.addStringProperty("text").notNull();

note.addStringProperty("comment");

note.addDateProperty("date");

new DaoGenerator().generateAll(schema, "../DaoExample/src/main/java");

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 the Note.java and NoteDao.java 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:

Schema schema = new Schema(1, "de.greenrobot.daoexample");

1	Schema schema = new Schema(1, "de.greenrobot.daoexample");

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:

// DAO classes go into the "dao" package
schema.setDefaultJavaPackageDao("de.greenrobot.daoexample.dao");
// test classes go into the "test" package
schema.setDefaultJavaPackageTest("de.greenrobot.daoexample.test");

// DAO classes go into the "dao" package

schema.setDefaultJavaPackageDao("de.greenrobot.daoexample.dao");

// test classes go into the "test" package

schema.setDefaultJavaPackageTest("de.greenrobot.daoexample.test");

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.

// optional: make entities active
schema.enableActiveEntitiesByDefault();
// optional: enable KEEP section support
schema.enableKeepSectionsByDefault();

// optional: make entities active

schema.enableActiveEntitiesByDefault();

// optional: enable KEEP section support

schema.enableKeepSectionsByDefault();

Entities

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

Entity user = schema.addEntity("User");

1	Entity user = schema.addEntity("User");

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

user.addIdProperty();
user.addStringProperty("name");
user.addStringProperty("password");
user.addIntProperty("yearOfBirth");

user.addIdProperty();

user.addStringProperty("name");

user.addStringProperty("password");

user.addIntProperty("yearOfBirth");

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:

user.addLongProperty("creationTime")
  .customType("com.example.UserTimestamp", "com.example.UserTimestampConverter");

1 2	user.addLongProperty("creationTime") .customType("com.example.UserTimestamp", "com.example.UserTimestampConverter");

See Custom Types for further details.

Inheritance, Interfaces, and Serializable

Entities may inherit from another non-entity class:

// class ExampleEntity extends BaseClass
exampleEntity.setSuperclass("BaseClass");

1 2	// class ExampleEntity extends BaseClass exampleEntity.setSuperclass("BaseClass");

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:

// entity class A implements C
entityA.implementsInterface("C");
// entity class B implements C
entityB.implementsInterface("C");

// entity class A implements C

entityA.implementsInterface("C");

// entity class B implements C

entityB.implementsInterface("C");

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

// class ExampleEntity implements Serializable
exampleEntity.implementsSerializable();

1 2	// class ExampleEntity implements Serializable exampleEntity.implementsSerializable();

Javadoc and annotations

You can add Javadoc documentation and Java annotations to entities:

myEntity.setJavaDoc("This is an hell of an entity.\nIt represents foos and bars.");
// add an annotation, though you can supply any string
myEntity.setCodeBeforeClass("@Awesome");

myEntity.setJavaDoc("This is an hell of an entity.\nIt represents foos and bars.");

// add an annotation, though you can supply any string

myEntity.setCodeBeforeClass("@Awesome");

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:

myEntity.addIntProperty("counter")
    .codeBeforeField("@SerializedName(\"the-number-of-things\")")
    .javaDocGetterAndSetter("The total count");

myEntity.addIntProperty("counter")

.codeBeforeField("@SerializedName(\"the-number-of-things\")")

.javaDocGetterAndSetter("The total count");

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:

tasks.withType(JavaCompile) { options.encoding = 'UTF-8' }

1	tasks.withType(JavaCompile) { options.encoding = 'UTF-8' }

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:

// KEEP INCLUDES - put your custom includes here
import com.example.ExampleClass;
// KEEP INCLUDES END

...

// KEEP FIELDS - put your custom fields here
private void ExampleClass someCustomField;
// KEEP FIELDS END

...

// KEEP METHODS - put your custom methods here
public ExampleClass getCustomStuff() {
    ...
}
// KEEP METHODS END

// KEEP INCLUDES - put your custom includes here

import com.example.ExampleClass;

// KEEP INCLUDES END

...

// KEEP FIELDS - put your custom fields here

private void ExampleClass someCustomField;

// KEEP FIELDS END

...

// KEEP METHODS - put your custom methods here

public ExampleClass getCustomStuff() {

...

}

// KEEP METHODS 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:

// add the foreign key "pictureId" to the "user" entity
Property pictureIdProperty = user.addLongProperty("pictureId").getProperty();
// set up a to-one relation to the "picture" entity
user.addToOne(picture, pictureIdProperty);

// add the foreign key "pictureId" to the "user" entity

Property pictureIdProperty = user.addLongProperty("pictureId").getProperty();

// set up a to-one relation to the "picture" entity

user.addToOne(picture, pictureIdProperty);

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

Picture picA = user.getPicture();
user.setPicture(picB);

1 2	Picture picA = user.getPicture(); user.setPicture(picB);

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:

// by default a to-one relation is named like the target entity
// here it is automatically named "picture"
Property pictureIdProperty = user.addLongProperty("pictureId").getProperty();
user.addToOne(picture, pictureIdProperty);
// to add more to-one relations, they need to be named differently
// so name this one "thumbnail"
Property thumbnailIdProperty = user.addLongProperty("thumbnailId").getProperty();
user.addToOne(picture, thumbnailIdProperty, "thumbnail");

// by default a to-one relation is named like the target entity

// here it is automatically named "picture"

Property pictureIdProperty = user.addLongProperty("pictureId").getProperty();

user.addToOne(picture, pictureIdProperty);

// to add more to-one relations, they need to be named differently

// so name this one "thumbnail"

Property thumbnailIdProperty = user.addLongProperty("thumbnailId").getProperty();

user.addToOne(picture, thumbnailIdProperty, "thumbnail");

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:

// add customerId foreign key to the order entity
Property customerId = order.addLongProperty("customerId").notNull().getProperty();
// set up a to-many relation to the orders entity from the customer entity
ToMany customerToOrders = customer.addToMany(order, customerId);
// optional: name the relation and specify the order of the referenced items
customerToOrders.setName("orders");
customerToOrders.orderAsc(orderDate);

// add customerId foreign key to the order entity

Property customerId = order.addLongProperty("customerId").notNull().getProperty();

// set up a to-many relation to the orders entity from the customer entity

ToMany customerToOrders = customer.addToMany(order, customerId);

// optional: name the relation and specify the order of the referenced items

customerToOrders.setName("orders");

customerToOrders.orderAsc(orderDate);

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:

Entity customer = schema.addEntity("Customer");
customer.addIdProperty();
customer.addStringProperty("name").notNull();

Entity order = schema.addEntity("Order");
order.setTableName("ORDERS"); // "ORDER" is a reserved keyword
order.addIdProperty();
Property orderDate = order.addDateProperty("date").getProperty();
Property customerId = order.addLongProperty("customerId").notNull().getProperty();
order.addToOne(customer, customerId);

ToMany customerToOrders = customer.addToMany(order, customerId);
customerToOrders.setName("orders");
customerToOrders.orderAsc(orderDate);

Entity customer = schema.addEntity("Customer");

customer.addIdProperty();

customer.addStringProperty("name").notNull();

Entity order = schema.addEntity("Order");

order.setTableName("ORDERS"); // "ORDER" is a reserved keyword

order.addIdProperty();

Property orderDate = order.addDateProperty("date").getProperty();

Property customerId = order.addLongProperty("customerId").notNull().getProperty();

order.addToOne(customer, customerId);

ToMany customerToOrders = customer.addToMany(order, customerId);

customerToOrders.setName("orders");

customerToOrders.orderAsc(orderDate);

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

List allOrdersOfCustomer = order.getCustomer().getOrders();

1	List allOrdersOfCustomer = order.getCustomer().getOrders();

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:

Entity treeEntity = schema.addEntity("TreeEntity");
treeEntity.addIdProperty();
Property parentIdProperty = treeEntity.addLongProperty("parentId").getProperty();
treeEntity.addToOne(treeEntity, parentIdProperty).setName("parent");
treeEntity.addToMany(treeEntity, parentIdProperty).setName("children");

Entity treeEntity = schema.addEntity("TreeEntity");

treeEntity.addIdProperty();

Property parentIdProperty = treeEntity.addLongProperty("parentId").getProperty();

treeEntity.addToOne(treeEntity, parentIdProperty).setName("parent");

treeEntity.addToMany(treeEntity, parentIdProperty).setName("children");

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

TreeEntity parent = child.getParent();
List grandChildren = child.getChildren();

1 2	TreeEntity parent = child.getParent(); List grandChildren = child.getChildren();

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:

DaoGenerator daoGenerator = new DaoGenerator();
daoGenerator.generateAll(schema, "../DaoExample/src/main/java");

1 2	DaoGenerator daoGenerator = new DaoGenerator(); daoGenerator.generateAll(schema, "../DaoExample/src/main/java");

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().

Note: If you have issues running the main() method in Android Studio (NoClassDefFoundError, ClassNotFoundException or TemplateNotFoundException), try running the generator using the Gradle application plugin. Configure the class with your main() method in your build.gradle file:

apply plugin: 'application'
mainClassName = "com.example.YourGeneratorClass"

1 2	apply plugin: 'application' mainClassName = "com.example.YourGeneratorClass"

Then execute the Gradle run task.

More examples

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

Spread the love