This library works as a SQLite wrapper and allows you to easily create, query and work with schemas based on objects. This means you can forget about handling queries and Cursors manually, and work directly with Java classes.

Maven integration

In order to use this library from you Android project using maven your pom should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    <dependencies>
        <dependency>
            <groupId>com.codeslap</groupId>
            <artifactId>persistence</artifactId>
            <version>0.9.23</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

Normal integration

Refer to the downloads section to get a JAR to import to your project.

Get started

Create a class that extends android.app.Application like this:

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        DatabaseSpec database = PersistenceConfig.registerSpec(/**db version**/1);
        database.match(Foo.class, Bar.class);
    }
}

And add this to your manifest:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="your.package.name"
          ...>
    <application ...
                 android:name="your.package.name.App">
     ...

Here Foo and Bar are POJOs that you will use within your app. Persistence library will automatically create sqlite tables for those classes, which will allow you to insert, query, update and delete data easily:

In order to interact with the database, you must get an implementation of the SqlAdapter interface. You can do so this way:

SqlAdapter adapter = Persistence.getAdapter(context);

Inserting/updating data

To insert a simple object to the database use the store method:

// single insertion
Foo foo = new Foo();
// add data to your object foo.setExample(...);
adapter.store(foo);

Notice: if you are inserting an object of type Foo, you must have already registered that class in the Application class.

If you want to store a collection of beans use the storeCollection(list, listener) method:

List<Foo> foos = new ArrayList();
// foos.add(foo);
adapter.storeCollection(null, new ProgressListener() {
    @Override
    public void onProgressChange(int percentage) {
    }
});

This is much more efficient than implementing a loop manually since this will not insert items one-by-one but instead will create a bulk insert statement. There is another version of this method called storeUniqueCollection which basically inserts and updates objects that you pass into the list, and delete from the database those items that are not included in the list.

When you insert an object whose primary key is not auto-increment, it will try to update it instead of inserting a new one. In other cases use the update method:

City sample = new City();
sample.setName("vogota");

City newCity = new City();
newCity.setName("Bogotá");

adapter.update(newCity, sample);

Notice that update method can also be used with raw SQL statements and Android wildcards.

Querying data

You can query single objects or a collection of objects:

// query a single item by example
City city = new City();
city.setName("Bogotá");
City bogota = adapter.findFirst(city);

You can also use raw SQL queries:

City bogota = adapter.findFirst(City.class, "name LIKE 'Bogotá'", null);
// although it is recommended to use Android's wildcards:
City bogota = adapter.findFirst(City.class, "name LIKE ?", new String[]{"Bogotá"});

Use findAll to get a list of objects that matches some conditions:

// Query all cities
List<City> cities = adapter.findAll(City.class);

// Query cities that match a sample
City sample = new City();
sample.setCountryCode("CO");
List<City> colombianCities = adapter.findAll(sample);

// You can set some constraints
Constraint constraint = new Constraint().limit(3).groupBy("column").orderBy("name");
List<City> someCities = adapter.findAll(sample, constraint);

Deleting data

Just use the delete method:

// this will truncate the table...
adapter.delete(City.class, null, null);

// this is a better way to truncate a table...
adapter.truncate(City.class);

// this will delete the items that match the sample
City sample = new City();
sample.setCountryCode("CO");
adapter.delete(sample);

Examples

Looking for examples? You might take a look at Github Jobs app.

Feedback

If you have any questions or suggestions do not hesitate to sending me an email about it (cristian@elhacker.net). Keep in mind that this project is in beta phase and I do not warranty it will work as expected.

casidiablo / persistence

readme