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:
| 1 2 3 4 5 6 7 8 9 | // In the build.gradle file of your app project: android { ... } greendao { schemaVersion 2 // daoPackage "com.example.model" // set package of generated classes } |
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:
| 1 2 3 4 5 6 7 8 9 10 11 12 | @Entity public class User { @Id private Long id; private String name; @Transient private int tempUsageCount; // not persisted // getters and setters for id and user ... } |
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:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | @Entity( // If you have more than one schema, you can tell greenDAO // to which schema an entity belongs (pick any string as a name). schema = "myschema", // Flag to make an entity "active": Active entities have update, // delete, and refresh methods. active = true, // Specifies the name of the table in the database. // By default, the name is based on the entities class name. nameInDb = "AWESOME_USERS", // Define indexes spanning multiple columns here. indexes = { @Index(value = "name DESC", unique = true) }, // Flag if the DAO should create the database table (default is true). // Set this to false, if you have multiple entities mapping to one table, // or the table creation is done outside of greenDAO. createInDb = false, // Whether an all properties constructor should be generated. // A no-args constructor is always required. generateConstructors = true, // Whether getters and setters for properties should be generated if missing. generateGettersSetters = true ) public class User { ... } |
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
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | @Entity public class User { @Id(autoincrement = true) private Long id; @Property(nameInDb = "USERNAME") private String name; @NotNull private int repos; @Transient private int tempUsageCount; ... } |
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:
| 1 2 3 4 5 | @Id private Long id; @Index(unique = true) private String key; |
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.
| 1 2 3 4 5 6 | @Entity public class User { @Id private Long id; @Index(unique = true) private String name; } |
@Unique adds a UNIQUE constraint to the database column. Note, that SQLite also implicitly creates an index for it.
| 1 2 3 4 5 | @Entity public class User { @Id private Long id; @Unique private String name; } |
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:
| 1 2 3 4 | Error:Execution failed for task ':app:greendao'. > Constructor (see ExampleEntity:21) has been changed after generation. Please either mark it with @Keep annotation instead of @Generated to keep it untouched, or use @Generated (without hash) to allow to replace it. |
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.
