Storm

Android SQLite manager

Introduction

Although there are letters [ORM] in title of this library it's not really an ORM. Mostly because there are no object relations out of box (but still it could be done, more on this later). Think of it as an echanted helper for working with SQLite database on Android. At almost no price you get:

Easy table creation via @Annotations
Easy migration via @Annotations
Nearly native SQLite speed at inserting, updating and selecting operations
No need to parse Cursors by hand / No need to init ContentValues by hand
Straight-forward API
Support for multiple database files
Any Object could be a model, no need to extend or implement anything
Easy serialization/deserialization of not supported by SQLite types
Android-orientired library

Performance

This repo contains the performance_test project (it has nothing to do with tests). It's more of a benchmark. With it you could measure the performance from currently popular Android ORMs (including raw SQLite) on your device. Check the project folder for the apk with already compiled project. On my Nexus 5 I get the following results:

Insert 10000 Query 10000

Getting started

compile 'ru.noties:storm:1.0.3' // check for latest version in this repo's releases tab

Table creation

Supported annotations during table creation:

@Column
@PrimaryKey
@Autoincrement
@DBNonNull
@Unique
@Index
@Default
@ForeignKey

Supported fields' types:

boolean (note, that it's represented as int (1 or 0, don't forget that if you are doing some selection by this field) (also think of suppling @Default("0") or @Default("1") for this type)
short
int
long
float
double
byte[]
String
and any other type that has registered TypeSerializer

@Table("my_super_table")
public class MySuperTable {

    @Column
    @PrimaryKey
    @Autoincrement
    private long id;

    @Column
    @DBNonNull
    private String otherColumn;

    @Column
    @Unique
    private int kindOfId;

    @Column
    @Index("my_super_table_date_index")
    private long date;

    @Column("other_title_for_this_column")
    @Default("0")
    private int color;

    @Column("id_of_other_table")
    @ForeignKey(
        parentTable = OtherTable.class,
        parentColumnName = OtherTable.COL_ID,
        onDelete = ForeignKeyAction.CASCADE,
        onUpdate = ForeignKeyAction.NO_ACTION
    )
    private long idOfOtherTable;

    @Column("some_column_that_has_registered_type_serializer")
    private SomeObject serializedObject;
}

Table migration

Supported annotations during table migration:

@NewTable
@NewColumn

@Table("new_table_for_version_2")
@NewTable(2)
public class MySuperNewTable {
    // the same as table creation
}

@Table("my_old_table_that_need_refreshement")
public class OldTableThatNeedRefreshment {

    // some columns

    @Column
    @NewColumn(2)
    private String newData;

    @Column
    @Index("new_column_index_name")
    @Unique
    @NewColumn(2)
    private long date;
}

Initialization

The main entry point for initialization is

Storm.getInstance().init(Context applicationContext, boolean isDebug);

This method should be called only once (the second time it will throw an Exception). So, the best place to call it is in your Application's onCreate() method. This will NOT open any connections, just establish required linking for library's fuctionality.

Additionally, during initialization you could supply an InstanceCreator or TypeSerializer.

InstanceCreator

By default all objects are constructed via ReflectionInstanceCreator. It almost has no performance penalty, but still if you wish to smooth things a little or if your model object has no spare empty constructor please use the following:

final Storm storm = Storm.getInstance();
storm.registerInstanceCreator(SampleObject.class, new InstanceCreator<SampleObject>() {
    @Override
    public SampleObject create(Class<SampleObject> clazz) {
        return new SampleObject();
    }
});

TypeSerializer

By default if field's type is not supported by SQLite it won't be in a table. But if you supply a TypeSerializer things change.

final Storm storm = Storm.getInstance();
storm.registerTypeSerializer(Date.class, new LongSerializer<Date>() {
    @Override
    public Date deserialize(long value) {
        return new Date(value);
    }

    @Override
    public long serialize(Date value) {
        return value.getTime();
    }
});

There are 8 abstract serializers for each SQLite supported type:

BooleanSerializer (INT) (well, there is no such type BOOL is SQLite, but still)
ShortSerializer (INT)
IntSerializer (INT)
LongSerializer (INT)
FloatSerializer (REAL)
DoubleSerializer (REAL)
StringSerializer (TEXT)
ByteArraySerializer (BLOB)

These open a possibility to store in any column nearly any type of object. Although it is supposed to be a very bad practice, you could use, for example, JSON to store complex short-lived objects, or Kryo. Of cause it could be used for good, for example, to query and parse object from other table:

final Storm storm = Storm.getInstance();
storm.registerTypeSerializer(OtherTable.class, new LongSerializer<OtherTable>() {

  private final DatabaseManager mManager;
  {
      mManager = getManager();
  }

  @Override
  public OtherTable deserialize(long value) {
    return Storm.newSelect(mManager).query(OtherTable.class, Selection.eq(OtherTable.COL_ID, value));
  }
  @Override
  public long serialize(OtherTable value) {
    return value.getId();
  }
});

(TODO maybe this fuctionality should be implemented in library itself)

Preparing database for using

The main class to work with database is DatabaseManager. You pass it's instance to every database operation (insert, update, delete, select). This gives a possibility to use as much database files as one wishes.

final DatabaseManager manager = new DatabaseManager(
    Context applicationContext,
    String databaseName,
    int databaseVersion,
    Class<?>[] arrayOfClassesThatThisConcreteDatabaseHas // see table creation
);

Additionally you could supply DatabaseManage's constructor a Pragma object, that will evaluate pragma statements on SQLite database connection opened:

final Pragma pragma = new Pragma.Builder()
    .setSynchronous(Synchronous.FULL)
    .setForeignKeys(ForeignKeys.ON) // this is crucial if you are using foreign keys
    .setJournalMode(JournalMode.TRUNCATE)
    .setTempStore(TempStore.DEFAULT)
    .setCustomPragmas(List<String> customPragmas)
    .build();

On DatabaseManager construction it will build it's own cache for classes that are in this database. It might be wise to call it off the main thread if you have a lot of tables with a lot of columns. Still you could share DatabaseManager instance between different threads although it has no inner synchronization whatsoever. Read more about how SQLite synchronizes on Android and prefer as less open SQLite database connections as possible.

Under the hood DatabaseManager holds a SQLiteDatabase reference. So you should call open() to start really using it.

manager.open();

Additionally you could catch SQLiteException duting method call:

try {
    manager.open();
} catch (SQLiteException e) {
    // there was an error during opening
    manager = null;
}

Even more you could supply you own SQLiteOpenCallbacks to the open() method to be executed during onCreate(), onUpgrade(), onOpen() of SQLiteDatabase:

manager.open(new SQLiteOpenCallbacks() {
  public void onCreate (SQLiteDatabase db) {}
  public void onUpgrade (SQLiteDatabase db, int oldVersion, int newVersion) {}
  public void onOpen (SQLiteDatabase db) {}
});

Now you are all set and ready to go.

SQLite operations

INSERT

try {
    Storm.newInsert(mManager).insert(list, boolean shouldNotify *true, boolean setPrimaryKey *false); // * - optional
} catch (StormException e) {
    e.printStackTrace();
}

For more information refer to ru.noties.storm.op.Insert javadoc

UPDATE

try {
    Storm.newUpdate(mManager).update(list, boolean shouldNotify *true, boolean setPrimaryKey *false); // * - optional
} catch (StormException e) {
    e.printStackTrace();
}

For more information refer to ru.noties.storm.op.Update javadoc

DELETE

try {
    Storm.newDelete(mManager).deleteAll(SomeTable.class, boolean shouldNotify *true); // * - optional
} catch (StormException e) {
    e.printStackTrace();
}

For more information refer to ru.noties.storm.op.Delete javadoc

SELECT

@Nullable final SomeTable table = Storm.newSelect(mManager).query(SomeTable.class, Selection.eq("id", 5));

For more information refer to ru.noties.storm.op.Select javadoc

Selection

Supported selections:

Selection.eq(); // ' = '
Selection.neq(); // '!='
Selection.in(); // ' IN ([])'
Selection.btw(); // ' BETWEEN (_int_ AND _int_)'
Selection.b(); // ' > '
Selection.be(); // ' >= '
Selection.l(); // ' < '
Selection.le(); // ' <= '

Selections could be chained:

final Selection root = Selection.empty();
root.grp(Selection.eq("id", 5).or(Selection.neq("column", 13)));
root.and(Selection.b("column2", 1001));

License

  Copyright 2015 Dimitry Ivanov (mail@dimitryivanov.ru)

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

noties / Storm

readme