Android LitePal库详解

一、GitHub

1、GitHub：链接

二、LitePal简介

LitePal 是一个开源 Android 库，它允许开发人员极其轻松地使用 SQLite 数据库。无需编写SQL语句即可完成大部分数据库操作，包括创建或升级表、crud操作、聚合函数等。 LitePal的设置也非常简单，不到5分钟就可以将其集成到你的项目中分钟。

三、LitePal特征

• 使用对象关系映射 (ORM) 模式。
• 几乎零配置（只有一个配置文件，属性很少）。
• 自动维护所有表（例如创建、更改或删除表）。
• 支持多数据库。
• 用于避免编写 SQL 语句的封装 API。
• 很棒的流畅查询 API。
• 仍然使用 SQL 的替代选择，但比原始 API更简单、更好。

四、配置

1.添加 LitePal 库

在build.gradle文件添加以下依赖项。

dependencies {
    implementation 'org.litepal.guolindev:core:3.2.3'
}

2.创建 litepal.xml 文件

在main文件夹中创建assets文件夹，并在assets文件夹中创建一个文件，并将其命名为litepal.xml。然后把下面的代码复制进去。

<?xml version="1.0" encoding="utf-8"?>
<litepal>
    <!--
    	定义应用程序的数据库名称。
    	默认情况下，每个数据库名称应以.db结尾。
    	如果没有将数据库的结尾命名为.db，LitePal会自动为你添加后缀。
    	例如：
    	<dbname value="demo" />
    -->
    <dbname value="NewFriend" />

    <!--
    	定义数据库的版本。每次升级数据库时，版本标签都会有所帮助。
    	修改你在mapping标签中定义的模型，只需将版本值加上一，数据库的升级将自动进行，无需担心。
    	例如：
    	<version value="1" />
    -->
    <version value="1" />

    <!--
    	在带有映射标记的列表中定义模型，LitePal将为每个映射类创建表。
    	模型中定义的受支持字段将映射到列中。
    	例如：
    	<list>
    		<mapping class="com.test.model.Reader" />
    		<mapping class="com.test.model.Magazine" />
    	</list>
    -->
    <list>
    	<mapping class="com.test.model.NewFriend" />
    </list>

    <!--
        定义.db文件应位于的位置。
        “internal”是指.db文件将存储在任何人都无法访问的internal storage的数据库文件夹中。
        “external”是指.db文件将存储在主外部存储设备上的目录路径中，应用程序可以将其拥有的所有人都可以访问的持久文件放置在该目录中。
        “internal”将作为默认值。
        例如：
        <storage value="external" />
    -->

</litepal>

这是唯一的配置文件，属性简单。

• dbname：配置项目的数据库名称。
• version：配置数据库的版本。每次要升级数据库，加这里的值。
• list：配置映射类。
• storage：配置应该存储数据库文件的位置。internal和external是唯一有效的选项。

3. 配置 LitePalApplication

你不想一直传递 Context 参数。为了使 API 变得简单，只需在AndroidManifest.xml 中配置 LitePalApplication如下：

<manifest>
    <application
        android:name="org.litepal.LitePalApplication"
        ...
    >
        ...
    </application>
</manifest>

当然你可能有自己的应用程序并且已经在这里配置好了，比如：

<manifest>
    <application
        android:name="com.example.MyApplication"
        ...
    >
        ...
    </application>
</manifest>

没关系。LitePal 仍然可以接受。只需在你自己的应用程序中调用LitePal.initialize(context)：

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        LitePal.initialize(this);
    }
}

确保尽早调用此方法。在 Application 的 onCreate() 方法中就可以了。并且永远记住使用应用程序上下文作为参数。不要使用任何活动或服务的实例作为参数，否则可能会发生内存泄漏。

五、开始使用

1.创建表

首先定义模型。例如，你有两个模型，Album 和 Song，都继承LitePalSupport 。这些模型可以定义如下：

public class Album extends LitePalSupport {
	
    @Column(unique = true, defaultValue = "unknown")
    private String name;
    
    @Column(index = true)
    private float price;
	
    private List<Song> songs = new ArrayList<>();

    // 生成getter和setter方法。
    ...
}

public class Song extends LitePalSupport {
	
    @Column(nullable = false)
    private String name;
	
    private int duration;
	
    @Column(ignore = true)
    private String uselessField;
	
    private Album album;

    // 生成getter和setter方法。
    ...
}

然后将这些模型添加到 litepal.xml 中的映射列表中：

<list>
    <mapping class="org.litepal.litepalsample.model.Album" />
    <mapping class="org.litepal.litepalsample.model.Song" />
</list>

下次操作数据库时会生成这些表。例如，使用以下代码获取 SQLiteDatabase：

SQLiteDatabase db = LitePal.getDatabase();

现在这些表将使用 SQL 自动生成，如下所示：

CREATE TABLE album (
	id integer primary key autoincrement,
	name text unique default 'unknown',
	price real
);

CREATE TABLE song (
	id integer primary key autoincrement,
	name text not null,
	duration integer,
	album_id integer
);

2. 升级表

在 LitePal 中升级表非常容易。只需修改你的模型即可：

public class Album extends LitePalSupport {
	
    @Column(unique = true, defaultValue = "unknown")
    private String name;
	
    @Column(ignore = true)
    private float price;
	
    private Date releaseDate;
	
    private List<Song> songs = new ArrayList<>();

    // 生成的getter和setter方法。
    ...
}

添加了一个 releaseDate 字段，并注释了 price 字段以忽略。然后在litepal.xml 中增加版本号：

    <!--
    	定义数据库的版本。每次升级数据库时，版本标签都会有所帮助。
    	修改你在mapping标签中定义的模型，只需将版本值加上一，数据库的升级将自动进行，无需担心。
    	例如：
    	<version value="1" />
    -->
    <version value="2" />

下次操作数据库时会升级这些表。album 表中将增加一个 releaseDate 列，并删除原来的 price 列。album 表中除删除的列之外的所有数据都将保留。

但是有一些升级情况是 LitePal 无法处理的，升级表中的所有数据都会被清理：

• 添加一个注释为 的字段 unique = true
• 将字段的注释更改为 unique = true
• 将字段的注释更改为 nullable =false

请注意上述会导致数据丢失的情况。

3. 保存数据

保存 API 是非常面向对象的。从 LitePalSupport 继承的每个模型都将免费拥有 save() 方法。

java：

Album album = new Album();
album.setName("album");
album.setPrice(10.99f);
album.setCover(getCoverImageBytes());
album.save();

Song song1 = new Song();
song1.setName("song1");
song1.setDuration(320);
song1.setAlbum(album);
song1.save();

Song song2 = new Song();
song2.setName("song2");
song2.setDuration(356);
song2.setAlbum(album);
song2.save();

Kotlin：

val album = Album()
album.name = "album"
album.price = 10.99f
album.cover = getCoverImageBytes()
album.save()

val song1 = Song()
song1.name = "song1"
song1.duration = 320
song1.album = album
song1.save()

val song2 = Song()
song2.name = "song2"
song2.duration = 356
song2.album = album
song2.save()

这会将album、song1 和 song2 插入到关联的数据库中。

4. 更新数据

最简单的方法，使用 save() 方法更新 find() 找到的记录。

Java:

Album albumToUpdate = LitePal.find(Album.class, 1);
albumToUpdate.setPrice(20.99f); // 提高价格
albumToUpdate.save();

Kotlin:

val albumToUpdate = LitePal.find<Album>(1)
albumToUpdate.price = 20.99f // 提高价格
albumToUpdate.save()

从 LitePalSupport 继承的每个模型也将具有 update() 和 updateAll() 方法。你可以使用指定的 id 更新单个记录。

Java:

Album albumToUpdate = new Album();
albumToUpdate.setPrice(20.99f); // 提高价格
albumToUpdate.update(id);

Kotlin:

val albumToUpdate = Album()
albumToUpdate.price = 20.99f // 提高价格
albumToUpdate.update(id)

或者你可以使用 where 条件更新多个记录。

Java:

Album albumToUpdate = new Album();
albumToUpdate.setPrice(20.99f); // 提高价格
albumToUpdate.updateAll("name = ?", "album");

Kotlin:

val albumToUpdate = Album()
albumToUpdate.price = 20.99f // 提高价格
albumToUpdate.updateAll("name = ?", "album")

5. 删除数据

可以使用 LitePal 中的静态 delete() 方法删除单个记录。

Java:

LitePal.delete(Song.class, id);

Kotlin:

LitePal.delete<Song>(id)

或者使用 LitePal 中的静态 deleteAll() 方法删除多条记录。

Java:

LitePal.deleteAll(Song.class, "duration > ?" , "350");

Kotlin:

LitePal.deleteAll<Song>("duration > ?" , "350")

6. 查询数据

从 song 表中查找具有指定 id 的单个记录。

Java:

Song song = LitePal.find(Song.class, id);

Kotlin:

val song = LitePal.find<Song>(id)

从 song 表中查找所有记录。

Java:

List<Song> allSongs = LitePal.findAll(Song.class);

Kotlin:

val allSongs = LitePal.findAll<Song>()

用流利的查询构造复杂的查询。

Java:

List<Song> songs = LitePal.where("name like ? and duration < ?", "song%", "200").order("duration").find(Song.class);

Kotlin:

val songs = LitePal.where("name like ? and duration < ?", "song%", "200").order("duration").find<Song>()

7. 多个数据库

如果你的应用需要多个数据库，LitePal 完全支持。你可以在运行时创建任意数量的数据库。例如：

LitePalDB litePalDB = new LitePalDB("demo2", 1);
litePalDB.addClassName(Singer.class.getName());
litePalDB.addClassName(Album.class.getName());
litePalDB.addClassName(Song.class.getName());
LitePal.use(litePalDB);

这将创建一个包含 singer 、album 和 song 表的 demo2 数据库。

如果你只想创建一个新数据库但与 litepal.xml 具有相同的配置，你可以使用：

LitePalDB litePalDB = LitePalDB.fromDefault("newdb");
LitePal.use(litePalDB);

还可以随时切换回默认数据库：

LitePal.useDefault();

还可以通过指定的数据库名称删除任何数据库：

LitePal.deleteDatabase("newdb");

8. Transaction

LitePal 支持原子数据库操作的事务。事务中的所有操作将一起提交或回滚

Java usage:

LitePal.beginTransaction();
boolean result1 = // db operation1
boolean result2 = // db operation2
boolean result3 = // db operation3
if (result1 && result2 && result3) {
    LitePal.setTransactionSuccessful();
}
LitePal.endTransaction();

Kotlin usage:

LitePal.runInTransaction {
    val result1 = // db operation1
    val result2 = // db operation2
    val result3 = // db operation3
    result1 && result2 && result3
}

六、混淆

1、如果你使用 ProGuard，你可能需要添加以下选项：

-keep class org.litepal.** {*;}
-keep class * extends org.litepal.crud.LitePalSupport {*;}