前言
本文档是以demo为例介绍，所以部分内容和解释会在demo里以注释的形式给出。
数据库的构建
环境配置
在app模块的build.gradle添加以下内容：
compile 'android.arch.lifecycle:extensions:1.0.0-alpha5'
compile 'android.arch.lifecycle:runtime:1.0.0-alpha5'
compile 'android.arch.persistence.room:runtime:1.0.0-alpha5'
testCompile 'junit:junit:4.12'
annotationProcessor 'android.arch.lifecycle:compiler:1.0.0-alpha5'
annotationProcessor "android.arch.persistence.room:compiler:1.0.0-alpha5"
//数据库迁移的时候使用
compile "android.arch.persistence.room:testing:1.0.0-alpha5"
在项目的build.gradle中添加
allprojects {
repositories {
jcenter()
maven {
url "https://dl.google.com/dl/android/maven2/"
//官方给出的链接是maven.google.com，但是这个网站连不上
}
}
}
entity
当一个类用@Entity注解并且被@Database注解中的entities属性所引用，Room就会在数据库中为那个entity创建一张表。
默认Room会为entity中定义的每一个field都创建一个column。如果一个entity中有你不想持久化的field，那么你可以使用@Ignore来注释它们，在项目的db/entities目录下：
student.java
//也可以使用组合主键，使用@Entity注解的primaryKeys属性
//@Entity(primaryKeys = {"firstName", "lastName"})
//也可以使用索引或者组合索引
//@Entity(indices = {@Index("name"), @Index("name", "student_id")})
@Entity(tableName = Student.TABLE_NAME)
public class Student {
//静态成员并不会被转换为数据库中的条目
/** 表名 */
public static final String TABLE_NAME = "students";
public static final String COLUMN_NAME = "student_name";
public static final String COLUMN_ID = "student_id";
//每个表必须要有一个主键
@PrimaryKey
@ColumnInfo(index = true, name = COLUMN_ID)
private long uid;
//自己定义列名
@ColumnInfo(name = COLUMN_NAME)
private String name;
private int age;
private String subject;
@Ignore
Bitmap picture;
...
}
DAOs
dao文件中主要存放对数据库的操作，在项目的db/dao目录下
StudentDao
@Dao
public interface StudentsDao {
@Insert(onConflict = OnConflictStrategy.REPLACE)
void insertAll(List<Student> students);
//如果@Insert方法只接收一个参数，它可以返回一个long，代表新插入元素的rowId
//如果参数是一个数组或者集合，那么应该返回long[]或者List。
@Insert
long insert(Student student);
//可以返回一个int类型的值，表示从数据库中被删除的行数，虽然通常并没有这个必要
@Delete
void delete(Student student);
@Query("DELETE FROM " + Student.TABLE_NAME + " WHERE " + Student.COLUMN_ID + " = :id")
int deleteById(long id);
//返回一个int类型的值，表示更新影响的行数，虽然通常并没有这个必要
@Update
int update(Student student);
@Update
void updateAll(List<Student> students);
@Query("SELECT * FROM " + Student.TABLE_NAME)
Cursor getAll();
@Query("SELECT * FROM " + Student.TABLE_NAME + " WHERE " + Student.COLUMN_ID + " = :id")
Student findById(long id);
@Query("SELECT * FROM " + Student.TABLE_NAME + " WHERE student_name LIKE :name")
Student findByName(String name);
@Query("SELECT * FROM " + Student.TABLE_NAME + " WHERE " + Student.COLUMN_ID + " IN (:uids)")
List<Student> loadAllByIds(long[] uids);
//如果app需要获得直接返回的行，你可以在查询中返回Cursor对象
@Query("SELECT * FROM " + Student.TABLE_NAME + " WHERE " + Student.COLUMN_ID + " = :id")
Cursor selectById(long id);
}
Database
你可以用这个组件来创建一个database holder。注解定义实体的列表，类的内容定义从数据库中获取数据的对象（DAO）。它也是底层连接的主要入口。
这个被注解的类是一个继承RoomDatabase的抽象类。在运行时，可以通过调用Room.databaseBuilder() 或者 Room.inMemoryDatabaseBuilder()来得到它的实例。
在项目的db/database
//entities表示把这几张表放入数据库
@Database(entities = {Student.class,Subject.class},version = 1)
//表示在这个数据库中使用类型转换器
@TypeConverters(DateConverter.class)
public abstract class AppDatabase extends RoomDatabase{
@SuppressWarnings("WeakerAccess")
public abstract StudentsDao studentsDao();
public abstract SubjectsDao teachersDao();
public static final String DATABASE_NAME = "roomTest-db";
}
数据的初始化与获取数据库
这部分操作在 db目录下的DatabaseCreator.java与DatabaseInitUtil.java.
前者是用于创建数据库，核心代码就这一句
// 构建数据库
AppDatabase db = Room.databaseBuilder(context.getApplicationContext(),
AppDatabase.class, DATABASE_NAME).build();
但是注意需要用单例的方式获取。
后者主要完成在创建数据库的时候插入一些初始数据，不多做介绍。
与contentProvider的结合
因为现有的项目有可能是使用contentProvider的，那么为了减少整合代价可以更改ContentProvider，即将内部的各种查找以Dao中方法来实现，dao中可以返回cursor也是为了应付这种情况。
在项目的provider目录下：
SimpleContentProvider
//截取一个方法为例
@Nullable
@Override
public Cursor query(@NonNull Uri uri, @Nullable String[] projection, @Nullable String selection,
@Nullable String[] selectionArgs, @Nullable String sortOrder) {
final int code = MATCHER.match(uri);
if (code == CODE_STUDENT_DIR || code == CODE_STUDENT_ITEM) {
final Context context = getContext();
if (context == null) {
return null;
}
//获取数据库
AppDatabase db = DatabaseCreator.getInstance(context).getDatabase();
//获取dao
StudentsDao studentsDao = db.studentsDao();
final Cursor cursor;
if (code == CODE_STUDENT_DIR) {
//执行查询，可以看到实际上使用的还是dao中的方法
cursor = studentsDao.getAll();
} else {
cursor = studentsDao.selectById(ContentUris.parseId(uri));
}
cursor.setNotificationUri(context.getContentResolver(), uri);
return cursor;
} else {
throw new IllegalArgumentException("Unknown URI: " + uri);
}
}
...
类型转换器
Room内置了原始类型。但是，有时你会希望使用自定义数据类型。 要为自定义类型添加这种支持，可以提供一个TypeConverter，它将一个自定义类转换为Room保留的已知类型。
先定义一个类型转换器,db/convert目录下：
DateConvert.java
public class DateConverter {
//将从Long到Date转换为执行逆转换
@TypeConverter
public static Date toDate(Long timestamp) {
return timestamp == null ? null : new Date(timestamp);
}
//将Date对象转换为Long对象
@TypeConverter
public static Long toTimestamp(Date date) {
return date == null ? null : date.getTime();
}
}
然后在AppDatebase上加一句
@TypeConverters(DateConverter.class)
然后就可以直接在查询语句里面用date
StudentsDao.java
//类型转换器可以直接查询date
@Query("SELECT * FROM students WHERE birthday BETWEEN :from AND :to")
List<Student> findUsersBornBetweenDates(Date from, Date to);
这时你对数据库的所有Date类型的查询都会被自动转换为long类型。
查询的结果如果是long类型，可以直接返回Date。
数据库的迁移
随着app功能的添加和修改，你需要修改entity类来反应这些变化。当一个用户更新了app的最新版本之后，你并不希望它们丢失所有的现有数据，尤其是当你无法通过远程服务器恢复这些数据的时候。
Room让你可以让你写Migration类来保存用户数据。每个Migration类指定from和to版本。运行时Room运行每个Migration类的 migrate() 方法，使用正确的顺序把数据库迁移到新版本。
注意：注意：如果你没有提供必要的migration，Room将重建数据库，也就是说数据库中的所有数据都会丢失。
room数据库的迁移
在项目的utils目录下
DataMigrationUtils
//迁移数据库
//Migration的两个参数分别是起始版本和最终版本
public static final Migration MIGRATION_1_2 = new Migration(1, 2) {
@Override
public void migrate(SupportSQLiteDatabase database) {
database.execSQL("ALTER TABLE students "
+ " ADD COLUMN grade INTEGER");
}
};
需要注意的一点是，Migration类可以同时处理超过一个版本的迁移，比如room打开的一个版本号为3的数据库但是最新的版本号是5，那么如果提供了3到5的迁移方法，room就不会去调用3到4然后4到5的方法。
但是如果你在两个版本之间没有提供迁移方法，哪怕数据库没改，那room也会去清空原有数据库然后新建一个。
迁移方法写好之后在其他地方调用它：
Room.databaseBuilder(getApplicationContext(), AppDatabase.class, DATABASE_NAME)
.addMigrations(MIGRATION_1_2).build();
可以通过一个方法看到数据库的改变，在build.gradle里加上这些：
android {
...
defaultConfig {
...
javaCompileOptions {
annotationProcessorOptions {
arguments = ["room.schemaLocation":
"$projectDir/schemas".toString()]
}
}
}
}
就会在app目录下生成一个schemas文件夹，里面有json文件，文件名代表着版本号。
打开可以看见：
这样就可以直观的看到数据库有没有更改成功~
从原生sqlite到room的迁移
和room不同版本的迁移没什么区别，毕竟本质上都是对sqlite的操作，但是同样要注意版本号的问题。
其他
json转化成实体是否与entity冲突
并不冲突，写一个测试方法：
public static void gsonTest(){
Gson gson = new Gson();
Student student = new Student();
student.setUid(1234);
student.setSubject("语文");
student.setName("kevin");
student.setGrade(98);
student.setAge(13);
student.setBrithday(new Date(2000,1,1));
String temp = gson.toJson(student);
Log.d("GSON TEST",temp);
Student student1 = gson.fromJson(temp,Student.class);
Log.d("GSON TEST","name:"+student1.getName() +" subject:"+ student1.getSubject()+ " age:"+student1.getAge()
+" grade:"+student1.getGrade()+" id:"+student1.getUid()+" birthday:"+student1.getBrithday());
}
同时在Student类上加上注解
@SerializedName("gson_student_name")
@ColumnInfo(name = COLUMN_NAME)
private String name;
测试结果：
正常运行，注解也正常运行。
