Библиотека Entity предназначена для работы с данными БД как с простыми OneScript объектами. Является реализацией концепции ORM в OneScript. Вдохновение черпается из Java Persistence API.
Возможности:
- Описание таблиц БД в виде специальным образом аннотированных OneScript классов
- Сохранение объектов OneScript в связанных таблицах БД
- Поиск по таблицам с результатом в виде коллекции заполненных данными объектов OneScript
- Абстрактный программный интерфейс (API), не зависящий от используемой СУБД
- Референсная реализация коннектора к SQLite
// file: СтраныМира.os
// Данный класс содержит данные о странах мира.
&Идентификатор // Колонка для хранения ID сущности
Перем Код Экспорт; // Колонка по умолчанию имеет строковый тип
Перем Наименование Экспорт; // Колонка `Наименование` будет создана в таблице, т.к. поле экспортное.
&Сущность // Объект с типом "СтраныМира" будет представлен в СУБД как таблица "СтраныМира"
Процедура ПриСозданииОбъекта()
КонецПроцедуры
// file: ФизическоеЛицо.os
// Данный класс содержит информацию о физических лицах.
&Идентификатор // Колонка для хранения ID сущности
&ГенерируемоеЗначение // Заполняется автоматически при сохранении сущности
&Колонка(Тип = "Целое") // Хранит целочисленные значения
Перем Идентификатор Экспорт; // Имя колонки в базе - `Идентификатор`
Перем Имя Экспорт; // Колонка `Имя` будет создана в таблице, т.к. поле экспортное.
&Колонка(Имя = "Отчество") // Поле `ВтороеИмя` в таблице будет представлено колонкой `Отчество`.
Перем ВтороеИмя Экспорт;
&Колонка(Тип = "Дата") // Колонка `ДатаРождения` хранит значения в формате дата-без-времени
Перем ДатаРождения Экспорт;
&Колонка(Тип = "Ссылка", ТипСсылки = "СтраныМира")
Перем Гражданство Экспорт; // Данная колонка будет хранить ссылку на класс СтраныМира
&Сущность(ИмяТаблицы = "ФизическиеЛица") // Объект с типом `ФизическоеЛицо` (по имени файла) будет представлен в СУБД в виде таблицы `ФизическиеЛица`
Процедура ПриСозданииОбъекта()
КонецПроцедуры// Создание менеджера сущностей. Коннектором к базе выступает референсная реализация КоннекторSQLite.
МенеджерСущностей = Новый МенеджерСущностей(Тип("КоннекторSQLite"));
// Создание или обновление таблиц в БД.
МенеджерСущностей.ДобавитьКлассВМодель(Тип("СтраныМира"));
МенеджерСущностей.ДобавитьКлассВМодель(Тип("ФизическоеЛицо"));
// После заполнения модели менеджер необходимо проинициализировать.
МенеджерСущностей.Инициализировать();
// Работа с обычными объектом OneScript.
СохраняемоеФизЛицо = Новый ФизическоеЛицо;
СохраняемоеФизЛицо.Имя = "Иван";
СохраняемоеФизЛицо.ВтороеИмя = "Иванович";
СохраняемоеФизЛицо.ДатаРождения = Дата(1990, 01, 01);
СтранаМира = Новый СтраныМира;
СтранаМира.Код = "643";
СтранаМира.Наименование = "Российская Федерация";
// Присваиваем колонке с типом "Ссылка" конкретный объект с типом "СтраныМира"
СохраняемоеФизЛицо.Гражданство = СтранаМира;
// Сохранение объектов в БД
// Сначала сохраняются подчиненные сущности, потом высокоуровневые
МенеджерСущностей.Сохранить(СтранаМира);
МенеджерСущностей.Сохранить(СохраняемоеФизЛицо);
// После сохранения СохраняемоеФизЛицо.Идентификатор содержит автосгенерированный идентификатор.
// Колонка "Гражданство" в СУБД будет хранить идентификатор объекта СтранаМира - значение "643".// Допустим в БД сохранено физ. лицо с идентификатором, равным 123.
СохраненноеФизЛицо = МенеджерСущностей.Получить(Тип("ФизическоеЛицо"), 123);
// Переменная "СохраненноеФизЛицо" содержит объект типа "ФизическоеЛицо" с заполненными из БД значениями полей.
// Поле "Гражданство" заполнится готовым объектом с типом "СтраныМира".Для связями между классом на OneScript и таблицей в БД используется система аннотаций. Часть аннотаций обязательная к применению. Все параметры аннотаций необязательные.
При анализе типа сущности менеджер сущности формирует специальные объекты модели, передаваемые конкретным реализациям коннекторов. Коннекторы могут рассчитывать на наличие всех описанных параметров аннотаций в объекте модели.
Применение: обязательно
Каждый класс, подключемый к менеджеру сущностей должен иметь аннотацию Сущность, расположенную над любым методом класса.
При отсутствии у класса методов рекомендуется навешивать аннотацию над методом ПриСозданииОбъекта().
Аннотация Сущность имеет следующие параметры:
ИмяТаблицы- Строка - Имя таблицы, используемой коннектором к СУБД при работе с сущностью. Значение по умолчанию - строковое представление имени типа сценария. При подключении сценариев стандартным загрузчиком библиотек совпадает с именем файла.
Применение: обязательно
Каждый класс, подключаемый к менеджеру сущностей должен иметь поле для хранения идентификатора объекта в СУБД - первичного ключа. Для формирования автоинкрементного первичного ключа можно воспользоваться дополнительной аннотацией ГенерируемоеЗначение.
Аннотация Идентификатор не имеет параметров.
Применение: необязательно
Все экспортные поля класса преобразуются в колонки таблицы в СУБД. Аннотация Колонка позволяет тонко настроить параметры колонки таблицы.
Аннотация Колонка имеет следующие параметры:
Имя- Строка - Имя колонки, используемой коннектором к СУБД при работе с сущностью. Значение по умолчанию - имя свойства.Тип- ТипыКолонок - Тип колонки, используемой для хранения идентификатора. Значение по умолчанию -ТипыКолонок.Строка. Доступные типы колонок:- Целое
- Дробное
- Булево
- Строка
- Дата
- Время
- ДатаВремя
- Ссылка
Применение: необязательно
Для части полей допустимо высчитывать значение колонки при вставке записи в таблицу. Например, для первичных числовых ключей обычно не требуется явное управление назначемыми идентификаторами.
Референсная реализация коннектора на базе SQLite поддерживает единственный тип генератора значений - AUTOINCREMENT.
Планируется расширение аннотации указанием параметров генератора.
Аннотация ГенерируемоеЗначение не имеет параметров.
To be continued...