Структура артефактов DataSpace#

О документе#

Документ предназначен для прикладного разработчика и содержит описание процесса формирования артефактов, необходимых для работы серверной (DataSpace Core) и клиентской (SDK) частей продукта Platform V DataSpace.

Расшифровку основных понятий см. в документе "Термины и определения".

Зависимости#

В корневом pom-файле проекта в качестве родительского артефакта необходимо указать dataspace-bom (версия указана для примера):

<parent>
  <groupId>sbp.com.sbt.dataspace</groupId>
  <artifactId>dataspace-bom</artifactId>
  <version>4.3.110</version>
  <relativePath/>
</parent>

В нем содержатся необходимые зависимости для корректной работы приложения, разрабатываемого с использованием DataSpace. Для обеспечения работоспособности не рекомендуется переопределять версии зависимостей, содержащиеся в родительском bom-файле.

Генерация артефактов DataSpace#

После описания модели предметной области необходимо выполнить генерацию артефактов для серверного компонента DataSpace Core (скрипты для БД и JPA классы для модуля). В случае использования SDK необходимо также выполнить генерацию SDK.

Примечание

Для вызова сервиса через JSON-RPС 2.0/GraphQL генерировать SDK не требуется.

Обе генерации выполняются при помощи одного maven-плагина, но разными целями.

<groupId>sbp.com.sbt.dataspace</groupId>
<artifactId>model-api-generator-maven-plugin</artifactId>

  • createModel — генерация артефактов серверного компонента;

  • createSdk — генерация артефактов SDK.

Генерация артефактов серверного компонента#

Минимальная конфигурация плагина для генерации артефактов серверного компонента:

<plugin>
    <groupId>sbp.com.sbt.dataspace</groupId>
    <artifactId>model-api-generator-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>createModel</id>
            <goals>
                <goal>createModel</goal>
            </goals>
            <configuration>
                <model>${model}</model>
                <basePackage>${modelPackage}</basePackage>
            </configuration>
        </execution>
    </executions>
</plugin>

где:

  • model — директория расположения файлов модели и статусов.
    При генерации проекта из архетипа (см. "Быстрый старт") устанавливается значение ${project.parent.basedir}/model/src/main/resources/model.

  • basePackage — пакет генерируемых JPA-классов. При генерации проекта из архетипа (см. "Быстрый старт") устанавливается значение groupId проекта.

Дополнительно могут быть указаны следующие конфигурационные параметры:

  • maxDBObjectNameLength — максимальная длина имени произвольного элемента (таблицы, индекса, поля и т.п.) в БД, по умолчанию — 63;

  • maxClassNameLength — максимально допустимая длина имени класса в модели, по умолчанию равна (maxDBObjectNameLength — 23), максимальное значение — 254;

  • maxPropertyNameLength — максимально допустимая длина имени свойства в модели, по умолчанию равна (maxDBObjectNameLength — 23), максимальное значение — 254;

  • minCroppedClassNameLength — минимально допустимая длина имени класса в результате урезания исходного, по умолчанию — 15, минимальное значение — 3;

  • minCroppedPropertyNameLength — минимально допустимая длина имени свойства в результате урезания исходного, по умолчанию — 15, минимальное значение — 3.

Примечание

Не рекомендуется изменять параметры maxClassNameLength, maxPropertyNameLength. В случае превышения длины имени элемента БД значения maxDBObjectNameLength, имя урезается до maxDBObjectNameLength символов.

Алгоритм урезания имен:

  1. Минимально урезается часть имени, относящаяся к имени класса, но не короче значения minCroppedClassNameLength. Сначала — для второго класса, участвующего в имени, если он присутствует, затем — для первого.

  2. Минимально урезается часть имени, относящаяся к имени свойства класса, но не короче значения minCroppedPropertyNameLength.

  3. При пересечении с уже существующими (или ранее сгенерированными) именами других объектов схемы данных добавляется числовой суффикс, состоящий из символа подчеркивания и последовательного номера. Он увеличивает номер на единицу, начиная с "1", пока не будет устранено пересечение с существующими именами.

Внимание!

При использовании DataSpace в интеграции с компонентом Прикладной журнал (APLJ) необходимо учитывать ограничение на длину полей, накладываемое компонентом Прикладной журнал (APLJ) и зависящее от версии данного компонента.

Установленная в DataSpace по умолчанию максимальная длина имени класса в сочетании с методом автогенерации идентификаторов агрегатов без префикса позволяет использовать любую версию компонента Прикладной журнал (APLJ).

При изменении схемы формирования идентификаторов агрегатов (с длиной более 19 символов) или при увеличении имени первого неабстрактного базового класса корня агрегата свыше 43 символов необходимо убедиться в том, что передаваемые через используемую версию компонента Прикладной журнал (APLJ) данные успешно реплицируются в StandIn и КАП.

Следует обратить внимание на то, что в данном случае при неуспешной репликации ошибка может не возникать. Необходимо убедиться в физическом наличии реплицируемых данных в StandIn и КАП.

После отработки goal createModel в папке target\classes модуля будут сформированы следующие ресурсы:

  • /db/* — Liquibase-скрипты для создания объектов БД;

  • /${modelPackage}/jpa/* — JPA-классы на основе описания модели.

Схема генерации артефактов показана на изображении ниже.

Генерация SDK#

SDK предназначен для работы с сервисами DataSpace на стороне Java-клиента в терминах зафиксированной модели данных. Разработчик пишет типизированный код для работы с данными на изменение/чтение, используя возможности DataSpace: идемпотентность, оптимистичное/пессимистичное блокирование ресурсов и т.д. Подробнее с функциональными возможностями можно ознакомиться в документе "Руководство прикладного разработчика".

Минимальная конфигурация плагина для генерирования SDK:

<plugin>
    <groupId>sbp.com.sbt.dataspace</groupId>
    <artifactId>model-api-generator-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>createSdk</id>
            <goals>
                <goal>createSdk</goal>
            </goals>
            <configuration>
                <model>${model}</model>
                <basePackage>${modelPackage}</basePackage>
            </configuration>
        </execution>
    </executions>
</plugin>

где:

  • model — директория расположения файлов модели и статусов.
    При генерации проекта из архетипа (см. документ "Быстрый старт") устанавливается значение ${project.parent.basedir}/model/src/main/resources/model.

  • basePackage — пакет генерируемых SDK-классов.
    При генерации проекта из архетипа (см. документ "Быстрый старт") устанавливается значение groupId проекта.

После работы goal createSdk в папке target\classes модуля генерируются следующие файлы:

  • /${modelPackage}/packet — классы SDK для формирования CRUD-операций в терминах модели данных и объединения их в один транзакционный пакет: UnitOfWork.

  • /${modelPackage}/graph — классы SDK для формирования представлений на запрос информации в терминах модели данных.

  • /${modelPackage}/grasp — классы SDK для формирования условий фильтрации к представлениям в терминах модели данных.

На схеме ниже показана генерация артефактов модели и SDK.

Примечание

В конце процесса генерации goal createSDK сформирует элементарные тесты, которые проверят модель на такие действия, как создание, сохранение и поиск. Формирование этих тестов можно отключить булевым параметром enableTestGoal. Значение по умолчанию: true.

Использование SDK#

В случае использования сгенерированного шагом ранее SDK в составе клиентского (стороннего) проекта требуется подключить дополнительные зависимости в pom.xml.

Примечание

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

<dependency>
    <groupId>sbp.com.sbt.dataspace</groupId>
    <artifactId>sdk-api</artifactId>
</dependency>

Также нужна зависимость на сгенерированную шагом ранее SDK:

<dependency>
    <groupId>sbp.com.sbt.dataspace</groupId>
    <artifactId>quickstart-model-sdk</artifactId>
</dependency>

Схема генерации артефактов модели, SDK и варианты использования сервисов DataSpace показаны на изображении ниже.

После добавления зависимостей можно приступить к написанию бизнес-логики с использованием SDK. Для этого нужно реализовать формирование пакетов UnitOfWork.
На основе пакета, указанного в параметре basePackage, сгенерировался пакет packet с классом Packet. Этот пакет следует использовать для формирования пакета CRUD-команд.

Действия в Packet сгруппированы по каждой сущности:

Внимание!

Пакет — транзакционная и маршрутизируемая единица. Описание правил транзакционности внутри пакета доступно в разделе "Транзакционная граница пакета" в документе "Руководство прикладного разработчика".

Инструкции по подключению dataspace-core в unit-тестах можно найти в документе "Локальный запуск DataSpace Core в Unit-тестах".