ORMDroid: Bugfixes + Sample App = Happiness!

So a few people have taken a look at ORMDroid since my previous blogs, and the feedback I’m getting most often is along the lines of “Sure, there’s some simple example snippets, but I want a complete, compilable, runnable example!” With this in mind, I’ve thrown together a very basic Android app that uses ORMDroid as it’s persistence framework. Like ORMDroid itself, it’s only in SVN for the moment, but you can browse the code online in the Google Code repository (Edit: Moved to Github), or check it out to build locally:

# git clone https://github.com/roscopeco/ormdroid-example.git

The sample app is a very simple address-book-type app that has a list of people and departments, with each person belonging to a department. It supports the basic CRUD operations, and gives a basic working example of ORMDroid in action.

A few things to note about the sample app:

  • It’s not pretty – It’s targeted at API 8 (ORMDroid’s minimum API level) and doesn’t have any kind of fancy UI, in order to keep the code simple. In fact, the UI is singularly awful (especially on newer devices), but that’s not the point!
  • It’s not clever – It just shows ORMDroid in use – it doesn’t necessarily exemplify best practices, and it has almost zero error handling. Over time it will be updated to at least check the best-practice box.
  • But it’s a start! If nothing else, it gives a template project off which you can base your own.

The second point above probably requires a bit of expansion. We all know that to make robust apps we need to be making reasonable checks for unexpected conditions, so we’ll just gloss over the error-handling aspect. But in terms of best practices, the sample app does all kinds of evil things, like blithely loading arbitrary object graphs into ArrayAdapters. On the UI thread no less. This is obviously not the kind of behaviour we want to endorse.

In fact, the whole point here is clarity – to allow you to see exactly what’s going on in the code with the minimum of fuss and boilerplate framework code. We’re trying to make it easy for you to look at a method and see exactly where the ORMDroid calls are happening, without having to wade through any number of AsyncTasks, adapters, and all that other stuff.

In the future, there will be more sample code (maybe as extensions to the current sample, or maybe as additional samples) that will serve to show how things should be done. For now though, take this code more as an example simply that things can be done.

A few bugfixes

While putting together the sample app, I found a few bugs in ORMDroid that are now fixed in SVN. If you’ve tried ORMDroid and experienced any of the following issues, you should grab a fresh copy:

  • Problems with models with only one field.
  • Problems when using ORMDroidApplication as your main Application class.
  • Problems with debugging SQL executed from EntityMapping.
  • Problems with executeMulti not ensuring the schema existed.
  • Problems with Query operators (lt, gt, and, or, etc).

Of course, if you’ve been experienced issues other than these, then you should get in touch and let us know!


Git on Dropbox

People have been doing this for ages, but I’m a bit late to the Dropbox (if you don’t have it yet, here’s my referral link) party and have only been using it for a little while (only since I got a One X which had a tie-in deal going with HTC Sense and Dropbox) so it was nice to stumble across this blog article today while looking around for a free way to host private git repositories off-site.

The long and the short of it is that you create a remote repo in your dropbox directory, and then it just follows you everywhere you go. I have to say, I love how easy git makes all this. We’re still using Subversion for “the work stuff” but the day can’t be far off when we migrate over to git…

ORMDroid on Google Code

Further to my previous post, I spent a bit of time today getting the ORMDroid project set up on Google Code (Edit: Moved to Github), including adding a bit of sample code to get you going with the library. I’m also working on extracting a simple sample project that will also go in the repository, which will serve as a proof of concept, a working example, and a functional testbed all in one.

Getting up and running with ORMDroid is really simple. Firstly, you need to add a single XML tag to your AndroidManifest.xml (it should be a child of the Application tag):

    android:value="your_database_name" />

Next, you need to initialize the framework somewhere. Application.onCreate() is the logical choice if you’re using a custom Application class (configured in your manifest – see Google’s JavaDocs if you want to go this route), but  you can happily call this from pretty much anywhere – even your activity’s onCreate() – since there’s actually no penalty for calling the initialize method multiple times.


Side note: Currently, ORMDroidApplication is itself a subclass of android.app.Application, so you could go down the route of setting it directly as your application class, or subclassing it with your custom behaviour, and have the initialization handled transparently for you. However, this isn’t the recommended way, and it’s possible this facility will be removed in future versions.

With the framework initialized, you can start loading and saving your models! These are just plain Java POJOs that subclass the ORMDroid Entity class. If you’re happy with the default table and column names provided by the framework, these can be as simple as:

package com.example.myapp;

import com.roscopeco.ormdroid.Entity;

public class Person extends Entity {
  public int id;
  public String name;
  public String telephone;

Working with the Person class is now as simple as:

Person p = Entity.query(Person.class).where("id").eq("1").execute();
p.telephone = "555-1234";  // for example...

And that’s it. No, really, it’s that simple. You don’t have to worry about setting up the database, ensuring tables are created, transaction management, or any of that other stuff. Of course, you can handle the database yourself if you really want to, but ORMDroid is more than happy to take care of it for you if you’ll let it.

The entity class in the example above will be stored in the following table:


If you aren’t happy with this default mapping, you can use the Table and Column annotations to customize things, e.g:

package com.example.myapp;

import com.roscopeco.ormdroid.Entity;
import com.roscopeco.ormdroid.Table;
import com.roscopeco.ormdroid.Column;

public class Person extends Entity {
  @Column(name="person_id", primaryKey=true)
  public int id;

  public String name;

  public String telephone;

A couple of things to note here are that the primaryKey parameter is actually redundant, since id would be used as a primary key in the absence of another field that has primaryKey=true, and that, and that you don’t have to annotate all the columns – only those you want to change the default mapping for.

And that’s it. You’re up and running with ORMDroid! Obviously this example code is very simple, and misses out probably the most important point with using an ORM framework – relationships. You can play with this yourself though – create another entity class, and give it a Person field. By default, whenever you persist your new class the related Person will be persisted as well. One-to-one relationships are already supported, and it’s easy to add helper methods to support many relationships using the query facilities provided by Entity. We’ll take a detailed look at relationships at a later date (this post is already long enough), but for now take a look at the code and I guarantee you’ll pick it up in no time anyway.

Introducing ORMDroid

Another year, another blog…

Actually, I’ve been out of the blogging cycle for a year or two now, as I’ve just been too busy with work to really dedicate any time to open source and my own projects, but a recent (positive!) change in my  work schedule means I’m now back and able to invest some time again.

Over the past couple of years I’ve been furiously developing solutions for a variety of clients, and in that time I’ve amassed a few different chunks of code that stand alone well enough, and are potentially generally useful enough, to be open sourced. Now I finally have some time, I’m going to start getting them out there, and hopefully get enough interest to get other developers involved.

So the first project, provisionally named ORMDroid, is an Object Relational Mapping framework for the Android platform. It grew (and is still growing) out of a quick (and very basic) solution that was created for a bespoke app a while ago and is still very simple – over time we’ve added features we’ve needed, and no more (well, not much more).

Why write an Android ORM framework? Well, at the time ORM on Android wasn’t served all that well. The two main solutions didn’t fit our needs – ORMLite just isn’t, well, lite enough, and ActiveAndroid‘s licensing doesn’t fit in with our ethos. Plus, for what we actually needed at the time it was fairly simple to hammer together a solution, which has grown since then through various iterations into the ORMDroid framework we’re using (and now open-sourcing) today.

The name may change soon (ORMDroid is just an internal name, and it turns out there’s already a project on Google code called ORMDroid, although it’s currently empty) and the API is certain to change, but right now it’s capable of managing very simple persistence mapping automatically for you. We’ve found it to be quite capable, and especially useful for getting database driven apps up and running quickly when the client just won’t wait!

The project has just found it’s way onto Google code (it’s at http://code.google.com/p/orm-droid/) and is currently source-only, but if you’re interested in ORM on the android platform come on over and take a look at the code (We’re using subversion as it’s fits with what we use in the lab). It’d be great to get any feedback, and even better to get some people involved.

Project page: http://code.google.com/p/orm-droid/
ource browser: http://code.google.com/p/orm-droid/source/browse/


Blog about the TTL based CPU design we're making

Don Charisma

because anything is possible with Charisma

Tech Filled Fantasy

One stop shop for all your tech-filled pleasures!