One-to-many in ORMDroid – at last!

I’m pleased to announce that as of this morning, ORMDroid now has some basic support for one-to-many relationships between entities, thanks to Jacob Ferrero and as hinted at in a previous post. Jacob actually put this together a few months ago, the only hold-up has been me getting around to merging the code in, so it’s great that it’s finally done. It’s not in a release yet (later this week is the plan on that) but is available in Git on the master branch.

Jacob explains the changes better than I can, so here’s a quote directly from his original pull request:

Basic usage is like this:

Person.java

class Person extends Entity {
    public String name;

    @Column(inverse = "person")
    public ArrayList<Hobby> hobbies;
}

Hobby.java

class Hobby extends Entity {
    public String type;
    public Person person;
}

And then you would just use it like normal:

Person person = Entity.query(Person).where(eql("name", "Christ")).execute();

for(Hobby hobby : person.hobbies)
    Log.d(TAG, "Hobby found: " + hobby.type);

It’s worth noting that this change does break the API slightly, the most common case being that if you’ve previously used @Column(inverse = true) then you’ll need to migrate to the new form which names the foreign column.

In the unlikely case that you’ve implemented your own type mappings, you’ll also need to make some changes as the public API has changed slightly (there’s a new parameter, precursors, which if you’re not currently using you can safely ignore in your code) and there have been some minor changes under the hood (e.g. in EntityMapping#load) that you’ll need to update your code for.

All in all, some long-overdue positive movement in ORMDroid. We’re definitely moving toward a new release this week, and I promise to be less tardy in the future!

 

 

Advertisements

Just checking in…

Wow, so my last post was September? That’s just not good blogging, and for that I apologise… There’s been a lot going on, but this is no time for excuses – I’m just posting this to let you all know that I’m still here, still writing code (lately, not as much as I’d like, but there you go) and I’m soon going to be making a start on the huge list of Open Source stuff that’s been building up over the past few months. Here are a few highlights of what’s in store:

  • Some awesome new stuff will be going into ORMDroid very soon, with some great contributions from Jacob Ferrero including one-to-many support. I can only apologise to Jacob for the time it’s taking to get these reviewed and merged!
  • Speaking or ORMDroid, it must be about time for that 1.0 release…
  • I’m planning to finally finish up Deelang. It still needs the new parser architecture sorting out, and some bug-fixes, plus some decent documentation. It’s been sitting there for too long, it needs to be pushed out the door!
  • I have some new code to put into Mink, including some rudimentary user-mode bootstrap code, along with a basic round-robin scheduler and other basic bits that will allow development to continue. A lot of this code is written, but still shockingly untested and even-more-shockingly out of version control!

Outside of Open Source, I still have to do something with retroify.me, a fact I was reminded of the other day when the domain name came up for renewal. The annoying thing there is that it’s done – I just need a reasonably-priced swag supplier who can print up cool T-shirts and the like for people to buy (any suggestions much appreciated!). We’ve also got an exciting new venture on the verge of private beta, which we hope to be launching as a commercial product later in the year.

So, all in all, exciting times. Now I just have to actually get on and do all this stuff.

Watch this space.

 

ORMDroid 0.40 released

ORMDroid 0.40 is now available from the releases area on Github. This is the first packaged release since 0.20 almost eleven months ago, and incorporates new features, reworked old features, and bugfixes. There’s a full announcement at the link above.

As well as packaging this release, we’ve now also closed the (legacy) Google Code site for ORMDroid – we’re now 100% Github!

This release marks the last call for major new features for the 1.0 series. If you’ve got any burning issues you’d like us to look at, discuss in the comments or post an issue on Github and we’ll take a look.

Enjoy!

Deelang & ORMDroid: Moving to GitHub

Image representing GitHub as depicted in Crunc...

After spending all their lives so far on Google Code, I’ve decided it’s time to move both Deelang and ORMDroid over to GitHub. The projects have moved away from the old Subversion VCS and are now using Git, and the actual moving of the wiki pages, issues and everything else is well underway.

Why the move? Well, GitHub makes collaboration much more pleasant (Forks and pull-requests vs. patches isn’t much of a contest), and crucially for an Open Source project, a lot more people are comfortable with Git these days than SVN (in the OSS world, at least). Until fairly recently the whole Git thing had passed me by to an extent, but it’s easy to pick up and I have to say it’s now my preferred VCS.

On top of all that, I just prefer the GitHub interface!

Here are the new links to the projects. Please update your references if you have them.

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.

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!

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/