Операции: серверная часть

Операция на стороне сервера — это Java/Groovy-класс, реализующий интерфейс Operation, который вызывается при отправке формы операции (REST-запрос с параметром _on_=<имя>). Сервер:

  1. создаёт экземпляр класса операции (по имени из метаданных),

  2. вызывает getParameters(...) — получает форму параметров (DPS, см. attributes.md),

  3. отправляет форму клиенту,

  4. при отправке формы клиентом вызывает invoke(parameters) — выполняет действие,

  5. возвращает результат (finished, redirect, error).

Этот документ описывает серверную реализацию. YAML-декларация операций (атрибуты type, code, records, roles, layout) — см. operations.md.

Основные методы

Интерфейс Operation

Интерфейс (be5/operation/.../operation/Operation.java) определяет контракт, который должен соблюдать любой класс операции.

Метод Описание
void initialize(OperationInfo info, OperationContext context, OperationResult operationResult) Вызывается один раз при создании экземпляра операции. Передаёт метаданные операции (info), контекст (выбранные записи, параметры запроса) и начальный результат (статус create)
OperationInfo getInfo() Метаданные операции: имя, роль, тип, code, records, logging, confirm, entity, layout и др.
OperationContext getContext() Контекст вызова: выбранные записи (getRecords() — массив id, getRecord() — одна запись), имя запроса (getQueryName()), параметры запроса (getParams())
Object getParameters(Map<String, Object> presetValues) throws Exception Возвращает форму параметров операции как DynamicPropertySet (DPS). presetValues — карта предзаполненных значений (фильтры, язык и т.д.). Если вернуть null, форма не показывается и invoke вызывается сразу
void invoke(Object parameters) throws Exception Выполняет действие операции. Принимает результат getParameters (DPS, заполненный пользователем). Внутри вызывает setResult(...) / setResultFinished(...) для отчёта о завершении
OperationStatus getStatus() Текущий статус операции (enum: CREATE, GENERATE, EXECUTE, FINISHED, ERROR, REDIRECTED, ...)
OperationResult getResult() Текущий результат операции
void setResult(OperationResult operationResult) Задаёт результат (заканчивает операцию)
void setResultGoBack() Короткая форма: завершить с редиректом обратно в таблицу
void addRedirectParams(Map<String, ?> extra) / addRedirectParam(String name, Object value) Добавить параметры URL для редиректа

Контракт getParameters → invoke

  1. getParameters(Map presetValues) вызывается сервером при запросе формы.

    • Возвращает DynamicPropertySet (DPS) — описание полей формы (см. attributes.md).

    • presetValues — карта, которую сервер заполняет параметрами из запроса (фильтры, язык, выбранные записи и т.д.).

    • Если вернул null — форма не показывается, invoke вызывается сразу с null.

    • Если бросил исключение — операция переходит в статус ERROR.

  2. invoke(Object parameters) вызывается после отправки формы клиентом.

    • parameters — тот же DPS, что вернул getParameters, но с заполненными значениями от пользователя.

    • Внутри метода выполняете логику операции (запись в БД, вызов API и т.д.).

    • В конце вызываете setResultFinished(...) или setResult(OperationResult.error(...)).

Классы-база

BaseOperationSupport (модуль operation)

Абстрактный класс, реализующий Operation. Хранит три поля:

  • protected OperationInfo info — метаданные операции;

  • protected OperationContext context — контекст вызова;

  • private OperationResult operationResult — результат.

Реализует initialize, getInfo, getStatus, getResult, setResult и утилиты редиректа: redirectThisOperationNewId(Object newID), redirectToTable(entityName, queryName[, params]), setResultGoBack(), getBackUrl(), getUrlForNewRecordId(Object newID).

По умолчанию getParameters возвращает null (форма не показывается).

OperationSupport (модуль server)

Абстрактный класс, расширяющий BaseOperationSupport. Основной базовый класс для встроенных операций и пользовательских Java-операций.

Инжектированные поля (через Guice):

Поле Тип Назначение
meta Meta Метаданные проекта (сущности, запросы, операции)
userAwareMeta UserAwareMeta Метаданные с учётом ролей текущего пользователя
db DbService Сервис работы с БД (insert, execute, query)
database DatabaseModel Модель БД (сущности, колонки)
dpsHelper DpsHelper Утилита для построения DPS из модели сущности
validator Validator Валидатор значений DPS
queries QueriesService Сервис запросов (getTagsFromSelectionView, getTagsFromCustomSelectionView, getTagsFromEnum)
session Session Сессия пользователя
request Request HTTP-запрос (устанавливается через setRequest(...))
userInfo UserInfo Информация о пользователе (имя, роли, язык)

Полезные методы:

Метод Описание
setResultFinished() / setResultFinished(String message) Завершить операцию успешно (с опциональным сообщением)
setResultFinished(String message, FrontendAction... actions) Завершить с сообщением и действиями для клиента (например, goBackOrRedirect, closeMainModal)
redirectThisOperation() Завершить с редиректом обратно в форму операции
setResultGoBack() Завершить с редиректом обратно в таблицу
getFileItem(String fileName) Получить FileItem из запроса (для операций с загрузкой файлов)
isModalFormLayout() Проверить, задан ли layout: {"type":"modalForm"}
localize(String text) Локализовать строку (с поддержкой {{{...}}} токенов)
localizeTags(String[][] tags) Локализовать список тегов

GOperationSupport (модуль server)

Абстрактный класс, расширяющий OperationSupport. Базовый класс для Groovy-операций. Добавляет одно публичное поле:

public GDynamicPropertySetSupport params = new GDynamicPropertySetSupport();

Это params, который вы используете в Groovy-коде (params.add { ... }). См. attributes.md → «Как задаются свойства» для Groovy-DSL.

DownloadOperationSupport (модуль server)

Абстрактный класс для операций скачивания файлов. invoke строит действие FrontendActions.downloadOperation(...), и браузер делает отдельный запрос к DownloadOperationController. Вы должны реализовать абстрактный метод:

abstract void invokeWithResponse(Response res, Object parameters);

Внутри него пишете байты в res (например, RequestUtils.sendFile(res, file)).

Типы операций

В метаданных операции имеют атрибут type. Сервер поддерживает:

type Описание
Groovy Groovy-класс, компилируемый на лету. code/file — путь к .groovy файлу (относительно src/main/groovy). Класс должен расширять GOperationSupport (или встроенную операцию) и реализовывать Operation
Java Java-класс, загружаемый через Class.forName. code — полное имя класса. Класс должен расширять OperationSupport (или встроенную операцию) и реализовывать Operation
SQL (не реализовано в open-source). В метаданных тип существует, но серверный исполнитель для SQL-операций отсутствует. SQL-запросы выполняются вручную внутри Java/Groovy-операции через db.insert(...), db.execute(...), db.query(...)
JavaScript/server (enterprise-only). Серверный JS-движок (Rhino/Nashorn) не входит в open-source. Реализация в enterprise-версии: com.developmentontheedge.enterprise.operations.JavaScriptOperationExtenderSupport

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

Operation (интерфейс, модуль operation)
├── BaseOperationSupport (абстрактный, модуль operation)
│   └── OperationSupport (абстрактный, модуль server)
│       ├── GOperationSupport (абстрактный, модуль server)
│       │   └── (пользовательские Groovy-операции)
│       ├── InsertOperation
│       │   └── SilentInsertOperation
│       ├── EditOperation
│       │   └── SilentEditOperation
│       ├── DeleteOperation (implements TransactionalOperation)
│       │   └── SilentDeleteOperation
│       ├── CloneOperation
│       │   └── SilentCloneOperation
│       ├── RestoreOperation (implements TransactionalOperation)
│       ├── FilterOperation
│       │   └── FilterByParamsInQueryOperation
│       └── DownloadOperationSupport (абстрактный)
│           └── GetLogFiles
└── TransactionalOperation (маркерный интерфейс, модуль operation)
    └── (реализуют DeleteOperation, RestoreOperation)

Пояснения:

  • TransactionalOperation — маркерный интерфейс. Операции, реализующие его, оборачиваются в транзакцию БД при выполнении invoke. Если статус становится ERROR, транзакция откатывается.

  • Silent* варианты — упрощённые версии встроенных операций: после invoke не показывают алерт, а сразу делают goBack() или setResult(finished(null, null, 0)) (тихое завершение без уведомления).

Встроенные операции

Класс Расширяет Что делает
InsertOperation OperationSupport Создание записи. getParameters строит DPS из модели сущности (dpsHelper.addDpExcludeAutoIncrement), invoke вызывает database.getEntity(entityName).add(entityParams). Хранит lastInsertID (доступен через getLastInsertID())
EditOperation OperationSupport Редактирование записи. getParameters загружает текущую запись, заполняет DPS её значениями. invoke: одна запись → database...set(record, entityParams), несколько → database...setIds(records, values) (bulk edit)
DeleteOperation OperationSupport + TransactionalOperation Удаление записей. getParameters строит информационную метку («N записей будет удалено») и read-only просмотр записи (для одного). invoke удаляет записи и каскадно удаляет ссылки из COLLECTION и GENERIC_COLLECTION таблиц. Детальное сообщение — только для SystemDeveloper
CloneOperation OperationSupport Клонирование записи. getParameters копирует значения выбранной записи в новый DPS. invoke создаёт новую запись (database...add(entityParams)), хранит lastInsertID
RestoreOperation OperationSupport + TransactionalOperation Восстановление (отмена soft-delete). getParameters проверяет наличие колонки IS_DELETED_COLUMN_NAME (если нет — ошибка). invoke обновляет isDeleted="no" в сущности и в сборочных таблицах
FilterOperation OperationSupport Стандартный фильтр таблицы. getParameters строит форму фильтра из модели, применяет пресеты поиска (FilterUtil.getSearchPresetNames), добавляет скрытые поля searchPresets и search=true. invoke собирает параметры запроса и вызывает documentGenerator.getDocument(query, params)
FilterByParamsInQueryOperation FilterOperation Переопределяет getFilterParameters, чтобы строить DPS из параметров самого запроса (dpsHelper.addParamsFromQuery)
SilentInsertOperation InsertOperation Тихая вставка: после super.invoke → если modal layout, setResult(finished(null, null, 0)), иначе setResultGoBack()
SilentEditOperation EditOperation Тихая правка: аналогично
SilentCloneOperation CloneOperation Тихое клонирование: аналогично
SilentDeleteOperation DeleteOperation Тихое удаление: аналогично
GetLogFiles DownloadOperationSupport Просмотр/скачивание лог-файлов. getParameters находит текущий FileAppender logback и предлагает выбор файла. invokeWithResponse стримит файл через RequestUtils.sendFile

Расширители операций (Extenders)

Расширители — классы, реализующие OperationExtender, которые могут вмешиваться в жизненный цикл операции:

OperationExtender (интерфейс)
└── BaseOperationExtenderSupport (абстрактный)
    └── OperationExtenderSupport (абстрактный, модуль server)
        ├── CheckRecordsExtender
        └── CheckInsertExtender
Метод Описание
postGetParameters(Operation op, Object parameters, Map presetValues) Вызывается после getParameters. Может модифицировать форму или заблокировать операцию
skipInvoke(Operation op, Object parameters) Если вернуть true — invoke не вызывается, операция завершается с сообщением «Invocation of operation is cancelled by extender»
preInvoke(Operation op, Object parameters) Вызывается перед invoke
postInvoke(Operation op, Object parameters) Вызывается после invoke

CheckRecordsExtender — проверяет, что выбранные записи присутствуют в view AllowedRecordsFor<OperationName> или AllowedRecords. Если нет — блокирует invoke.

CheckInsertExtender — проверяет, что параметры вставки допустимы по view AllowedRecordsForInsert. Если нет — устанавливает ошибку в postGetParameters и блокирует invoke.

Жизненный цикл операции

Полный путь запроса _on_=<operation> от REST до invoke:

1. FormController.generateJson / execute
   (server/controllers/FormController.java)
   ├── Читает entityName, queryName, operationName (из _on_), contextParams, values
   └── Вызывает formGenerator.generate / formGenerator.execute

2. FormGeneratorImpl.getOperation
   (server/services/impl/FormGeneratorImpl.java)
   ├── userAwareMeta.getOperation(entityName, queryName, operationName)
   │   └── Проверяет роли: meta.hasAccess(operation.getRoles(), userInfoProvider.getCurrentRoles())
   │       Если нет доступа → Be5Exception.accessDeniedToOperation
   └── operationExecutor.create(operationInfo, queryName, operationParams)

3. OperationExecutorImpl.create
   (operation/services/impl/OperationExecutorImpl.java)
   ├── getOperationContext: строит OperationContext из _selectedRows_ + params
   ├── getOperationInstance:
   │   ├── GroovyOperation → groovyOperationLoader.get(...).newInstance()
   │   ├── JavaOperation → Class.forName(operationInfo.getCode()).newInstance()
   │   └── else → throw Be5Exception.internal("Not support operation type")
   ├── injector.injectMembers(operation)  # Guice
   └── operation.initialize(info, context, OperationResult.create())

4. FormGeneratorImpl.generate / execute
   ├── operationService.generate / operationService.execute
   ├── operationLogging.saveOperationLog  # если Features.LOGGING и статус FINISHED/REDIRECTED
   └── getResult: оборачивает в FormPresentation (форма) или OperationResultPresentation (результат)

5. OperationServiceImpl.generate / execute
   (operation/services/impl/OperationServiceImpl.java)
   ├── generate → operationExecutor.generate(operation, values)
   │   └── Если parameters == null → сразу execute
   └── execute → operationExecutor.execute(operation, values)
       ├── Если статус ещё EXECUTE (операция не задали результат) → operation.setResultGoBack()
       ├── Если ERROR → validator.throwExceptionIsError, иначе регенерирует форму с ошибками
       └── Иначе возвращает OperationResult

6. OperationExecutorImpl.generate / execute
   ├── generate:
   │   ├── Устанавливает результат в generate()
   │   ├── Загружает расширители
   │   ├── Вызывает operation.getParameters(presetValues)
   │   └── Вызывает postGetParameters у каждого расширителя
   └── execute:
       ├── Устанавливает результат в execute()
       ├── Если операция implements TransactionalOperation → оборачивает в транзакцию
       ├── callOperation:
       │   ├── generateWithExtenders (повторно вызывает getParameters)
       │   ├── validator.checkAndThrowExceptionIsError(parameters)
       │   └── callInvoke:
       │       ├── doInvokeWithExtenders:
       │       │   ├── preInvoke у расширителей
       │       │   ├── skipInvoke (если true → finished, не вызываем invoke)
       │       │   ├── operation.invoke(parameters)  # <-- ВАШ КОД
       │       │   └── postInvoke у расширителей
       │       └── validator.throwExceptionIsError(parameters)
       └── Если статус ERROR и TransactionalOperation → откат транзакции

Логирование: OperationLoggingImpl (модуль modules/core) пишет в таблицы be5operationLogs и be5operationLogParams, только если в проекте включена фича Features.LOGGING и операция завершилась успешно (FINISHED или REDIRECTED). Уровень логирования операции задаётся в YAML (logging: everything|params|exec|none).

Пользовательские операции

Groovy-операция (основной паттерн)

Groovy-операции лежат в src/main/groovy/operations/** и определяются в YAML сущности:

operations:
- MyOperation:
    type: Groovy
    roles: Administrator
    layout: '{"type":"modalForm"}'
    file: operations.mypackage.MyOperation.groovy

Класс должен расширять GOperationSupport (или встроенную операцию) и реализовывать Operation:

package operations.mypackage

import com.developmentontheedge.be5.operation.Operation
import com.developmentontheedge.be5.operation.OperationResult
import com.developmentontheedge.be5.server.operations.support.GOperationSupport
import com.developmentontheedge.be5.databasemodel.util.DpsUtils

@TypeChecked
class MyOperation extends GOperationSupport implements Operation
{
    @Override
    Object getParameters(Map<String, Object> presetValues) throws Exception
    {
        // 1. Строим форму параметров (DPS)
        params.add {
            name = "title"
            DISPLAY_NAME = "Название"
            CAN_BE_NULL = false
        }

        params.add {
            name = "category"
            DISPLAY_NAME = "Категория"
            TAG_LIST_ATTR = queries.getTagsFromSelectionView("categories")
            CAN_BE_NULL = true
        }

        // 2. Заполняем предзаполненными значениями (из запроса)
        return DpsUtils.setValues(params, presetValues)
    }

    @Override
    void invoke(Object parameters) throws Exception
    {
        // 1. Читаем значения из DPS
        def title = parameters.getValue("title")
        def category = parameters.getValue("category")

        // 2. Выполняем логику операции
        def entity = database.getEntity(info.getEntityName())
        def record = [title: title, category: category]
        def newId = entity.add(record)

        // 3. Отмечаем завершение
        setResultFinished("Запись создана: " + newId)
    }
}

Что доступно внутри:

  • params — GDynamicPropertySetSupport (DPS для Groovy-DSL, см. attributes.md);

  • queries — QueriesService (getTagsFromSelectionView, getTagsFromCustomSelectionView, getTagsFromEnum);

  • database — DatabaseModel (getEntity(name).add/get/set/remove);

  • db — DbService (insert, execute, query для SQL);

  • meta / userAwareMeta — метаданные;

  • dpsHelper — утилиты построения DPS из модели;

  • validator — валидатор (setError, checkAndThrowExceptionIsError);

  • session / userInfo — сессия и пользователь;

  • getFileItem(name) — загрузка файлов;

  • setResultFinished(...) / setResult(OperationResult.error(...)) — завершение.

Наследование встроенных операций

Можно расширить встроенную операцию и переопределить нужные методы:

package operations.mypackage

import com.developmentontheedge.be5.server.operations.FilterOperation
import com.developmentontheedge.be5.beans.DynamicPropertySet
import com.developmentontheedge.be5.databasemodel.util.DpsUtils

class CustomFilter extends FilterOperation
{
    @Override
    DynamicPropertySet getFilterParameters(Map<String, Object> presetValues)
    {
        // Переопределяем построение формы фильтра
        params.add {
            name = "customField"
            DISPLAY_NAME = "Моё поле"
            TAG_LIST_ATTR = [["a", "А"], ["b", "Б"]] as String[][]
        }
        return DpsUtils.setValues(params, presetValues)
    }
}

Java-операция

Java-операции определяются в YAML с type: Java:

operations:
- MyJavaOperation:
    type: Java
    roles: Administrator
    code: com.mycompany.operations.MyJavaOperation

Класс должен расширять OperationSupport (или встроенную операцию) и реализовывать Operation:

package com.mycompany.operations;

import com.developmentontheedge.be5.beans.DynamicProperty;
import com.developmentontheedge.be5.beans.DynamicPropertySet;
import com.developmentontheedge.be5.beans.DynamicPropertySetSupport;
import com.developmentontheedge.be5.databasemodel.util.DpsUtils;
import com.developmentontheedge.be5.operation.Operation;
import com.developmentontheedge.be5.server.operations.support.OperationSupport;

import java.util.Map;

public class MyJavaOperation extends OperationSupport implements Operation
{
    @Override
    public Object getParameters(Map<String, Object> presetValues) throws Exception
    {
        DynamicPropertySet dps = new DynamicPropertySetSupport();
        dps.add(new DynamicProperty("name", "Name", String.class));
        dps.add(new DynamicProperty("value", "Value", Integer.class));
        return DpsUtils.setValues(dps, presetValues);
    }

    @Override
    public void invoke(Object parameters) throws Exception
    {
        DynamicPropertySet dps = (DynamicPropertySet) parameters;
        String name = (String) dps.getValue("name");
        Integer value = (Integer) dps.getValue("value");

        // Выполняем SQL
        db.insert("INSERT INTO " + info.getEntityName() + " (name, value) VALUES (?, ?)",
                  name, value);

        // Завершаем
        setResultFinished("Запись добавлена");
    }
}

SQL-запросы внутри операций

В open-source be5 нет отдельного исполнителя SQL-операций. SQL выполняется вручную внутри Java/Groovy-операции через инжектированный db (DbService):

void invoke(Object parameters) throws Exception
{
    def name = parameters.getValue("name")
    def value = parameters.getValue("value")

    // INSERT
    db.insert("INSERT INTO " + info.getEntityName() + " (name, value) VALUES (?, ?)",
              name, value)

    // UPDATE
    db.execute("UPDATE " + info.getEntityName() + " SET value = ? WHERE name = ?",
              newValue, name)

    // SELECT
    def result = db.query("SELECT * FROM " + info.getEntityName() + " WHERE value > ?", threshold)
    // result — список QRec (DPS)

    setResultFinished("Готово")
}

Методы DbService:

Метод Описание
void insert(String sql, Object... params) Выполняет INSERT, возвращает lastInsertID
int execute(String sql, Object... params) Выполняет DML (UPDATE/DELETE), возвращает число затронутых строк
List<QRec> query(String sql, Object... params) Выполняет SELECT, возвращает список QRec (DPS-представление строки)

Ошибки и валидация

Ошибка на уровне свойства (форма перерисовывается с ошибкой в конкретном поле):

void invoke(Object parameters) throws Exception
{
    def name = parameters.getValue("name")
    if (name == null || name.isEmpty())
    {
        validator.setError("name", "Поле обязательно")
        return
    }
    // ...
}

Ошибка всей операции (алерт с сообщением, форма не перерисовывается):

void invoke(Object parameters) throws Exception
{
    try
    {
        // ... логика ...
    }
    catch (Exception e)
    {
        setResult(OperationResult.error("Не удалось выполнить операцию: " + e.getMessage()))
        return
    }
    setResultFinished("Успешно")
}

Непредвиденное исключение (захватывается исполнителем, статус ERROR):

void invoke(Object parameters) throws Exception
{
    // Если бросите исключение, OperationExecutorImpl его зацепит
    // и установит setResult(OperationResult.error(...))
    throw new RuntimeException("Что-то пошло не так")
}

Загрузка файлов

Object getParameters(Map<String, Object> presetValues) throws Exception
{
    params.add {
        name = "file"
        DISPLAY_NAME = "Файл"
        TYPE = File
        CAN_BE_NULL = true
    }
    return DpsUtils.setValues(params, presetValues)
}

void invoke(Object parameters) throws Exception
{
    def fileItem = getFileItem("file")
    def fileName = fileItem.getName()
    def fileData = fileItem.get()
    // ... сохранить ...
    setResultFinished("Файл загружен: " + fileName)
}

Ссылки

  • operations.md — YAML-декларация операций (атрибуты type, code, records, roles, layout)

  • attributes.md — Dynamic Properties (DPS), формы параметров, атрибуты, валидация

  • l10n.md — локализация имён операций