OSCHINA-MIRROR/HarmonyOS-tpc-LitePal

LitePal для openharmony

LitePal — это библиотека openharmony с открытым исходным кодом, которая позволяет разработчикам легко использовать базу данных SQLite. Вы можете выполнять большинство операций с базой данных, не записывая даже SQL-запросы, включая создание или обновление таблиц, операции CRUD, агрегатные функции и т. д. Настройка LitePal также довольно проста: вы можете интегрировать его в свой проект менее чем за 5 минут.

Испытайте магию прямо сейчас и получайте удовольствие!

Особенности

Использование шаблона объектно-реляционного отображения (ORM).
Практически нулевая конфигурация (только один файл конфигурации с несколькими свойствами).
Автоматическое ведение всех таблиц (например, создание, изменение или удаление таблиц).
Поддержка нескольких баз данных.
Инкапсулированные API для избежания написания SQL-запросов.
Отличный fluent-API для запросов.
Альтернативный выбор использования SQL, но более простые и лучшие API по сравнению с оригиналами.
Больше возможностей для изучения.

Быстрая настройка

1. Включите библиотеку

Отредактируйте файл build.gradle и добавьте следующую зависимость.

dependencies {
    implementation 'io.openharmony.tpc.thirdlib:LitePal:1.0.2'
}

2. Настройте litepal.xml

Создайте файл в папке assets вашего проекта и назовите его litepal.xml. Затем скопируйте в него следующие коды.

<?xml version="1.0" encoding="utf-8"?>
<litepal>
    <!--
        Определите имя базы данных вашего приложения. 
        По умолчанию каждое имя базы данных должно заканчиваться на .db. 
        Если вы не назвали свою базу данных оканчивающейся на .db, 
        LitePal добавит суффикс автоматически для вас.
        Например:    
        <dbname value="demo" />
    -->
    <dbname value="demo" />

    <!--
        Определите версию вашей базы данных. Каждый раз, когда вы хотите 
        обновить свою базу данных, тег версии поможет.
        Измените модели, которые вы определили в теге сопоставления, и просто 
        увеличьте значение версии на единицу, обновление базы данных
        будет обработано автоматически без беспокойства.
            Например:    
        <version value="1" />
    -->
    <version value="1" />

    <!--
        Определите свои модели в списке с тегом сопоставления, LitePal создаст таблицы для каждого класса сопоставления. Поддерживаемые поля
        определённые в моделях, будут сопоставлены со столбцами.
        Например:    
        <list>
            <mapping class="com.test.model.Reader" />
            <mapping class="com.test.model.Magazine" />
        </list>
    -->
    <list>
    </list>

    <!--
        Определите, где должен находиться файл .db. "internal" означает, что файл
        .db будет храниться в папке базы данных внутреннего хранилища, к которой никто
        не может получить доступ. "external" означает, что файл .db будет сохранён в
        пути к каталогу на основном внешнем запоминающем устройстве, где
        приложение может размещать постоянные файлы, которыми оно владеет и к которым каждый может получить доступ. По умолчанию действует "internal".
        Например:
        <storage value="external" />
    -->
</litepal>

Это единственный файл конфигурации, и свойства просты.

dbname настраивает имя базы данных проекта.
version настраивает версию базы данных. При каждом обновлении базы данных увеличивайте значение здесь.
list настраивает классы сопоставления.
storage настраивает, где должен храниться файл базы данных. internal и external — единственные допустимые варианты.

3. Настройте LitePalApplication

Вы не хотите передавать параметр Context всё время. Чтобы упростить API, просто настройте AbilityPackage в config.json, как показано ниже:

{
"module": {
    "name": "org.litepal.LitePalApplication",
    ...
    }
}

Конечно, у вас может быть собственный AbilityPackage, который уже настроен здесь, например:

{
"module": {
    "name": ".MyAbilityPackage",
    ...
    }
}

Всё в порядке. LitePal всё ещё может работать с этим. Просто вызовите LitePal.initialize(context) в своём собственном AbilityPackage:

public class MyAbilityPackage extends AbilityPackage {

    @Override
    public void onInitialize() { **super.onInitialize();**

**org.litepal.LitePal.initialize(getApplicationContext());**

*…*

}

*...*

Make sure to call this method as early as you can. In the onInitialize() method of AbilityPackage will be fine. And always remember to use the application context as parameter. Do not use any instance of Ability or AbilityService as parameter, or memory leaks might happen.

Get Started

После настройки вы можете испытать мощные функции прямо сейчас.

1. Создание таблиц

Сначала определите модели. Например, у вас есть две модели: Album и Song. Модели можно определить следующим образом:

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<>();

    // сгенерированные геттеры и сеттеры.
    ...
}

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

    // сгенерированные геттеры и сеттеры.
    ...
}

Затем добавьте эти модели в список сопоставления в litepal.xml:

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

ОК! Таблицы будут созданы при следующей операции с базой данных. Например, получите RdbStore с помощью следующих кодов:

RdbStore 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<>();

    // сгенерированные геттеры и сеттеры.
    ...
}

Было добавлено поле releaseDate, а поле price было аннотировано для игнорирования. Затем увеличьте номер версии в litepal.xml:

<!--
    Определите версию вашей базы данных. Каждый раз, когда вы хотите
    обновить свою базу данных, тег версии поможет.
    Измените модели, которые вы определили в теге сопоставления, и просто
    увеличьте значение версии на единицу, обновление базы данных
    будет выполнено автоматически без проблем.
    Например:    
    <version value="1" />
-->
<version value="2" />

Таблицы будут обновлены при следующей операции с базой данных. Поле releasedate будет добавлено в таблицу album, а исходное поле 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()

Это позволит добавить альбом, 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(). Вы можете обновить одну запись с указанным идентификатором.

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. Удаление данных

Вы можете удалить одну запись, используя статический метод delete() в LitePal.

Java:

LitePal.delete(Song.class, id);

Kotlin:

LitePal.delete<Song>(id)

Или удалите несколько записей, используя статический метод deleteAll() в LitePal.

Java:

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

Kotlin:

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

6. Запрос данных

Найдите одну запись из таблицы песен с указанным идентификатором.

Java:

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

Kotlin:

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

Найдите все записи из таблицы песен.

Java:

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

Kotlin:

val allSongs = LitePal.findAll<Song>()

Построение сложного запроса с помощью fluent query.

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

Это создаст базу данных demo2 с таблицами singer, album и song.

Если вы просто хотите создать новую базу данных, но с той же конфигурацией, что и litepal.xml, вы можете сделать это с помощью:

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

Вы всегда можете вернуться к базе данных по умолчанию с помощью:

LitePal.useDefault();

И вы можете удалить любую базу данных по указанному имени базы данных:

LitePal.deleteDatabase("newdb");

8. Транзакции

LitePal поддерживает транзакции для атомарных операций с базой данных. Все операции в транзакции будут зафиксированы или откатываются вместе.

Использование Java:

LitePal.beginTransaction();
boolean result1 = // операция с БД 1
boolean result2 = // операция с БД 2
boolean result3 = // операция с БД 3
if (result1 && result2 && result3) {
    LitePal.setTransactionSuccessful();
}
LitePal.endTransaction();

Использование Kotlin:

LitePal.runInTransaction {
    val result1 = // операция с БД 1
    val result2 = // операция с БД 2
    val result3 = // операция с БД 3
    result1 && result2 && result3
}

ProGuard

Если вы используете ProGuard, вы можете... Необходимо добавить следующую опцию:

-keep class org.litepal.** {
    *;
}

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

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

License

Copyright (C)  Tony Green, LitePal Framework Open Source Project

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.