ParameterService

ru.bgcrm.model.param.service.ParameterService — основной сервис чтения и изменения значений параметров. Он проверяет существование и тип параметра, применяет ограничения значения и при записи публикует события параметров.

Используйте его вместо ParamValueDAO и устаревшего ru.bgcrm.service.ParameterService.

Получение сервиса

val parameterService = ServerContext.get().getService<ParameterService>()
ParameterService parameterService = ServerContext.lookup(ParameterService.class);

В JEXL-контексте процесса сервис доступен как parameterService.

id во всех методах — идентификатор объекта-владельца значения, а param/paramId — идентификатор определения параметра. Владельцем может быть процесс, контрагент, пользователь или другой поддерживаемый объект; тип владельца задан в самом определении параметра.

События и проверки

Обычный ParameterService при записи выполняет следующую последовательность:

  1. Находит определение параметра в ParameterCache и проверяет его тип.

  2. Публикует ParamChangingEvent для скрипта параметра и, для параметра процесса, для скрипта типа процесса.

  3. Записывает новое значение через repository.

  4. Публикует ParamChangedEvent по тем же маршрутам.

getListExt динамического спискового параметра также публикует ParamListGetEvent.

EventlessParameterService имеет тот же интерфейс и те же проверки типов, но не публикует события изменения. Используйте его только там, где подавление событий является явной частью сценария; это не более быстрый вариант по умолчанию.

Текст и blob

Метод Поведение

getText(id, param): String?

Читает параметр типа text или blob

updateText(id, param, value)

Записывает значение; null очищает параметр

Boolean и число

Метод Поведение

getBoolean(id, param): Boolean

Читает флаговый параметр

updateBoolean(id, param, value: Boolean?)

Записывает true/false; null очищает значение

getNumber(id, paramId): BigDecimal?

Читает число без потери точности

updateNumber(id, paramId, value: BigDecimal?)

Записывает число или очищает значение

Для числа проверяются общая точность до 20 знаков, scale до 5 знаков после запятой и ограничения min/max из конфигурации параметра.

Tree и list

Метод Поведение

getTree(id, param): MutableSet<String>

Идентификаторы выбранных узлов tree

getTreeExt(id, param): MutableList<TreeTitle>

Идентификаторы и названия выбранных узлов

updateTree(id, param, values)

Полностью заменяет выбранные узлы

getList(id, param): MutableSet<Int>

Идентификаторы выбранных значений списка

getListExt(id, param): MutableSet<IdTitleComment>

Идентификатор, название и комментарий каждого значения

updateList(id, param, values)

Полностью заменяет значения без комментариев

updateListExt(id, param, values: Map<Int, String?>)

Полностью заменяет значения и комментарии

Пустой набор очищает параметр.

ListCount

Метод Поведение

getListCount(id, param): MutableSet<ParameterListCountValue>

Читает значения с количеством

updateListCount(id, param, values)

Полностью заменяет набор и проверяет числовые ограничения количества

Email и телефон

Метод Поведение

getEmail(id, param): MutableSet<ParameterEmailValue>

Читает все email-значения

updateEmail(id, param, values)

Полностью заменяет email-значения

getPhone(id, param): String?

Возвращает строковое значение телефона либо null

updatePhone(id, param, format, value)

Записывает один телефон; пустое значение очищает параметр

getPhoneExt(id, param): ParameterPhoneValue

Возвращает полную структуру телефонного параметра

updatePhoneExt(id, param, phoneValue)

Записывает полную структуру

Для нескольких телефонов и сохранения дополнительных полей используйте методы *PhoneExt.

Адрес

Метод Поведение

getAddress(id, param, loadDetails)

Читает адреса; loadDetails управляет загрузкой детальных объектов справочника

updateAddress(id, param, values)

Полностью заменяет адреса

Если нужны только идентификаторы и поля сохранённого значения, передавайте loadDetails = false.

Дата и дата-время

Метод Поведение

getDate(id, param): LocalDate?

Читает календарную дату

updateDate(id, param, value: LocalDate?)

Записывает или очищает дату

getDateTime(id, param): LocalDateTime?

Читает локальные дату и время

updateDateTime(id, param, value: LocalDateTime?)

Записывает или очищает дату-время

API использует java.time, а преобразование к формату хранения выполняет реализация сервиса.

Файлы

Метод Поведение

getFile(id, param): List<FileData>

Возвращает версии файлов параметра

addFile(id, param, value: FileData)

Привязывает уже сохранённый файл; нужны положительный id и непустое название

addFile(id, param, fileName, bytes)

Создаёт и добавляет файл из массива байтов

removeFile(id, param, value)

Удаляет указанную версию; нужны положительные position и version

Не загружайте большие файлы в память без необходимости: перегрузка с ByteArray получает весь файл целиком.

Пакетное обновление

updateValues(objectId, values: List<ParamValue<*>>) применяет типизированные значения последовательно. Поддерживаются ParamValueText, ParamValueBoolean, ParamValueDate, ParamValueDateTime, ParamValueList, ParamValueEmail, ParamValueAddress, ParamValuePhone, ParamValueTree, ParamValueListCount и ParamValueNumber.

Особенности текущей реализации:

  • objectId == 0 считается ошибкой;

  • пустой список ничего не меняет;

  • элементы с paramId ⇐ 0 пропускаются;

  • пустые значения list, email, address, tree и listCount пропускаются, а не очищают параметр;

  • неподдерживаемый класс ParamValue приводит к BGException.

Если требуется гарантированно очистить значение, вызовите типовой update* с null/пустой коллекцией либо cleanParam.

Копирование и очистка

Метод Поведение

copyParam(fromObjectId, toObjectId, paramId)

Копирует один и тот же параметр между объектами; событие копирования не публикуется

copyParams(fromObjectId, fromParamId, toObjectId, toParamId)

Копирует между разными параметрами и публикует ParamCopiedEvent

cleanParam(objectId, paramId)

Очищает значение через соответствующий update*; тип file текущей реализацией не поддерживается

isFilled(id, param): Boolean

Проверяет заполненность по правилам типа параметра

Строки объектного списка

Для параметра объектного списка доступны низкоуровневые операции:

Метод Поведение

getObjectListValues(id, param): List<Int>

Получить идентификаторы строк

addObjectListValue(id, param): Int

Добавить строку и вернуть её идентификатор

deleteObjectListValue(id, param, lineId)

Удалить строку

Эти методы не вызывают assertParameter и не публикуют события параметра. Используйте их только вместе с API конкретного объектного списка, которое заполняет содержимое строки.

Ошибки и транзакции

При отсутствии определения параметра большинство типовых операций выбрасывает IllegalArgumentException, при несовпадении типа — IllegalStateException. Ошибки бизнес-валидации возвращаются как BGException/BGMessageException.

Сервис использует соединение текущего ServerContext. В транзакционном контексте вызывающий код отвечает за commit, а при перехваченной ошибке — за осознанный rollback и завершение контекста. Не смешивайте сервис с ParamValueDAO, созданным на другом соединении. Подробнее: Соединения и транзакции.