Операции: серверная часть
Операция на стороне сервера — это Java/Groovy-класс, реализующий интерфейс Operation,
который вызывается при отправке формы операции (REST-запрос с параметром _on_=<имя>).
Сервер:
создаёт экземпляр класса операции (по имени из метаданных),
вызывает
getParameters(...)— получает форму параметров (DPS, см.attributes.md),отправляет форму клиенту,
при отправке формы клиентом вызывает
invoke(parameters)— выполняет действие,возвращает результат (
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
getParameters(Map presetValues)вызывается сервером при запросе формы.Возвращает
DynamicPropertySet(DPS) — описание полей формы (см.attributes.md).presetValues— карта, которую сервер заполняет параметрами из запроса (фильтры, язык, выбранные записи и т.д.).Если вернул
null— форма не показывается,invokeвызывается сразу сnull.Если бросил исключение — операция переходит в статус
ERROR.
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— локализация имён операций