Installing (and using) ActiveAndroid 3.0 in your Android App

If you’re persisting the data in your Android app with SQLite, then ActiveAndroid can keep things much cleaner and simpler for you. You won’t have to define your own SQLiteOpenHelper class; ActiveAndroid will take care of it, as long as you provide it a model and feed it migrations when you make changes to your data structure. Plus, you can interact with your objects pretty much like normal objects, making your code more readable. It’s very similar to the concept of ActiveRecord for Rails. Now, let’s get going setting up!

  1. Download the latest ActiveAndroid jar here
  2. Drag the jar to the libs folder of your app in your IDE (I’m using Android Studio). Right click on the jar, and select "Add as a Library…".
  3. Now go into your AndroidManifest.xml file and ensure that the application’s name is com.activeandroid.app.Application. Here’s an example of how my application node setting looks like:

    <application
      android:name="com.activeandroid.app.Application"
      android:allowBackup="true"
      android:icon="@drawable/ic_launcher"
      android:label="@string/app_name"
      android:theme="@style/Theme.AppCompat.Light.DarkActionBar" >
    
  4. While you’re in your AndroidManifest.xml, you’ll also want to add some metadata about your database, like the name and version. Again, here’s what mine looks like:

    <application
      android:name="com.activeandroid.app.Application"
      android:allowBackup="true"
      android:icon="@drawable/ic_launcher"
      android:label="@string/app_name"
      android:theme="@style/Theme.AppCompat.Light.DarkActionBar" >
    
      <meta-data
        android:name="AA_DB_NAME"
        android:value="Application.db" />
      <meta-data
        android:name="AA_DB_VERSION"
        android:value="1" />
    

    Once that’s done, you’re ready to use ActiveAndroid. Woohoo!

  5. Create a model (or open up an existing one). I like to put my models in their own package called "models." My model looks like this:

    public class Item {
    
      private String name;
    
      public Item(String name){
        this.name = name;
      }
    
      public String getName(){
        return name;
      }
    
      public void setName(String name){
        this.name = name;
      }
    }
    
  6. We’d like to make this model into a SQLite table. We can do this by making the model extend the ActiveAndroid Model class, as well as adding annotations to denote table name and columns:

    @Table(name = "Items")
    public class Item extends Model {
    
      @Column(name = "Name")
      private String name;
    
      public Item(String name){
        this.name = name;
      }
    
      public String getName(){
        return name;
      }
    
      public void setName(String name){
        this.name = name;
      }
    }
    

    Note that the names you provide in the annotations refer to the actual name the table and columns will be given in the SQLite database itself. So make sure you follow the SQLite naming conventions there.

  7. Add an empty constructor, and add a call to super() to the beginning of all constructors:

    @Table(name = "Items")
    public class Item extends Model {
    
      @Column(name = "Name")
      private String name;
    
      public Item(){
        super();         
      }
    
      public Item(String name){
        super();
        this.name = name;
      }
    
      public String getName(){
        return name;
      }
    
      public void setName(String name){
        this.name = name;
      }
    }
    
  8. Delete your SQLiteOpenHelper class if you have one—otherwise there will be conflicts and confusion. ActiveAndroid takes care of the helper for you.

  9. That’s it! You’ve got ActiveAndroid and your Items table all set up. To make sure that it worked, run your app and then open the Android Device Monitor. Go to the File Explorer tab to see all of the files and directories. Go to data/data/[your app]/databases. Click on Application.db (or whatever you named your database) and then select the item in the menu that says "Pull File." This will save your SQLite database to your desktop. Now you can open that database using a tool like SQLiteBrowser and view its contents. You should see that there is a table called "Items", which has a primary key Id of type Integer and, in my case, Name of type Text.

Note that ActiveAndroid does automatically create a unique primary key for your records called "Id". You can access your object’s id by calling .getId() on it. This is a long datatype, not an integer even though that’s how it’s stored in the database.

Querying usage is pretty straight forward; the documentation can be found here. The important thing to remember is to call the .save() method on your object if you want it to actually save to the database.

Here are 2 examples of useful queries that I’ve added to my Item model, one to get an item based on its id and another to get a list of all of the items:

public static Item getItemWithId(long id) {
  return new Select().from(Item.class).where("id = ?", id).executeSingle();
}

public static List<Item> getAll(){
  return new Select().from(Item.class).execute();
}