ORMDroid 0.20 now available

ORMDroid 0.20, the first packaged release of the ORM framework for android, is now available from the project downloads page on Google Code. This first release packages up the Android library ADT project, adds some documentation (which you can view online here), and makes it easy to grab and go if you don’t like to/want to work with the Subversion repository.

In case you missed it, you can read more about ORMDroid here, here and here.

Advertisements

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):

<meta-data
    android:name="ormdroid.database.name"
    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.

ORMDroidApplication.initialize(someContext);

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...
p.save();

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:

CREATE TABLE comexamplemyappPerson (id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR, phone VARCHAR);

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;

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

  @Column(name="fullname")
  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/
S
ource browser: http://code.google.com/p/orm-droid/source/browse/