Links to source documents

Engineering configuration

implementation "android.arch.persistence.room:runtime:1.0.0"
annotationProcessor "android.arch.persistence.room:compiler:1.0.0"

// RxJava support for Room (use 1.1.0-alpha3 for latest alpha)
implementation "android.arch.persistence.room:rxjava2:1.0.0"

Table definition

Define Entity

By default, Room builds columns for each attribute in a class that uses the @Entity annotation, and ignores an attribute with @Ignore

@Entity
class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

For attributes, Room must be able to use and can be set directly to public, which provides setter/getter methods that use the conventions in JavaBean s when using set/get

Be careful

Use PrimariKey

Each Entity must define at least one PrimaryKey attribute; you can use PrimaryKey's autoGenerate attribute when you want to use Room to automatically define an ID; and you can use Entity's primaryKey attribute if you use a composite primary key

Such as:

@Entity(primaryKeys = {"firstName", "lastName"})
class User {
    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

By default, Room uses class names as table names and can be defined using Entity's tableName

@Entity(tableName = "users")
class User {
    ...
}

Be careful

Similar to tableName, Room uses the name of the attribute as the column name in the table and can be defined with the name of @ColumnInfo

@Entity(tableName = "users")
class User {
    @PrimaryKey
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;

    @Ignore
    Bitmap picture;
}

Annotation Index and Uniqueness

1. If you need to add indexes to speed up queries, you can use the indices attribute in Entity to specify indexes (composite indexes)

   @Entity(indices = {@Index("name"),
           @Index(value = {"last_name", "address"})})
   class User {
       @PrimaryKey
       public int id;
   
       public String firstName;
       public String address;
   
       @ColumnInfo(name = "last_name")
       public String lastName;
   
       @Ignore
       Bitmap picture;
   }

2. Set uniqueness for a single attribute (multiple attributes)

   @Entity(indices = {@Index(value = {"first_name", "last_name"},
           unique = true)})
   class User {
       @PrimaryKey
       public int id;
   
       @ColumnInfo(name = "first_name")
       public String firstName;
   
       @ColumnInfo(name = "last_name")
       public String lastName;
   
       @Ignore
       Bitmap picture;
   }
   

Defining Object Relations

SQLite is a relational database that specifies the relationships between objects. Room prohibits mutual references between entity objects.

Although not directly referenced, Room allows the use of foreign keys

User and Book build relationships through ForeignKey

@Entity(foreignKeys = @ForeignKey(entity = User.class,
                                  parentColumns = "id",
                                  childColumns = "user_id"))
class Book {
    @PrimaryKey
    public int bookId;

    public String title;

    @ColumnInfo(name = "user_id")
    public int userId;
}

For the above code, you can use onDelete = CASCADE in ForeginKey to tell SQLite that when you delete a User, all Book s corresponding to that User will be deleted at the same time.

Be careful

SQLite processing @Insert(onConflict = Replace) has a series of REMOVE and REPLACE operations, not an UPDATE operation. Conflict values in REPLACE operations in this method may affect foreign keys. SQLite documentation

Create nested objects

When a reference object is used as an attribute inside an object, it can be decomposed using @Embedded and stored in the corresponding column again.

class Address {
    public String street;
    public String state;
    public String city;

    @ColumnInfo(name = "post_code")
    public int postCode;
}

@Entity
class User {
    @PrimaryKey
    public int id;

    public String firstName;

    @Embedded
    public Address address;
}

In the user table built by the above code, there are six fields - id, first Name, street, state, city, post_code.

Be careful

Embedded attributes can include other embedded attributes

If there are multiple attributes of the same type in an entity, you can use prefix attributes to indicate uniqueness. Room adds a prefix value before the corresponding attribute