Room Persistence Library

Android Architecture Components 基本介紹和使用方式見，Android架構元件

Room提供了一個抽象層，允許流暢的訪問SQLite資料庫，全面強大的直接SQLite。
Android框架提供了支援原始SQL內容的內建支援。雖然這些API是強大的，但是水平相當低，需要大量的時間和精力使用：
原始SQL查詢沒有編譯時驗證。由於資料圖表的更改，需要手動更新受影響的sql查詢。這個過程是費時和容易出錯的。
你需要使用大量的樣板程式碼的SQL查詢和java資料物件之間的轉換。

Room為了解決這些問題在SQLite提供一個抽象層。
Room有3個主要組成部分：

• Database: 可以使用此元件建立資料庫 holder，註釋定義實體列表，和類的內容定義資料訪問物件（DAO）資料庫中的表。它也是基本連線的主要訪問點。
• Entity: 實體類物件模型，一般一對一對應表結構。實體的每個欄位在資料庫中都是儲存的，除非你用@Ignore 註解。
• DAO: 資料庫操作介面，一般一對一對應表的相關操作
  這些元件，以及它們與應用程式其餘部分的關係，如圖所示：

Entity

User.java

//@Entity用來註解一個實體類，對應資料庫一張表
@Entity
public class User {
    //@PrimaryKey 主鍵
    @PrimaryKey
    private int uid;
    //@ColumnInfo 對應的資料庫的欄位名成
    @ColumnInfo(name = "first_name")
    private String firstName;

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

    // Getters and setters are ignored for brevity,
    // but they're required for Room to work.
}

預設情況下，Room為實體中定義的每個成員變數在資料中建立對應的欄位，我們可能不想儲存到資料庫的欄位，這時候就要用道@Ignore註解

@Entity
class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

注意：為了儲存每一個欄位，這個欄位需要有可以訪問的gettter/setter方法或者是public的屬性

Entity的引數 primaryKeys

每個實體必須至少定義1個欄位作為主鍵,即使只有一個成員變數，除了使用@PrimaryKey 將欄位標記為主鍵的方式之外，還可以通過在@Entity註解中指定引數的形式

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

    @Ignore
    Bitmap picture;
}

Entity的引數 tableName

預設情況下，Room使用類名作為資料庫表名。如果你想表都有一個不同的名稱，就可以在@Entity中使用tableName引數指定

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

---

和tableName作用類似； @ColumnInfo註解是改變成員變數對應的資料庫的欄位名成

Entity的引數 indices

indices的引數值是@Index的陣列，在某些情況寫為了加快查詢速度我們可以需要加入索引

@Entity(indices = {@Index("name"), @Index("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;
}

有時，資料庫中某些欄位或欄位組必須是唯一的。通過將@Index的unique 設定為true，可以強制執行此唯一性屬性。下面的程式碼示例防止表有兩行包含FirstName和LastName列值相同的一組：

@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;
}

Entity的引數 foreignKeys

因為SQLite是一個關係型資料庫，你可以指定物件之間的關係。儘管大多數ORM庫允許實體物件相互引用，但Room明確禁止。實體之間沒有物件引用。

不能使用直接關係，所以就要用到foreignKeys（外來鍵）。

@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;
}

外來鍵是非常強大的，因為它允許指定引用實體更新時發生的操作。例如，級聯刪除，你可以告訴SQLite刪除所有書籍的使用者如果使用者對應的例項是由包括OnDelete =CASCADE在@ForeignKey註釋。ON_CONFLICT ： @Insert(onConflict=REPLACE) REMOVE 或者 REPLACE

有時候可能還需要物件巢狀這時候可以用@Embedded註解

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;
}

Dao

UserDao.java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List<User> getAll();

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND "
           + "last_name LIKE :last LIMIT 1")
    User findByName(String first, String last);

    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);
}

資料訪問物件Data Access Objects (DAOs)是一種抽象訪問資料庫的乾淨的方式。

DAO的Insert 操作

當建立DAO方法並用@Insert註釋它時，生成一個實現時會在一個事務中完成插入所有引數到資料庫。

@Dao
public interface MyDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    public void insertUsers(User... users);

    @Insert
    public void insertBothUsers(User user1, User user2);

    @Insert
    public void insertUsersAndFriends(User user, List<User> friends);
}

DAO的Update、Delete操作

與上面的插入類似

@TypeConverte

型別轉換，例如：

public class Converters {
    @TypeConverter
    public static Date fromTimestamp(Long value) {
        return value == null ? null : new Date(value);
    }

    @TypeConverter
    public static Long dateToTimestamp(Date date) {
        return date == null ? null : date.getTime();
    }
}

前面的例子定義了2個函式，一個將Date物件轉換為一個Long物件，另一個Long到Date的逆轉換。因為Room已經知道如何儲存Long物件，所以可以使用這個轉換器來儲存型別Date的值。@TypeConverters的使用

@Database(entities = {User.java}, version = 1)
@TypeConverters({Converter.class})
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}
@Entity
public class User {
    ...
    private Date birthday;
}
@Dao
public interface UserDao {
    ...
    @Query("SELECT * FROM user WHERE birthday BETWEEN :from AND :to")
    List<User> findUsersBornBetweenDates(Date from, Date to);
}

Database

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

在建立上述檔案之後，您將使用以下程式碼獲取建立的資料庫例項：

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

Database migration 資料庫遷移（升級）

版本迭代中，我們不可避免的會遇到資料庫升級問題Room也為我們提供了資料庫升級的處理介面；

Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name")
        .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build();

static final Migration MIGRATION_1_2 = new Migration(1, 2) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, "
                + "`name` TEXT, PRIMARY KEY(`id`))");
    }
};

static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL("ALTER TABLE Book "
                + " ADD COLUMN pub_year INTEGER");
    }
};

遷移過程結束後，Room將驗證架構以確保遷移正確發生。如果Room發現問題，則丟擲包含不匹配資訊的異常。
警告：如果不提供必要的遷移，Room會重新構建資料庫，這意味著將丟失資料庫中的所有資料。

輸出模式

可以在gradle中設定開啟輸出模式，便於我們除錯，檢視資料庫表情況，以及做資料庫遷移。

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = ["room.schemaLocation":
                             "$projectDir/schemas".toString()]
            }
        }
    }
}