LitePal基本使用概述

前言

LitePal是一款开源的Android数据库框架，它采用了对象映射关系（ORM）的模式，并将我们平时开发最常用的一些数据库功能进行了封装，减小了代码量。

官方Git地址

使用

使用LitePal主要包括如下几步：

1. 引入jar包并申请对应权限
2. 初始化数据库，创建实体类
3. 绑定实体类到数据库中，生成数据表
4. 进行数据库增删改查等基本操作

litePal数据库的创建包括两种基本方式：

1. 通过xml定义数据库名称及版本，定义实体类的绑定
2. 通过代码动态控制数据库名称及版本

下面分别对上面两种方式进行说明。

一、引入jar包

使用LitePal必须要引入对应jar包，示例代码如下：

//Android LitePal
implementation 'org.litepal.guolindev:core:3.1.1'

添加jar包之后需要注意混淆配置，在混淆文件中添加如下内容：

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

二、通过xml定义

1. 定义数据库xml

首先需要定义数据库文件，可以在包下新建一个assets文件夹，在此文件中新建名为litepal.xml的文件，文件内容示例如下：

<?xml version="1.0" encoding="utf-8"?>
<litepal>
    <!--数据库名称-->
    <dbname value="testlitepal" />
    <!--数据库版本-->
    <version value="1" />

    <!--映射模型-->
    <list>
        <!--添加实体类，此处必须映射完整路径-->
        <mapping class="com.example.demowork1.litepal.model.DataEntity1" />
    </list>
</litepal>

完成了上述内容之后我们需要注意上述文件中的几点内容：

1. version参数代表的是数据库的版本参数，在我们每次更改完数据库之后必须要+1才能够生效，否则不会有覆盖安装生效。
2. 在list中的实体类必须要继承LitePalSupport类定义为LitePal实体。

2. 定义实体类

LitePal定义的实体类必须要继承LitePalSupport,示例如下：

class DataEntity1(var id: Int = 0, var name: String ="default") : LitePalSupport() {

    override fun toString():String{
        return "$name=name   id=$id"
    }
}

需要注意的是：

1. LitePal支持的实体类字段映射类型为int,long,double,float,boolean,String,Data,byte[],不支持String[]以及List类型的属性。
2. LitePal会在表中自动生成一个id列，用来标识当前这张表的主键，即使实体类中没有id这个属性，也会创建这样一个默认为整形的id字段，以作为自增的主键。
3. 如果实体类中有一个字段名为id，那么此字段的类型只能定义为int或者long。
4. id字段的值始终为当前记录的行号（下标从1开始），即使我们在实体类中定义了int或者long类型的id字段，在添加数据时人为的去更新id值也会无效的。id的值会始终等于行号。

3. 初始化数据库

使用LitePal需要在application中添加初始化代码：

class DemoApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        mContext = this
        LitePal.initialize(this)
        ...
    }
    ...
}

然后需要将此Application设置到AndroidManifest.xml文件中：

    <application
        android:name=".DemoApplication"
        ...>
    </application>

4. 数据库的增删改查

1. 存储

将数据存储到数据库中可以调用方法：save()：

var testData1 = DataEntity1()
testData1.name = "aaa"
testData1.id = 1
if (testData1.save())
    LogUtil.instance.d("添加数据成功")
else
    LogUtil.instance.d("添加数据失败")

save()方法的返回值是boolean类型，表示数据是否添加到数据库中，true为添加成功。如果需要批量添加数据，需要调用LitePal.saveAll(datas);

2.删除

删除可以调用delete()或者deleteAll()方法，示例如下：

//删除数据表中指定ID的数据
LitePal.delete(DataEntity1::class.java,1)
//清空整个数据表
LitePal.deleteAll(DataEntity1::class.java)
//条件删除
deleteAll(DataEntity1::class.java, "id = ?", "1")

当然也可以通过获得SQLiteDatabase来进行操作，获取SQLiteDatabase方法如下：

SQLiteDatabase db = LitePal.getDatabase();

3. 修改

由于LitePal是以行号id作为主键，因此可以直接通过调用update方法直接更新对应id的数据，示例代码如下：

var testData1 = DataEntity1(2,"bbb")
testData1.update(2)

当然，仅仅有针对id进行修改是不够的，我们更多情况的使用是去修改满足一定条件的数据内容，当然LitePal也支持这种操作，采用的方法是：

public static int updateAll(String... conditions)

通过updateAll方法可以修改多行记录，conditions参数是指的约束条件，它是一个String数组，我们可以在这里填入多个String参数，其中第一个String参数表示约束条件，后面的String参数是逐项的参数值，举例如下：

testData1.updateAll("name = ? and id < ?", "bbb", "3");

如上述句子，我们去修改制定的数据内容，可以看到首项String(“name= ? and id < ?”)这个是标识当前修改的约束条件，而后面的两项"bbb"和"3"是前面约束条件的值。
完整的代码如下：

var testData1 = DataEntity1(2,"bbb")
testData1.updateAll("name = ? and id < ?", "bbb", "3");

4. 查询

LitePal查询和更新有些相似，都是分为根据id或条件进行查询。
根据id查询
根据id查询主要包括findAll(),find()等几个方法，传入参数多为实体类class，以及id参数，示例如下：

//查找所有DataEntity1中的数据
var listData = LitePal.findAll(DataEntity1::class.java)
//查找id为1的数据
var listData1 = LitePal.find(DataEntity1::class.java,1)
//查找ID为1，2，3的数据
var listData2 = LitePal.findAll(DataEntity1::class.java,1,2,3)

根据条件进行查询
根据条件查询主要调用的方法是select()方法，示例如下：

 var listData3 = LitePal.select("name")
                .where("id < ?","3")
                .order("id desc")
                .find(DataEntity1::class.java)

如上述条件所示，select中的参数是表的列名，where中的参数是条件，其规则和上述更新时的条件规则一样。order是排序功能，这里是降序排列，find指定具体查询的表名称。

5. 数据库升级

使用LitePal完成数据库升级十分简单，只需要在完成数据表结构变更之后，在litepal.xml文件里将version参数+1即可，如果有新增的数据表，则还需要将新增的数据表映射添加到xml文件的映射list中。

需要注意的是，每次数据的升级都必须要对版本号进行更改，否则覆盖安装时你所做的修改不会触发，从而有可能发生错误。

三、 通过代码控制数据库的生成

除了通过xml完成数据库的配置之外，我们还可以通过代码设置数据库并添加数据表,示例代码如下:

class LitePalDBManager {
    var litePalDB: LitePalDB? = null

    /**
     * 动态建立数据库，不去使用xml
     */
    fun initMultiDB(dbName: String) {
        litePalDB = LitePalDB(dbName, 1)
        litePalDB?.addClassName(DataEntity1::class.java.name)
        if (litePalDB != null) {
            use(litePalDB!!)
        }
    }

    companion object {
        val instance: LitePalDBManager by lazy { LitePalDBManager() }
    }
}

通过使用LitePalDB来动态的创建一个数据库，声明其数据库的名称，之后通过addClassName来添加数据表名称，最后通过调用use方法使用数据库。

1. 增删改查操作

增删改查操作和使用xml时没有区别。

2. 数据库升级

数据库升级和使用xml同样比较相似，只需要在修改数据表结构之后，将数据库的版本+1即可，同理，如果数据库版本没有增加，则覆盖安装后数据库结构不会发生变化。

四、注意事项

要注意到上述的这些数据库操作都是在主线程中进行操作的，因此在使用数据库时需要判断自己的需求是否可以在主线程中调用数据库操作，需要放在子线程的请放在子线程操作。