Updating to greenDAO 3 and annotations

Contents

If you are new to greenDAO, start at How to get started.

greenDAO 3 uses annotations to define schemas and entities. In contrast, previous greenDAO versions required developers to have a separate generator Java project.

While you can still do this, greenDAO 3 lets you annotate entity classes to define the schema on the fly. 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). Code generation is now done at build time.

Migrating existing greenDAO 2 projects

There are two ways to use greenDAO 3: keep the generator project or migrate to annotation-based entities while dropping the generator. Which ever way you want to go, you should start with updating the generator project.

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

Step 1: Update dependencies to V3

1. Update your generator project: update the greendao-generator dependency to version 3. In your generator class, change your imports from de.greenrobot.daogenerator to org.greenrobot.greendao.generator.

2. Run your generator. This will generate entities with the new greenDAO 3 annotations.

3. Update your Android project: update the greendao dependency to version 3.

The greenDAO package has changed here as well: all classes have moved from de.greenrobot.dao to  org.greenrobot.greendao (use your IDE’s Find and Replace to update your imports):

If you are using ProGuard, you may want to update your rules for greenDAO:

Step 2: Use entity annotations

Before greenDAO 3, entity classes were created by greenDAO and the developer could add custom code to them using keep sections. greenDAO 3 inverts this behavior: the developer creates the entity classes using annotations and greenDAO may augment them with additional code for DAOs.

Once you have created the annotated entity classes with your updated generator, you can then use the new greenDAO Gradle plugin to replace your generator project.

Note: 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.

The next section will explain how to use the Gradle plugin. Once this is set up, keep in mind that your DAO classes (DaoMaster, DaoSession, DAOs) are now generated automatically on each build. So you can safely delete the versions created with your old generator project.

If everything works fine, you should then be able to completely abandon your old generator project (if not, let us know).

greenDAO 3 Gradle Plugin

greenDAO 3 generates code using a new Gradle plugin. It will scan all entity classes to collect schema information and generate DaoSession, DaoMaster, and all the DAO classes. In many ways, the greenDAO Gradle plugin is the replacement for the generator project. Actually, the Gradle plugin uses the generator library internally.

To use the greenDAO Gradle plugin, add it to your build script.

Now, when you build your project, greenDAO code generation is executed. This is also triggered when you select “Build > Make Project” in Android Studio. By default, it generates Java sources in  build/generated/source/greendao, and adds this directory as a source folder for the Gradle build. The directory is configurable, see the next section for details.

Troubleshooting tip: If you think something is wrong with the generated classes, check out build/generated/source/greendao first.

Configuration, Entities and Annotations

Finally, have a look at the documentation, notably Modelling entities, to learn how to configure the new Gradle plugin and how to use the new annotations.

Spread the love