Tutorial

This tutorial will explain the initial steps to begin developing with Datarobot for Android. Before starting with it you should setup you IDE. The setup of the common IDEs is explained here.

Create a database

You have enabled your project to use the benefits of Datarobot for Android, now let's start developing. Creating a database

First of all you create a simple class, the name of the class is not important so you can choose a name you like. The class will be used do some basic configurations. For this tutorial let's use the name PersistenceConfig. After you created the class annotate it with @Persistence. Enter the dbVersion 1, this is the version attribute that you normally would specify within your SQLiteDatabaseHelper. Optionally you can enter a name for the database file. If you don't provide one storage.db will be used as default.

It is recommended to also annotate PersistenceConfig with @Update and let it implement the interface DbUpdate. This provides you with the possibility to update your database when incrementing the version.

With the basic configuration done you probably want to create your first entity. Entities are simple POJOs annotated with the @Entity annotation. Create a new class and name it User. Annotate the class with the annotation @Entity. Every @Entity needs a primary key so create a field _id of type Integer and annotate it with @PrimaryKey, @AutoIncrement and @Column. The @Column annotation marks this field to be mapped to a column with in the database, the @AutoIncrement annotation is optional and allows the primary key to be increment automatically when being saved. The @PrimaryKey annotation sets this column to be the primary key. The resulting class should look like the following snippet

After adding the primary key, add some more columns. For example a field of type String called name annotated with @Column. With this class Datarobot will generate the table user with two columns _id and name.

The resulting entity should look similar to the following.

@Entity
public class User {
   @PrimaryKey
   @AutoIncrement
   @Column
   private Integer _id;
   @Column
   private String name;

   ...
}

Clean your project and you will find two classes, DB and UserContentProvider within your configured generated source directory of the Annotation Processing.

The DB class is the database schema containing information about the database like version and name as well as all containing tables and their relationships with each other.

The UserContentProvider is a Android ContentProvider for the User entity, it can be used with a ContentResolver like any other ContentProvider. It is already registered within your AndroidManifest.xml. This is all done for you be adding the @Entity annotation. If you like to configure the authority are the exported state of the generated contentProvider you can do this with the respective parameters of the @Entity annotation. In case you do not want a ContentProvider for your entity you simply set the contentProvider parameter to false.

You have created a database and a table named User within it. This was pretty simple right?

Storing data

Now that you have a database you probably want to store some data within it. For easy storing and loading entities in the database a service called EntityService is provided for you. Within a activity instantiate an EntityService and give it the @Entity annotated class as second constructor argument. After this you can create a simple instance of the User class, give it some data and hand it to the EntityServices' save method for storing.

EntityService userService = new EntityService(this, User.class);
userService.save(new User("user #1"));
userService.close();

This snippet will save a new user into the User table and return its primary key. The primary key will also be set to the given POJO, which has in this case no effect. Being able to save data you also want to retrieve it again from the database. You can do it with the generated ContentProvider, any standard mechanism you know by Android or use the EntityService to directly get a entity object.

EntityService userService = new EntityService(this, User.class);
List<User> allUsers = userService.get();
userService.close();

With this simple snippet you can load all users previously saved as User objects from the database. After storing and loading data to and from the database you may want to update entities. This also be easily done using the save method on the EntityService. It will, according to the primary key, determine whether to insert or update the entity. This are the basic steps to start developing with Datarobot for Android.

Have fun exploring the API and create Apps backed by a database more easily.