entity - OneScript Persistence API

<a id="header" />

Библиотека Entity предназначена для работы с данными БД как с простыми OneScript объектами. Является реализацией концепции ORM и шаблонов DataMapper и ActiveRecord в OneScript. Вдохновение черпается из Java Persistence API и TypeORM.

Возможности:

• описание таблиц БД в виде специальным образом аннотированных OneScript классов;
• сохранение объектов OneScript в связанных таблицах БД;
• поиск по таблицам с результатом в виде коллекции заполненных данными объектов OneScript;
• абстрактный программный интерфейс (API), не зависящий от используемой СУБД;
• референсная реализация полнофункционального коннектора к SQLite и PostgreSQL, а так же упрощенного коннектора к файлам JSON.

Описание публичного интерфейса - каталог docs.

Оглавление

• <a href="#header">entity - OneScript Persistence API</a>
  • <a href="#entity-example">Пример класса-сущности</a>
  • <a href="#entity-create">Создание и сохранение сущностей</a>
  • <a href="#entity-read">Чтение и поиск объектов</a>
    • <a href="#entity-complex-find">Поиск сущностей со сложными отборами</a>
    • <a href="#entity-sort">Сортировка результатов</a>
    • <a href="#entity-limit">Пропуск и смещение</a>
  • <a href="#entity-delete">Удаление сущностей</a>
  • <a href="#entity-active-record">Активная запись</a>
  • <a href="#entity-repository">Работа через ХранилищеСущностей</a>
  • <a href="#transactions">Работа с транзакциями</a>
  • <a href="#annotations">Система аннотаций для сущностей</a>
    • <a href="#annotation-entity">Сущность</a>
    • <a href="#annotation-id">Идентификатор</a>
    • <a href="#annotation-generated">ГенерируемоеЗначение</a>
    • <a href="#annotation-column">Колонка</a>
    • <a href="#annotation-secondary-table">ПодчиненнаяТаблица</a>
  • <a href="#library-structure">Структура библиотеки</a>
    • <a href="#library-structure-entity-manager">МенеджерСущностей</a>
    • <a href="#library-structure-entity-repository">ХранилищеСущностей</a>
    • <a href="#library-structure-connectors">Коннекторы (АбстрактныйКоннектор)</a>
    • <a href="#library-structure-data-model">МодельДанных</a>
    • <a href="#library-structure-model-object">ОбъектМодели</a>
    • <a href="#library-structure-connector-sqlite">КоннекторSQLite</a>
    • <a href="#library-structure-connector-postgresql">КоннекторPostgreSQL</a>
    • <a href="#library-structure-connector-json">КоннекторJSON</a>
    • <a href="#library-structure-connector-inmemory">КоннекторInMemory</a>
  • <a href="#versioning-strategy">Версионирование и обратная совместимость</a>

<a id="entity-example" />

Пример класса-сущности

Сущность - это обычный класс OneScript, размеченный служебными аннотациями. Обязательными аннотациями являются &Сущность и &Идентификатор.

Библиотека entity считывает состав аннотаций класса, строит модель данных и инициализирует таблицы базы данных для работы с объектами данного класса.

Ограничения:

• класс-сущность должен иметь конструктор по умолчанию, либо конструктор без параметров, либо конструктор со значениями всех параметров по умолчанию.

// file: СтраныМира.os

// Данный класс содержит данные о странах мира.

&Идентификатор                        // Колонка для хранения ID сущности
Перем Код Экспорт;                    // Колонка по умолчанию имеет строковый тип

Перем Наименование Экспорт;           // Колонка `Наименование` будет создана в таблице, т.к. поле экспортное.

&Сущность                             // Объект с типом "СтраныМира" будет представлен в СУБД как таблица "СтраныМира"
Процедура ПриСозданииОбъекта()

КонецПроцедуры

// file: Документ.os

&Идентификатор
&ГенерируемоеЗначение                      // Заполняется автоматически при сохранении сущности
&Колонка(Тип = "Целое")                    // Хранит целочисленные значения
Перем Идентификатор Экспорт;               // Имя колонки в базе - `Идентификатор`

&Колонка
Перем Номер Экспорт;                       // Колонка `Номер` будет создана в таблице, т.к. поле экспортное

&Колонка
Перем Серия Экспорт;                       // Колонка `Номер` будет создана в таблице, т.к. поле экспортное

&Сущность(ИмяТаблицы = "Документы")
Процедура ПриСозданииОбъекта()             // Объект с типом "Документ" будет представлен в СУБД как таблица "Документы"

КонецПроцедуры

// file: ФизическоеЛицо.os

// Данный класс содержит информацию о физических лицах.

&Идентификатор                             // Колонка для хранения ID сущности
&ГенерируемоеЗначение                      // Заполняется автоматически при сохранении сущности
&Колонка(Тип = "Целое")                    // Хранит целочисленные значения
Перем Идентификатор Экспорт;               // Имя колонки в базе - `Идентификатор`

Перем Имя Экспорт;                         // Колонка `Имя` будет создана в таблице, т.к. поле экспортное.
&Колонка(Имя = "Отчество")                 // Поле `ВтороеИмя` в таблице будет представлено колонкой `Отчество`.
Перем ВтороеИмя Экспорт;

&Колонка(Тип = "Дата")                     // Колонка `ДатаРождения` хранит значения в формате дата-без-времени
Перем ДатаРождения Экспорт;

&Колонка(Тип = "Ссылка", ТипСсылки = "СтраныМира")
Перем Гражданство Экспорт;                 // Данная колонка будет хранить ссылку на класс `СтраныМира`

&ПодчиненнаяТаблица(Тип = "Массив", ТипЭлемента = "Документы", КаскадноеЧтение = Истина)
Перем Документы Экспорт;                   // Данное поле будет хранить массив ссылок на класс `Документ`.
                                           // Для хранения массива будет создана отдельная таблица.
                                           // Взведенный флаг "КаскадноеЧтение" сигнализирует о необходимости
                                           // инициализировать сущности в массиве при чтении объекта из СУБД.

&Сущность(ИмяТаблицы = "ФизическиеЛица")   // Объект с типом `ФизическоеЛицо` (по имени файла) будет представлен в СУБД в виде таблицы `ФизическиеЛица`
Процедура ПриСозданииОбъекта()

КонецПроцедуры

<a id="entity-create" />

Создание и сохранение сущностей

// Создание менеджера сущностей. Коннектором к базе выступает референсная реализация КоннекторSQLite.
// В качестве БД используется "база в оперативной памяти".
МенеджерСущностей = Новый МенеджерСущностей(Тип("КоннекторSQLite"), "FullUri=file::memory:?cache=shared");

// Создание или обновление таблиц в БД.
МенеджерСущностей.ДобавитьКлассВМодель(Тип("СтраныМира"));
МенеджерСущностей.ДобавитьКлассВМодель(Тип("Документ"));
МенеджерСущностей.ДобавитьКлассВМодель(Тип("ФизическоеЛицо"));

// После заполнения модели менеджер необходимо проинициализировать.
МенеджерСущностей.Инициализировать();

// Работа с обычными объектом OneScript.
СохраняемоеФизЛицо = Новый ФизическоеЛицо;
СохраняемоеФизЛицо.Имя = "Иван";
СохраняемоеФизЛицо.ВтороеИмя = "Иванович";
СохраняемоеФизЛицо.ДатаРождения = Дата(1990, 01, 01);

СтранаМира = Новый СтраныМира;
СтранаМира.Код = "643";
СтранаМира.Наименование = "Российская Федерация";

Паспорт = Новый Документ;
Паспорт.Номер = "11 11";
Паспорт.Серия = "111000";

// Присваиваем колонке с типом "Ссылка" конкретный объект с типом "СтраныМира"
СохраняемоеФизЛицо.Гражданство = СтранаМира;

// Инициализируем массив для хранения документов.
// Это можно сделать и в методе ПриСозданииОбъекта в классе ФизическоеЛицо.os
СохраняемоеФизЛицо.Документы = Новый Массив;
// Добавляем новый документ
СохраняемоеФизЛицо.Документы.Добавить(Паспорт);

// Сохранение объектов в БД
// Сначала сохраняются подчиненные сущности, потом высокоуровневые
МенеджерСущностей.Сохранить(СтранаМира);
МенеджерСущностей.Сохранить(Паспорт);
МенеджерСущностей.Сохранить(СохраняемоеФизЛицо);

// После сохранения СохраняемоеФизЛицо.Идентификатор содержит автосгенерированный идентификатор.
// Колонка "Гражданство" в СУБД будет хранить идентификатор объекта СтранаМира - значение "643".
// Для хранения документов будет создана отдельная таблица, в которой будут сохранены
// значения массива с привязкой к физическому лицу.

<a id="entity-read" />

Чтение и поиск объектов

Для поиска сущностей существуют методы Получить() и ПолучитьОдно().

Метод Получить() возвращает массив найденных сущностей.

Метод ПолучитьОдно() возвращает одну (первую попавшуюся) сущность или Неопределено, если найти сущность не удалось.

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

• Неопределено (параметр не заполнен) - поиск без отборов;
• Соответствие - пары ИмяПоля-ЗначениеПоля, используемые как отбор по "равно";
• ОпцииПоиска - объект типа "ОпцииПоиска", позволяющий использовать сложные условия отбора и сортировки.

Поиск сущностей с простыми отборами

// Для поиска нескольких сущностей, удовлетворяющих условию, можно использовать метод Получить()
// При вызове метода без параметров будут полученные все сущности указанного типа.
// В массиве содержатся объекты типа "ФизическоеЛицо" с заполненными значениями полей.
// Поле "Гражданство" заполнится готовым объектом с типом "СтраныМира".
// Т.к. над полем "Документы" взведен флаг "КаскадноеЧтение", то данное поле