Чек-лист при создании и расширении сущности

THESIS Studio Guidelines
1

В разделе приведены рекомендации по созданию и сопровождению сущностей в THESIS Studio. Сведения предназначены для учета особенностей платформы при проектировании модели данных, настройке наследования, экранов, представлений и сценариев базы данных.

Важно!
Раздел находится в разработке.

Класс сущности

BaseCreatableUuidEntity

Если для сущности требуется использовать BaseUuidEntity и одновременно хранить сведения о ее создании, рекомендуется наследовать сущность от BaseCreatableUuidEntity.

NamePattern

Аннотация NamePattern определяет строковое представление сущности. Это представление используется, в частности, при выборе сущности в элементах Lookup.

Если NamePattern не задан, строковое представление формируется по шаблону:

<EntityClass>-<InstanceUUID>

При расширении сущности, если собственное значение NamePattern не указано, используется значение из родительской сущности. Поиск выполняется вверх по иерархии, начиная с текущего класса.

Если требуется задать собственное значение NamePattern, рекомендуется использовать только атрибуты родительской сущности. Использование атрибутов потомка может привести к ошибкам на экранах, где выполняется выбор сущностей родительского типа. Это связано с тем, что родительская сущность не содержит сведений об атрибутах потомка.

Например, в иерархии карточек wf$Card использует атрибут description, содержащий строковое представление карточки. Все дочерние сущности используют тот же NamePattern, а значение атрибута description изменяется в слушателях сущностей. Такой подход снижает риск ошибок при работе с иерархией сущностей.

Слушатели сущностей

Слушатели сущностей рекомендуется использовать, если обработка сущности выполняется в нескольких местах проекта. Это позволяет сосредоточить связанную логику в одном месте. Кроме того, слушатель выполняется на уровне core, что дает доступ к базе данных без дополнительного обращения через сервисы.

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

Следует учитывать, что слушатели родительских сущностей также выполняются для дочерних сущностей.

Дискриминатор

Если предполагается, что сущность в дальнейшем будет расширяться в текущем проекте или в проектах расширения, рекомендуется заранее определить стратегию наследования и значение дискриминатора. Это позволит избежать дополнительных сценариев обновления базы данных в дальнейшем.

Стратегия наследования

Выбор стратегии наследования зависит от структуры модели и предполагаемого использования сущностей.

Стратегия SINGLE_TABLE, как правило, обеспечивает более высокую производительность. Однако при наличии нескольких сущностей в одной иерархии могут возникать сложности при использовании такой сущности в качестве атрибута с отношением «многие», поскольку EclipseLink не всегда может корректно определить конкретный тип дочерней сущности.

Стратегия JOIN предпочтительна, если дочерние сущности имеют существенно различающиеся наборы атрибутов или количество таких атрибутов велико.

Аннотация PrimaryKeyJoinColumn

В аннотации @PrimaryKeyJoinColumn параметр referencedColumnName указывает столбец в корневой таблице иерархии, а не в таблице непосредственного родителя. В качестве примера можно использовать иерархию карточек ТЕЗИС.

Изменение стратегии наследования

одной иерархии наследования допускается сочетание разных стратегий, однако в EclipseLink поддерживается только переход от JOIN к SINGLE_TABLE.

Аннотация @Inheritance задается только для корневой сущности иерархии. Чтобы использовать SINGLE_TABLE внутри иерархии JOIN, в аннотации @Table необходимо указать таблицу родительской сущности.

Пример для двух сущностей в иерархии:

@Entity(name = "ex$Root")
@Table(name = "ROOT")
@Inheritance(strategy = InheritanceType.JOINED)
@DiscriminatorColumn(name = "TYPE", discriminatorType = DiscriminatorType.INTEGER)
@DiscriminatorValue("0")
public class Root extends StandardEntity {
}

@Entity(name = "ex$SubOne")
@Table(name = "ROOT")
@DiscriminatorValue("1")
public class Sub1 extends Root {
}

В этом случае для Sub1 достаточно указать аннотацию @Table с таблицей родительской сущности.

Если переход выполняется на втором или последующем уровне иерархии, необходимо дополнительно указывать @PrimaryKeyJoinColumn.

@Entity(name = "ex$SubTwo")
@Table(name = "SUB_TWO")
@PrimaryKeyJoinColumn(name = "REF_ID", referencedColumnName = "ID")
@DiscriminatorValue("2")
public class Sub2 extends Sub1 {
}

@Entity(name = "ex$SubThree")
@Table(name = "SUB_TWO")
@PrimaryKeyJoinColumn(name = "REF_ID", referencedColumnName = "ID")
@DiscriminatorValue("3")
public class Sub3 extends Sub2 {
}

Значение параметра name в @PrimaryKeyJoinColumn для Sub2 и Sub3 совпадает, так как обе сущности хранятся в одной таблице. В этом случае Sub2 задает столбец внешнего ключа, а Sub3 использует его.

SystemLevel

Аннотацию SystemLevel рекомендуется использовать для сущностей, которые обрабатываются программно и не имеют собственных пользовательских экранов. Например, такие сущности могут использоваться для композиции набора атрибутов.

Атрибуты сущности

Не рекомендуется использовать ограничение not null без дополнительной проверки и значения по умолчанию. Если атрибут должен быть обязательным, следует задать значение по умолчанию в сценарии создания таблицы и контролировать обязательность заполнения на уровне приложения. В противном случае у пользователей могут возникать неочевидные ошибки при создании или изменении сущностей, особенно при расширении сущности.

При добавлении, удалении или изменении типа атрибута необходимо:

  • добавить сценарий обновления базы данных и изменить сценарии инициализации базы данных;

  • оценить необходимость создания индекса, включая составные и частичные индексы;

  • для карточек — добавить атрибут в вид документа или тип карточки;

  • добавить, удалить или изменить атрибут во всех представлениях сущности;

  • обновить конфигурации FTS, а для карточек также TypedEntities и LoggedEntities;

  • обновить экраны сущности, включая элементы, столбцы, фильтры таблиц и пользовательские условия;

  • проверить настройки экранов, в том числе столбцы таблиц;

  • проверить системные и пользовательские фильтры;

  • проверить запросы на всех уровнях: в бинах, экранах, отчетах, процессах и папках;

  • при удалении атрибута удалить связанные с ним правила в ролях.

Индексы рекомендуется создавать с учетом характера использования атрибута:

  • для атрибута-сущности индекс целесообразен, если по связи хранится большое количество записей;

  • для атрибута-данных индекс целесообразен, если часто выполняется фильтрация по точному совпадению значения;

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

Конфигурационные файлы

При создании и изменении сущностей необходимо учитывать связанные конфигурационные файлы:

  • FTS;

  • Logged;

  • Typed;

  • настройки автоматической замены Lookup на Picker.

Группы доступа

При добавлении новых сущностей следует определить необходимость настройки групп доступа.

Разрешения для ролей

Для новых или измененных сущностей необходимо проверить состав разрешений в ролях.

Экраны

При изменении модели сущности необходимо проверить связанные экраны.

Editor

Для экранов редактирования необходимо учитывать правила, применяемые из вида документа, а также настройки AccessManager.

Lookup и Browse

Для экранов выбора и списочных экранов необходимо проверить состав отображаемых полей, фильтры и пункты меню.

Папки

При необходимости следует обновить настройки папок, если в них используются изменяемые сущности или атрибуты.

Файлы свойств

При изменении сущностей необходимо проверить связанные значения в файлах свойств проекта.

Типы карточек

Для карточек необходимо проверить регистрацию в типах карточек и связанные настройки.

Основание

При использовании сущности в качестве основания необходимо проверить связанные настройки и сценарии обработки.

Рекомендации по разработке (Guidelines)