Room

A SQLite object mapping library.

Room provides an object-mapping abstraction layer that allows fluent database access while harnessing the full power of SQLite to store data locally. This allows caching of data for offline access and improved performance of online apps.

Room is an abstraction layer over SQLite that provides:

• Compile time verification of RAW SQL queries, errors caught at compile time instead of runtime
• Automatic updates to SQL queries as scheme changes via data observation with LiveData or RxJava
• Remove boilerplate in transforming SQL queries and Java Objects, removes need to use low level contentValues and cursors.

Note: By default, Room doesn't allow you to issue database queries on the main thread to avoid poor UI performance.

Room has an extremely handy feature for when you want to have a LiveData object that stays in sync with whatever is in the database - Room can return LiveData wrapped objects. This LiveData will trigger its' observers any time the database data changes. It even loads this database data off of the main thread for you.

Database, Entity, and DAO

Room uses annotiations to define database structures. The major components of Room are:

• Database
  is a holder class that uses annotations to define the list of entities and database version. The class content defines the list of DAOs. It's also the main access point for the underlying database connection. Used to create a new database and acquire a connection to the database at runtime.

• Entity
  represents the data for a single database row, constructed using an annotated Java data object. Each Entity is persisted into its own table. Provides an API for reading and writing to database.

• DAO
  (Data Access Object) an abstract class or interface that defines the methods that access the database, using annotations to bind SQL to each method. Defines database queries and helps to reduce boilerplate. SQL generated and validated at compile time.

To use Room, you annotate the Java data objects you wish to persist as entities, create a database containing these entities, and define a DAO class with the SQL to access and modify the database.

@Entity
public class User {
    @PrimaryKey
    private int uid; 
    private String name;

    // Getters and Setters - required for Room
    public int getUid() { return uid; }
    public String getName() { return name; }
    public void setUid(int uid) { this.uid = uid; }
    public void setName(String name) { this.name = name; }
}

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List getAll();
    @Insert
    void insertAll(User... users);
}

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

To get an instance of the Database use the following as a singleton:

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

Adding Room To A Project

Add Room library to a project:

build.gradel(Project: project)

allprojects {
    repositories {
        jcenter()
        maven { url 'https://maven.google.com' }
    }
}

build.gradle(Module: app)

compile "android.arch.persistence.room:runtime:1.0.0-alpha9"
annotationProcessor "android.arch.persistence.room:compiler:1.0.0-alpha9