SQLBrite DAO
Dependencies
// DAO
compile 'com.hannesdorfmann.sqlbrite:dao:xxx'
// Object Mapper
compile 'com.hannesdorfmann.sqlbrite:annotations:xxx'
apt 'com.hannesdorfmann.sqlbrite:object-mapper:xxx'
To run annotation processing you have to use apt. Please note that DAO and Object-Mapper are independent. You can choose whether you want to use both or not.
How to use
This library adds an layer on top of SQLBrite by providing basically two modules:
- ObjectMapper
- Dao
ObjectMapper
This project doesn't aim to implement a full ORM framework and will never be. It just uses annotation processing to generate code for reading value from Cursor
and handle ContentValues
. With @Column
you specify with database table column belongs to which field of your Model class. You can annotate fields (no private or protected fields are allowed) or public setter methods. With @ObjectMappable
you have to annotate your model class containnig @Column
annotations like this:
@ObjectMappable
public class Customer {
public static final String TABLE_NAME = "Customer";
public static final String COL_FIRSTNAME = "firstname";
public static final String COL_LASTNAME = "lastname";
public static final String COL_ID = "id";
protected long id;
@Column(COL_FIRSTNAME) String firstname;
@Column(COL_LASTNAME) String lastname;
public Customer() {
}
public Customer(long id, String firstname, String lastname) {
this.id = id;
this.firstname = firstname;
this.lastname = lastname;
}
@Column(COL_ID)
public void setId(int id) {
this.id = id;
}
public long getId() {
return id;
}
public String getFirstname() {
return firstname;
}
public String getLastname() {
return lastname;
}
}
For Customer
a class called CustomerMapper
gets generated that looks like this:
public final class CustomerMapper {
/**
* RxJava Func1 Method that can be used to generate a Customer from a Cursor's data (sql row)
*/
public static final Func1<Cursor, Customer> MAPPER = new Func1<Cursor, Customer>() {
...
}
/**
* Get a typesafe ContentValues Builder
* @return The ContentValues Builder
*/
public static ContentValuesBuilder contentValues() {
...
}
}
So basically it generates a Func1
that can be applied on a SQLBrite QueryObservable
to instantiate your data object (i.e. Customer) out of a Cursor
(cursor gets closed internally and resources released by SQLBrite) and retrieve fetch data by calling cursor.getString(index)
and so on. See DAO section below for a concrete example how to use the generated Func1
. Additionally, it also generates a type safe builder for ContentValues
.
ContentValues cv = CustomerMapper.contentValues()
.id(1)
.firstname("Hannes")
.lastname("Dorfmann")
.build();
The supported types for @Column
are:
- String
- int
- long
- short
- float
- double
- boolean
- byte[]
- java.util.Date (mapped to long internally, time in milli seconds)
Kotlin support
ObjectMapper is supported by Kotlin (use kapt
instead of apt
for annotation processing):
@ObjectMappable
class People {
@Column("name")
var name: String? = null
@Column("age")
var age : Int = 0
}
Unfortunately, data classes are not supported yet.
Auto-Value
The provided Object Mapper does not support Auto-Value. However, there is a nice library called auto-value-cursor that can be used instead of the build in Object Mapper and with the DAO module to achieve the same, just with auto-value.
DAO
Create your own Data Access Object (DAO) where you define methods to manipulate or query your database table. Usually a DAO represents a database table, like the database table for storing Customer
:
public class CustomerDao extends Dao {
@Override public void createTable(SQLiteDatabase database) {
CREATE_TABLE(Customer.TABLE_NAME,
Customer.COL_ID + " INTEGER PRIMARY KEY NOT NULL",
Customer.COL_FIRSTNAME + " TEXT",
Customer.COL_LASTNAME + " TEXT")
.execute(database);
}
@Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
if (oldVersion == 1 && newVersion == 2){
ALTER_TABLE(Customer.TABLE_NAME)
.ADD_COLUMN(Customer.PHONE_NUMBER +" TEXT")
.execute(db);
}
}
...
}
onCreateTable()
and onUpgrade()
gets called internally (from an internal SQLiteOpenHelper
) to create or migrate the table for Customer
.
As you already have seen above, the DAO provides provides a high level API so you don't have to deal that much with String concatenation and can use IDE's auto completion to build your sql statements. The same API can be used to create SQL query statements:
public class CustomerDao extends Dao {
@Override public void createTable(SQLiteDatabase database) {
...
}
@Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
...
}
public Observable<List<Customer>> getCustomers(String lastname) {
return query(
SELECT(Customer.COL_ID, Customer.COL_FIRSTNAME, Customer.COL_LASTNAME)
.FROM(Customer.TABLE_NAME)
.WHERE(Customer.COL_LASTNAME + " = ? ")
)
.args(lastname) // arguments that replace the "?" placeholders in SQL statement
.run() // Executes query
.mapToList(CustomerMapper.MAPPER) // Use the generated Func1 method
);
}
public Observable<Long> addCustomer(int id, String firstname, String lastname) {
ContentValues values = CustomerMapper.contentValues()
.id(id)
.firstname(firstname)
.lastname(lastname)
.build();
return insert(Customer.TABLE_NAME, values);
}
}
To register your DAO classes to SQLBrite
you have to create a DaoManager
. While a Dao
represents a table of a database DaoManager
represents the whole database file. DaoManager
internally creates a SQLiteOpenHelper
and instantiates a SqlBrite
instance. All DAO's registered to the same DaoManager
share the same SqlBrite
instance.
CustomerDao customerDao = new CustomerDao();
AddressDao addressDao = new AddressDao();
DaoManager daoManager = DaoManager.with(context)
.databaseName("Customers.db")
.version(1)
.add(customerDao)
.add(addressDao)
.logging(true)
.onTablesCreated(createdListener) // optional callback
.onTablesUpgraded(upgradedListner) // optional callback
.build();
Please note that adding DAO's dynamically (later) is not possible. You have to instantiate a DaoManager
and pass all your DAO's in the constructor as seen above.
To sum up:
- A
DaoManager
is representing the whole database file and basically is aSQLiteOpenHelper
and managesSqlBrite
instance for you. - A
Dao
is representing a table of a database. You define a public API for other software components of your App likegetCustomers()
oraddCustomer()
to query and manipulate the data of the underlying table.
License
Copyright 2015 Hannes Dorfmann
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.