Dynamic Properties (динамические свойства)

Dynamic Properties (DPS) — это механизм описания динамических форм и наборов полей в be5. DPS — упорядоченный набор именованных свойств, где каждое свойство имеет имя (name), тип (type), значение (value) и произвольные атрибуты (атрибуты управляют внешним видом, поведением и валидацией поля в интерфейсе).

DPS используются в be5 для:

  • описания параметров операций (полей формы операции) — GOperationSupport.params;

  • описания форм сущностей и запросов (наборы колонок) — DpsHelper;

  • представления результатов SQL-запросов — QRec;

  • моделирования «живых» строк БД — RecordModel.

Базовый API предоставляют классы модуля beanexplorer/beans (артефакт com.developmentontheedge:beans): интерфейс DynamicPropertySet, реализации DynamicPropertySetSupport/GDynamicPropertySetSupport, единичное свойство DynamicProperty и набор констант-атрибутов BeanInfoConstants.

Оглавление

  1. Иерархия классов — основные классы DPS API и их назначения

  2. Типы свойств (TYPE) — Java-классы значений, файловые типы, вложенные формы

  3. Атрибуты свойств — все атрибуты: базовые, тег-списки, группировка, валидация, спецконтролы

  4. Как задаются свойства — Groovy-DSL, мапы, Java builder, DpsHelper

  5. Как атрибуты потребляются — сериализация в JSON, проверка значений

Иерархия классов

Класс Модуль Назначение
DynamicPropertySet beanexplorer/beans Интерфейс — контракт набора динамических свойств
AbstractDynamicPropertySet beanexplorer/beans Абстрактная базовая реализация
DynamicPropertySetSupport beanexplorer/beans Основная (каноническая) реализация: add, edit, remove, moveTo, asMap, build(name, class), makeBetterDisplayName и т.д.
DynamicPropertySetAsMap beanexplorer/beans Реализация, хранимая в Map
DynamicPropertySetDecorator / DynamicPropertySetBlocked beanexplorer/beans Декораторы; Blocked — read-only обёртка
DynamicProperty beanexplorer/beans Одно свойство: name, type, value, displayName + атрибуты (setAttribute, getAttribute)
DynamicPropertyBuilder beanexplorer/beans Java-fluent builder для создания DynamicProperty
GDynamicPropertySetSupport be5/base (com.developmentontheedge.be5.groovy) Groovy-DSL поверх DynamicPropertySetSupport: add { name = ... }, add(name, displayName) { ... }, edit(name) { ... }, доступ dps[name] = значение, dps._name = объект свойства, with { ... }, << (мапа), + (объединение)
QRec be5/database DPS-представление одной строки результата SQL; типизированные доступы getString, getInt, getLong, getDate
RecordModelBase<T> / RecordModel<T> be5/database-model DPS, привязанный к строке БД: запись значения — через update(name, value) (через EntityModel), setValue запрещён

Типы свойств (TYPE)

Тип (TYPE) свойства определяет класс Java, в который приводится значение поля. По умолчанию — String.class. Тип сериализуется в JSON-мета как имя класса (Class.getSimpleName()) и используется клиентским UI для выбора контрола ввода.

Тип Класс UI (React) Примечание
String java.lang.String Текстовый <input> Тип по умолчанию; многострочный — через EXTRA_ATTRS = ["inputType": "textArea"]
Boolean java.lang.Boolean Checkbox При READ_ONLY — disabled, а не readonly
Short java.lang.Short Числовой <input type="number"> В VALIDATION_RULES автоматически добавляется step
Integer java.lang.Integer Числовой <input type="number"> В VALIDATION_RULES автоматически добавляется step; для INTEGER-колонок DpsHelper добавляет range
Long java.lang.Long Числовой <input type="number"> Аналогично Integer
Double java.lang.Double Числовой <input type="number"> Аналогично
Date java.sql.Date Контрол даты (DateTimePropertyInput)
Time java.sql.Time Контрол времени (DateTimePropertyInput)
Timestamp java.sql.Timestamp Контрол даты+времени (DateTimePropertyInput)
File java.io.File <input type="file"> (FilePropertyInput) Загрузка как multipart-файл; см. Файловые типы
Base64File com.developmentontheedge.be5.server.model.Base64File <input type="file"> (Base64FilePropertyInput) Загрузка в base64-JSON; см. Файловые типы
GDynamicPropertySetSupport com.developmentontheedge.be5.groovy.GDynamicPropertySetSupport Скрытое поле с JSON-строкой Вложенная форма (группа полей); см. Вложенные формы
любой другой Class произвольный Текстовый <input> Значение парсится в нужный тип при приёме запроса (JsonFactory.getSimpleValueFromJson)

2.1. Файловые типы

File — multipart-загрузка

Клиентский UI рендерит как <input type="file"> (FilePropertyInput). Значение отправляется как настоящий multipart-файл (а не base64-JSON). На сервере такие запросы обрабатываются через FileUploadWrapper (модуль web), который превращает multipart в Map<String, List<FileItem>>.

params.add("attachment", "Файл") {
    TYPE = File   // java.io.File
}

Base64File — base64-JSON

Base64File (be5/server/.../server/model/Base64File.java) — специальный тип свойства для полей загрузки файлов. Клиентский UI рендерит его как <input type="file"> (Base64FilePropertyInput, при READ_ONLY — disabled), а отправляемое значение — JSON:

{"type":"Base64File","name":"<имя файла>","data":"data:<mime>;base64,<base64-данные>"}

Серверная сторона распарсивает такие значения автоматически (ParseRequestUtils.checkAndParseBase64File), поэтому в операции значение поля приходит уже как объект Base64File:

Base64File file = (Base64File) ((DynamicPropertySet) parameters).getValue("picture");
file.getName();      // имя файла
file.getMimeTypes(); // MIME-тип
file.getData();      // байты файла

Определение такого поля в Java:

dps.add(new DynamicProperty("picture", "Picture", Base64File.class));

или в Groovy:

params.add("picture", "Файл") {
    TYPE = Base64File   // com.developmentontheedge.be5.server.model.Base64File
}

Мультизагрузка файлов (для обоих типов) — MULTIPLE_SELECTION_LIST = true (multiple в <input type="file">).

2.2. Вложенные формы

Типом свойства может быть сам GDynamicPropertySetSupport — в этом случае значение поля является вложенной формой (группой полей). Клиентский UI рендерит такое поле как скрытое текстовое поле, содержащее JSON-строку (сериализованный DPS).

Атрибуты свойств

Атрибуты задаются на конкретное свойство. Ключи атрибутов — константы интерфейса BeanInfoConstants (модуль beanexplorer/beans). В Groovy-DSL константы доступны по имени (TAG_LIST_ATTR, CSS_CLASSES, …), в Java — через строковые ключи ("tag-list-attr") или BeanInfoConstants.TAG_LIST_ATTR.

Важно. В Groovy-closure (dps.add { ... }) доступны только те атрибуты, для которых определены setter“ы в классе DPSAttributes (be5/base/.../groovy/meta/DPSAttributes.java): name, DISPLAY_NAME, TYPE, value, READ_ONLY, HIDDEN, RAW_VALUE, RELOAD_ON_CHANGE, RELOAD_ON_CLICK, RELOAD_ON_FOCUS_OUT, CAN_BE_NULL, MULTIPLE_SELECTION_LIST, PASSWORD_FIELD, LABEL_FIELD, TAG_LIST_ATTR, EXTRA_ATTRS, VALIDATION_RULES, COLUMN_SIZE_ATTR, INPUT_SIZE_ATTR, PLACEHOLDER, GROUP_ID, GROUP_NAME, GROUP_CLASSES, GROUP_INITIALLY_CLOSED, TAB_ID, TAB_NAME, TAB_CLASSES, DEFAULT_VALUE, CSS_CLASSES, STATUS, MESSAGE. Через Java (DynamicProperty.setAttribute / DynamicPropertyBuilder.attr) можно задать любой атрибут из BeanInfoConstants.

3.1. Базовые атрибуты

Атрибут Строковый ключ Тип Описание
DISPLAY_NAME displayName String Отображаемое имя поля (метка над полем)
DEFAULT_VALUE defaultValue Object Значение по умолчанию, если getter возвращает null
READ_ONLY read-only boolean Поле только для чтения
HIDDEN node-hidden boolean Скрыть поле из интерфейса
CAN_BE_NULL can-be-null boolean Поле допускает пустое значение
RAW_VALUE raw-value boolean Вставлять значение в разметку без экранирования (например, HTML-лейблы)
STATUS status String Статус валидации, отображаемый в UI (например, "error")
MESSAGE message String Сообщение, сопутствующее STATUS
HELP_ID help-id String Идентификатор контекстной помощи
TOOLTIP tooltip String Подсказка (tooltip) поля
ORDER properties-order Object Явный порядок свойств
CHILD_DISPLAY_NAME childDisplayName String Метод/имя для расчёта display-name элементов массива
CHILD_READ_ONLY child-read-only boolean Элементы массива — только для чтения
FORMAT_MASK format-mask String Формат строки значения
NUMBER_FORMAT number-format String/NumberFormat Формат чисел (DecimalFormat или паттерн); "none" — без форматирования
PLACEHOLDER placeholder String Текст-заглушка в поле ввода

3.2. Тег-списки и выпадающие

Атрибут Строковый ключ Тип Описание
TAG_LIST_ATTR tag-list-attr String[][] / Map / Object[] Варианты для выпадающего списка. Формат: пары [значение, подпись] (String[][]), мапа значение→подпись или просто массив значений
MULTIPLE_SELECTION_LIST multiple-selection-list boolean Мультивыбор (список чекбоксов)
USE_AUTOCOMPLETE use-autocomplete boolean Рендерить поле как autocomplete
USE_SELECT2 use-select2 boolean Рендерить поле как select2
USE_CHOSEN use-chosen boolean Рендерить поле как chosen
DYNAMIC_TAG_LIST_ATTR dynamic-tag-list-attr Object Динамический источник тегов (загружается асинхронно)
NO_TAG_LIST no-tag-list boolean Явно отключить список тегов
NO_TAG_LIST_SHRINK_ATTR no-tag-list-shrink-attr boolean Не «схлопывать» поле без списка тегов
EXTERNAL_TAG_LIST external-tag-list String Внешний источник тегов (таблица)
ORIG_PROPERTY_ENTITY_ATTR origEntity String Имя сущности-источника внешнего списка
ORIG_PROPERTY_NAME_ATTR origName String Имя колонки-источника внешнего списка
SKIP_L10N skip-localization-attr boolean Не локализовать подпись поля
SKIP_SERVER_NULL_CHECK skip-server-null-check boolean Не проверять null на сервере

Типичный источник тегов для операций — QueriesService (поле queries в OperationSupport):

  • queries.getTagsFromSelectionView(tableName[, params]) — стандартный выборочный view;

  • queries.getTagsFromCustomSelectionView(tableName, queryName[, params]) — пользовательский query из метаданных;

  • queries.getTagsFromEnum(tableName, name) / getTagsFromEnum(columnDef) — перечисление (enum) колонки.

Все методы возвращают String[][] (пары [значение, подпись]), готовую к присваиванию TAG_LIST_ATTR.

3.3. Группировка и вкладки

Атрибут Строковый ключ Тип Описание
GROUP_ID group-id String Идентификатор группы (сворачиваемая панель формы)
GROUP_NAME group-name String Заголовок группы
GROUP_CLASSES group-classes String CSS-классы панели группы
GROUP_INITIALLY_CLOSED group-initially-closed boolean Группа свёрнута изначально
GROUPING_PROPERTY grouping Object Значение свойства используется для группировки наборов бин-объектов
TAB_ID tab-id String Идентификатор вкладки
TAB_NAME tab-name String Заголовок вкладки
TAB_CLASSES tab-classes String CSS-классы вкладки
CSS_CLASSES css-classes String CSS-классы для контрола самого поля (например, col-lg-6)

3.4. Размеры и форматирование

Атрибут Строковый ключ Тип Описание
INPUT_SIZE_ATTR input-size-attr Integer Размер поля ввода (size)
COLUMN_SIZE_ATTR column-size-attr Integer Ширина в колонках
NCOLUMNS_ATTR cols-attr Integer Число колонок (например, для textarea)
NROWS_ATTR rows-attr Integer Число строк (например, для textarea)

3.5. Поведение формы

Атрибут Строковый ключ Тип Описание
RELOAD_ON_CHANGE reload-on-change boolean Пересылать форму при изменении значения поля
RELOAD_ON_CLICK reload-on-click boolean Пересылать форму по клику на поле
RELOAD_ON_FOCUS_OUT reload-on-focus-out* boolean Пересылать форму при потере фокуса (*Groovy-only, не входит в BeanInfoConstants)

3.6. Специальные контролы и видимость

EXTRA_ATTRS — свободные HTML/JS-атрибуты

EXTRA_ATTRS (extra-attrs-attr) — не фиксированный набор: произвольные пары [ключ, значение], которые передаются в HTML-разметку контрола поля как есть. Формат значения — Map или String[][], в JSON-мета сериализуется как extraAttrs (список пар).

Служебный ключ inputType (константа PROPERTY_INPUT_TYPE, строковый ключ "inputType") определяет тип контрола:

Значение Где применяется Описание
textArea DpsHelper автоматически для колонок TEXT Многострочное поле ввода
AsyncSelect Задаётся вручную Асинхронный выпадающий список: варианты загружаются по запросу. Требует дополнительных пар entity (сущность) и query (имя запроса)
button Задаётся вручную Поле-кнопка. При таком типе Validator пропускает null-проверку значения
radio Задаётся вручную Рендерит TAG_LIST_ATTR как radio-кнопки, а не select
WYSIWYG Задаётся вручную Rich-text редактор (WYSIWYGPropertyInput)
произвольное Через registerPropertyInput(name, component) Зарегистрированный кастомный React-компонент

JavaScript-обработчики: любые пары вида [onchange, js], [onclick, js] подставляются в контрол как HTML-атрибуты с JS-выражением, например ["onchange", "this.form.submit()"].

Примеры:

// Groovy — Map
params.add("request", "Заявка на закупку") {
    EXTRA_ATTRS = ["inputType": "AsyncSelect", "entity": "testtable"]
}

// Groovy — обработчики
params.add("status", "Статус") {
    EXTRA_ATTRS = ["onchange": "this.form.submit()"]
}
// Java — builder
dps.add(new DynamicPropertyBuilder("request", String.class)
        .extraAttrs(Map.of("inputType", "AsyncSelect", "entity", "testtable"))
        .onchange("this.form.submit()")
        .get());

Кто потребляет EXTRA_ATTRS:

  • Клиентский UI (React) — читает extraAttrs из JSON-мета: рендерит контрол по inputType, остальные пары подставляет как HTML-атрибуты поля.

  • Validator (модуль operation) — читает inputType из EXTRA_ATTRS, чтобы пропустить null-проверку для button.

  • DpsHelper (модуль server) — сам выставляет EXTRA_ATTRS с inputType=textArea для TEXT-колонок.

Прочие специальные контролы

Атрибут Строковый ключ Тип Описание
LABEL_FIELD label-field boolean Рендерить как обычный текстовый лейбл, а не ввод
PASSWORD_FIELD password-field boolean Поле пароля
BUTTON_FIELD button boolean Поле-кнопка
RICH_TEXT rich-text boolean Rich-текст редактор
COLOR_PICKER color-picker boolean Выбор цвета
CUSTOM_INPUT_TYPE_ATTR custom-input-type-attr Object Произвольный тип ввода
CUSTOM_EDITOR_ATTR custom-editor-attr Object Произвольный редактор поля
PSEUDO_PROPERTY pseudo-property boolean «Псевдо»-свойство (служебное, не колонка БД)
SKIP_SMART_BOOLEAN_TRUNC_ATTR skip-smart-boolean-trunc-attr boolean Не обрезать «умные» булевы значения
NO_WRAP_LABELS no-wrap-labels-attr boolean Не переносить строки в лейблах
SEMANTIC_RULES semantic-rules Object Семантические правила поля
ARRAY_ITEM_TEMPLATE arrayItemTemplate Object Шаблон элемента массива

3.7. Валидация значений

Правила валидации задаются атрибутом VALIDATION_RULES (validation-rules) как список объектов ValidationRules.Rule (модуль operation, класс com.developmentontheedge.be5.operation.validation.ValidationRules). Каждое правило сериализуется в JSON-мета как {"type": "<имя>", "attr": <параметры>} и проверяется и на клиенте (маска ввода, range/step для чисел), и на сервере (Validator в модуле operation).

Правило Метод JSON Описание
range ValidationRules.range(min, max) или range(min, max, customMessage) {"type":"range","attr":{"min":"...","max":"..."}} Значение в диапазоне [min, max]
step ValidationRules.step(value) или step(value, customMessage) {"type":"step","attr":"..."} Шаг/точность значения (для чисел)
pattern ValidationRules.pattern(regex) или pattern(regex, customMessage) {"type":"pattern","attr":"<regex>"} Регулярное выражение; на клиенте при наличии pattern-правила UI использует react-maskedinput с этой маской
unique ValidationRules.unique(tableName), unique(tableName, column, message) {"type":"unique","attr":{"tableName":"..."}} Уникальность значения в указанной таблице (проверка на сервере)
mask (встроенный клиентский) {"type":"mask","attr":"<маска>"} Маска ввода на клиенте (react-maskedinput)

Предопределённые правила — ValidationRules.DefaultRules, доступные по имени:

Правило Описание
ipPattern IP-адрес по маске 255.255.255.255 (4 октета, каждая 0–255)

Примеры:

// Groovy — closure
params.add("amount", "Сумма") {
    TYPE = Integer
    VALIDATION_RULES = [
        ValidationRules.range(1, 1000),
        ValidationRules.step(1),
        ValidationRules.unique("documents", "id", "Значение уже существует")
    ]
}
// Java — builder
dps.add(new DynamicPropertyBuilder("amount", Integer.class)
        .attr("validation-rules", Arrays.asList(
            ValidationRules.range(1L, 1000L),
            ValidationRules.step(1L)
        ))
        .get());

Кто потребляет VALIDATION_RULES:

  • Клиентский UI (React) — читает validationRules из JSON-мета: range/step для NumberPropertyInput, pattern → react-maskedinput, mask → маска ввода.

  • Validator (модуль operation) — серверная проверка: null-проверка (с учётом CAN_BE_NULL и BUTTON_FIELD в EXTRA_ATTRS), range, step, pattern, unique, статус/сообщение ошибки записываются в STATUS/MESSAGE.

  • DpsHelper (модуль server) — автоматически выставляет range/step для числовых (INTEGER/DECIMAL) колонок при сборке DPS из модели.

3.8. Иконки (Swing-интроспекция)

Атрибут Строковый ключ Описание
NODE_ICON_COLOR_16x16 node-icon: color16x16 Иконка 16×16, цветная
NODE_ICON_COLOR_32x32 node-icon: color32x32 Иконка 32×32, цветная
NODE_ICON_MONO_16x16 node-icon: mono16x16 Иконка 16×16, монохромная
NODE_ICON_MONO_32x32 node-icon: mono32x32 Иконка 32×32, монохромная

Как задаются свойства

4.1. Groovy-DSL (основной способ в операциях)

В Groovy-операциях, наследующих GOperationSupport, поле params — это GDynamicPropertySetSupport. Варианты add:

class MyOperation extends GOperationSupport implements Operation
{
    Object getParameters(Map<String, Object> presetValues)
    {
        // 1) name задаётся внутри closure
        params.add {
            name = "request"
            DISPLAY_NAME = "Заявка на закупку"
            TAG_LIST_ATTR = queries.getTagsFromCustomSelectionView("documents", "Заявки на закупку")
            CSS_CLASSES = "col-lg-6"
            GROUP_ID = "purchase"
            GROUP_NAME = "Закупка"
        }

        // 2) name и displayName — аргументы метода
        params.add("beginDate", "Дата начала") {
            TYPE = java.sql.Date
        }

        // 3) только name / name + displayName
        params.add("reason", "Причина")

        return DpsUtils.setValues(params, presetValues)
    }
}

edit(name) { ... } — изменить атрибуты уже существующего свойства.

Доступ к значениям и свойствам:

def value = params["reason"]      // значение свойства
def prop  = params._reason        // объект DynamicProperty
params.with { reason = "vacation" }  // установка значения

4.2. Мапа (Groovy)

params << [
    name          : "reason",
    DISPLAY_NAME  : "Причина увольнения",
    TAG_LIST_ATTR : [["fired", "Уволен"], ["vacation", "Отпуск"]] as String[][],
    CAN_BE_NULL   : true,
    value         : "vacation"
]

4.3. Java fluent builder

DynamicPropertySet dps = new DynamicPropertySetSupport();
dps.add(new DynamicPropertyBuilder("name", String.class)
        .value("text")
        .title("Имя")
        .tags(new String[] { "one", "two", "three" })
        .attr("css-classes", "col-lg-6")
        .get());

Полезные методы builder“а: value, title, readonly, nullable, hidden, tags, dynamicTags, multiple, attr, extraAttrs, onchange, onclick, placeholder, reloadOnChange, reloadOnClick, columnSize, size, group(groupId, name), tab(id, name), rawValue, inputType, autocomplete, select2, chosen, external(tableFrom, col, tableTo), noServerCheck.

4.4. Автоматическая сборка из модели (DpsHelper)

Сервис DpsHelper (be5/server/.../services/DpsHelper.java) собирает DPS из метаданных сущности: addDp, addDpForColumns, addDpExcludeAutoIncrement, addParamsFromQuery, addLabel, addLabelRaw. Для каждой колонки автоматически выставляются PLACEHOLDER, CAN_BE_NULL, EXTRA_ATTRS (например, textArea для TEXT), COLUMN_SIZE_ATTR, VALIDATION_RULES (range/step для числовых типов), локализованное DISPLAY_NAME, а addTags заполняет TAG_LIST_ATTR из enum“ов, yes-no значений и выборочных view внешних ключей.

Как атрибуты потребляются

Атрибуты сериализуются в JSON-мета для клиентского UI через JsonPropertyAttributes (модуль beanexplorer/json). JSON-ключи, которые видит клиент: tagList, multipleSelectionList, canBeNull, readOnly, hidden, rawValue, reloadOnChange, reloadOnClick, groupId / groupName / groupClasses / groupInitiallyClosed, tabId / tabName / tabClasses, cssClasses, columnSize, inputSize, placeholder, status / message, defaultValue, extraAttrs, validationRules, labelField, passwordField.

Проверка значений при записи — DpsUtils (модуль database-model: поиск имени тега, проверка принадлежности значения к списку тегов) и Validator (модуль operation).