Merge pull request #103 from nixel2007/feature/data-source

Указание источников данных в сущностях, расширение документации

.github/workflows/main.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        oscript_version: ['1.8.3', 'stable']
+        oscript_version: ['1.9.2', 'stable']
     steps:
     - uses: actions/checkout@v4
 

.github/workflows/qa.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Setup Onescript Action
       uses: otymko/[email protected]
       with:
-        version: "1.8.3"
+        version: "1.9.2"
 
     - name: Install dependencies
       run: |

.github/workflows/release.yml

@@ -5,8 +5,8 @@
 name: Подготовка релиза и публикация в хабе
 # Только события создания и изменения релиза
 on:
-    release:
-        types: [published, edited]
+  release:
+    types: [published]
 
 env:
   PACKAGE_MASK: entity-*.ospx
@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        oscript_version: ['1.8.3']
+        oscript_version: ['1.9.2']
 
     steps:
       # Загрузка проекта

README.md

@@ -409,14 +409,15 @@
 Аннотация `Сущность` имеет следующие параметры:
 
 * `ИмяТаблицы` - Строка - Имя таблицы, используемой коннектором к СУБД при работе с сущностью. Значение по умолчанию - строковое представление имени типа сценария. При подключении сценариев стандартным загрузчиком библиотек совпадает с именем файла.
+* `ИсточникДанных` - Строка - Повторяемый. Имя источника данных, используемого коннектором к СУБД при работе с сущностью. Если не задано, считается, что сущность может быть использована с любым источником данных.
 
 <a id="annotation-id" />
 
 ### Идентификатор
 
 > Применение: обязательно
 
-Каждый класс, подключаемый к менеджеру сущностей должен иметь поле для хранения идентификатора объекта в СУБД - первичного ключа. Для формирования автоинкрементного первичного ключа можно воспользоваться дополнительной аннотацией `ГенерируемоеЗначение`.
+Каждый класс, подключаемый к менеджеру сущностей, должен иметь поле для хранения идентификатора объекта в СУБД - первичного ключа. Для формирования автоинкрементного первичного ключа можно воспользоваться дополнительной аннотацией `ГенерируемоеЗначение`.
 
 Аннотация `Идентификатор` не имеет параметров.
 

lib.config

@@ -1,6 +1,7 @@
 <package-def>
     <class name="АбстрактныйКоннектор" file="src/Классы/АбстрактныйКоннектор.os"/>
     <class name="АбстрактныйКоннекторSQL" file="src/Классы/АбстрактныйКоннекторSQL.os"/>
+    <class name="ИсточникДанных" file="src/Классы/ИсточникДанных.os"/>
     <class name="КоннекторSQLite" file="src/Классы/КоннекторSQLite.os"/>
     <class name="КоннекторJSON" file="src/Классы/КоннекторJSON.os"/>
     <class name="КоннекторPostgreSQL" file="src/Классы/КоннекторPostgreSQL.os"/>
@@ -12,6 +13,11 @@
     <class name="ЭлементПорядка" file="src/Классы/ЭлементПорядка.os"/>
     <class name="ХранилищеСущностей" file="src/Классы/ХранилищеСущностей.os"/>
     <class name="КоннекторInMemory" file="src/Классы/КоннекторInMemory.os"/>
+    <class name="АннотацияГенерируемоеЗначение" file="src/Аннотации/Классы/АннотацияГенерируемоеЗначение.os"/>
+    <class name="АннотацияИдентификатор" file="src/Аннотации/Классы/АннотацияИдентификатор.os"/>
+    <class name="АннотацияКолонка" file="src/Аннотации/Классы/АннотацияКолонка.os"/>
+    <class name="АннотацияПодчиненнаяТаблица" file="src/Аннотации/Классы/АннотацияПодчиненнаяТаблица.os"/>
+    <class name="АннотацияСущность" file="src/Аннотации/Классы/АннотацияСущность.os"/>
     <module name="ТипыКолонок" file="src/Модули/ТипыКолонок.os"/>
     <module name="ТипыПодчиненныхТаблиц" file="src/Модули/ТипыПодчиненныхТаблиц.os"/>
     <module name="ВидСравнения" file="src/Модули/ВидСравнения.os"/>

packagedef

@@ -4,17 +4,18 @@
 //
 // BSLLS:CodeOutOfRegion-off
 Описание.Имя("entity")
-        .Версия("3.4.2.0")
+        .Версия("3.4.3.0")
         .Автор("Nikita Gryzlov")
         .АдресАвтора("[email protected]")
         .Описание("entity")
-        .ВерсияСреды("1.8.3")
+        .ВерсияСреды("1.9.2")
         .ВключитьФайл("src")
         .ВключитьФайл("tests")
         .ВключитьФайл("lib.config")
         .ВключитьФайл("README.md")
         .ВключитьФайл("docs")
         .ВключитьФайл("LICENSE.md")
+        .ЗависитОт("annotations", "1.2.0")
         .ЗависитОт("asserts", "1.3.0")
         .ЗависитОт("fluent", "0.6.1")
         .ЗависитОт("fs", "1.0.0")

src/Аннотации/Классы/АннотацияГенерируемоеЗначение.os

@@ -0,0 +1,16 @@
+// Для части полей допустимо высчитывать значение колонки при вставке записи в таблицу.
+// Например, для первичных числовых ключей обычно не требуется явное управление назначаемыми идентификаторами.
+//
+// Референсная реализация коннекторов на базе SQL поддерживает единственный тип генератора значений - `AUTOINCREMENT`.
+//
+// Применяется на поле класса.
+//
+// Пример:
+// 
+// &Идентификатор
+// &ГенерируемоеЗначение
+// Перем ИД;
+//
+&Аннотация("ГенерируемоеЗначение")
+Процедура ПриСозданииОбъекта()
+КонецПроцедуры

src/Аннотации/Классы/АннотацияИдентификатор.os

@@ -0,0 +1,16 @@
+// Каждый класс, подключаемый к менеджеру сущностей, должен иметь поле для хранения 
+// идентификатора объекта в СУБД - первичного ключа.
+//
+// Для формирования автоинкрементного первичного ключа можно воспользоваться
+// дополнительной аннотацией `&ГенерируемоеЗначение`.
+//
+// Применяется на поле класса.
+//
+// Пример:
+// 
+// &Идентификатор
+// Перем ИД;
+//
+&Аннотация("Идентификатор")
+Процедура ПриСозданииОбъекта()
+КонецПроцедуры

src/Аннотации/Классы/АннотацияКолонка.os

@@ -0,0 +1,37 @@
+// Все **экспортные** поля класса (за исключением полей, помеченных аннотаций `ПодчиненнаяТаблица`)
+// преобразуются в колонки таблицы в СУБД.
+//
+// Аннотация `Колонка` позволяет тонко настроить параметры колонки таблицы.
+//
+// Применяется на поле класса.
+// 
+// Параметры:
+//   Имя - Строка - Имя колонки, используемой коннектором к СУБД при работе с сущностью.
+//                  Значение по умолчанию - имя свойства.
+//   Тип - Строка - Тип колонки, используемой для хранения идентификатора. Значение по умолчанию - `ТипыКолонок.Строка`.
+//                  Доступные типы колонок:
+//                    - "Целое"
+//                    - "Дробное"
+//                    - "Булево"
+//                    - "Строка"
+//                    - "Дата"
+//                    - "Время"
+//                    - "ДатаВремя"
+//                    - "Ссылка"
+//                    - "ДвоичныеДанные"
+//   ТипСсылки - Строка - Имя зарегистрированного в модели типа, в который преобразуется значение из колонки.
+//                        Имеет смысл только в паре с параметром `Тип`, равным `Ссылка`.
+//                        Допустимо указывать примитивные типы из перечисления `ТипыКолонок`
+//                        и типы сущностей (например, `"ФизическоеЛицо"`)
+//
+// Пример:
+//
+// 1. &Колонка(Тип = Число)
+// Перем Возраст;
+//
+// 2. &Колонка(Имя = "ДУЛ", Тип = Ссылка, ТипСсылки = "Документ")
+// Перем ДокументУдостоверяющийЛичность;
+//
+&Аннотация("Колонка")
+Процедура ПриСозданииОбъекта(Имя = Неопределено, Тип = "Строка", ТипСсылки = Неопределено)
+КонецПроцедуры

src/Аннотации/Классы/АннотацияПодчиненнаяТаблица.os

@@ -0,0 +1,21 @@
+// Аннотация `ПодчиненнаяТаблица` используется для хранения коллекций - массивов и структур.
+//
+// Параметры:
+//   ИмяТаблицы - Строка - Имя таблицы, используемой коннектором к СУБД при работе с сущностью.
+//                         Значение по умолчанию - строка вида `ИмяТаблицыСущности_ИмяСвойства`.
+//   Тип - Строка - Тип колонки, используемой для хранения идентификатора.
+//                  Доступные типы подчиненных таблиц:
+//                   - Массив
+//                   - Структура
+//   ТипЭлемента - Строка - Имя зарегистрированного в модели типа, в который преобразуется значение из колонки.
+//                          Допустимо указывать примитивные типы из перечисления `ТипыКолонок`
+//                          и типы сущностей (например, `"ФизическоеЛицо"`).
+//   КаскадноеЧтение - Булево - Флаг, отвечающий за инициализацию сущностей в подчиненной таблице
+//                              (если `ТипЭлемента` является ссылочным типом).
+//
+// Пример:
+// &ПодчиненнаяТаблица(Тип = "Массив", ТипЭлемента = "Документ", КаскадноеЧтение = Истина)
+// Перем Документы;
+&Аннотация("ПодчиненнаяТаблица")
+Процедура ПриСозданииОбъекта(ИмяТаблицы = Неопределено, Тип = Неопределено, ТипЭлемента = Неопределено, КаскадноеЧтение = Ложь)
+КонецПроцедуры

src/Аннотации/Классы/АннотацияСущность.os

@@ -0,0 +1,19 @@
+// Каждый класс, подключаемый к менеджеру сущностей должен иметь аннотацию `Сущность`,
+// расположенную над конструктором объекта.
+//
+// Параметры:
+//   ИмяТаблицы - Строка - Имя таблицы, используемой коннектором к СУБД при работе с сущностью.
+//                         Значение по умолчанию - строковое представление имени типа сценария.
+//                         При подключении сценариев стандартным загрузчиком библиотек совпадает с именем файла.
+//   ИсточникДанных - Строка - Повторяемый. Имя источника данных, используемого коннектором к СУБД при работе с сущностью.
+//                             Если не задано, считается, что сущность может быть использована с любым
+//                             источником данных.
+//
+// Пример:
+//
+// &Сущность("ФизическиеЛица")
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+&Аннотация("Сущность")
+Процедура ПриСозданииОбъекта(ИмяТаблицы = Неопределено, &Повторяемый ИсточникДанных = Неопределено)
+КонецПроцедуры

src/Классы/ИсточникДанных.os

@@ -0,0 +1,37 @@
+Перем пИмя;
+Перем пТипКоннектора;
+Перем пСтрокаСоединения;
+Перем пПараметрыКоннектора;
+
+Функция Имя() Экспорт
+	Возврат пИмя;
+КонецФункции
+
+Функция ТипКоннектора() Экспорт
+	Возврат пТипКоннектора;
+КонецФункции
+
+Функция СтрокаСоединения() Экспорт
+	Возврат пСтрокаСоединения;
+КонецФункции
+
+Функция ПараметрыКоннектора() Экспорт
+	Возврат пПараметрыКоннектора;
+КонецФункции
+
+Процедура ПриСозданииОбъекта(
+	Знач Имя,
+	Знач ТипКоннектора,
+	Знач СтрокаСоединения = "",
+	Знач ПараметрыКоннектора = Неопределено
+)
+
+	пИмя = Имя;
+	пТипКоннектора = ТипКоннектора;
+	пСтрокаСоединения = СтрокаСоединения;
+
+	Если ПараметрыКоннектора = Неопределено Тогда
+		ПараметрыКоннектора = Новый Массив();
+	КонецЕсли;
+	пПараметрыКоннектора = Новый ФиксированныйМассив(ПараметрыКоннектора);
+КонецПроцедуры

src/Классы/МенеджерСущностей.os

@@ -1,3 +1,4 @@
+#Использовать "../Аннотации"
 #Использовать "../internal"
 
 #Использовать asserts