Today I’d like to introduce you to a new library that I’ve been building and using at Qbus in various apps for over a year called Cupboard.
Cupboard is what I’d like to call simple persistence for Android. Most non-trivial apps need some kind of persistance, most likely using a SQLiteDatabase. There are already many libraries and frameworks like ORMLite that are populair choices, but after evaluating most popular options we decided to take a different path.
Background
Basically, I built Cupboard out of frustration with the available options. I don’t like frameworks that take over my code: require me to extend an interface for models or force me in to a global DAO / EntityManager kind of approach. I needed something that I could easily integrate with what Android already gives me. Things like SQLiteDatabase, Cursor, ContentValues. I especially needed something that could work in multiple contexts: passing data from/to a ContentProvider from an Activity for example. None of the options I looked at totally satisfied me in that regard.
For Cupboard I set out to achieve the following goals:
- Persistence of Java Objects, no more ContentValues and Cursor.getColumnIndex()
- Simple and lightweight
- Not a framework, but a library, like syntactic sugar.
- Integrate with core Android classes without any hassle
Let’s also mention what Cupboard isn’t: it isn’t a full fledged ORM solution. For example: while you can hold references to other entities, the relational aspect isn’t managed by Cupboard. This makes things simpler and we haven’t missed it in our apps so far.
How does it look?
An entity is a very simple object, with their field names corresponding to the columns of the table they are stored in. Remember, field access is fast in Android.
public class Person {
public Long _id;
public String name;
public int age
}
Here’s a line of code from a CursorAdapter to bind to a Person object from a cursor
Person person = cupboard().withCursor(cursor).get(Person.class);
Here’s how you’d get a person with id 12 from a SQLiteDatabase:
Person person = cupboard().withDatabase(db).get(Person.class, 12L);
Or using a ContentProvider:
Uri uri = ... // the uri to Person object we want to get
Person person = cupboard().withContext(mContext).get(uri, Person.class);
Note that the cupboard() function is just a helper; it holds the Cupboard instance that knows about your entities. You could inject the instance if you are using a dependency injection framework.
The Cupboard instance doesn’t hold on to your database, it doesn’t manage anything. So if you would need to interact with the cursor in the first case, or the database in the latter case, no problem! Pass in a different database? Sure!
Using Cupboard
Cupboard is Open Source software, Apache Licensed like most Android libraries. You can get it at the project site. Check out the documentation to get started or look at the sample project. You can add it to your project as a simple jar. There’s a pre build jar on the project site as well. The jar includes the source for easy debugging.
I’m curious if you think this is useful to you too. Let me know on Google+ or Twitter!
