Атрибуты
Синтаксис атрибутов
Самый простой способ получить значение атрибута - указать его имя:
name
Примечание
Двоеточие — часть имени и не является спец символом в данном контексте.
Если мы не указываем скаляр, то он по умолчанию принимается равным «?disp». То есть запись выше аналогична следующей:
name?disp
Для значений с типом «Строка (String)» разницы между скалярами «?disp» и «?str» нет т.к. вернется одно и то же значение.
Для обращения к вложенному атрибуту следует разделять имена точкой:
counterparty.fullOrgName?str
Если на каком-то из уровней в атрибуте ожидается список значений, то следует использовать квадратные скобки «[]» после имени атрибута:
counterparty[].fullOrgName?str
manager.subordinates[].userName?str
manager.department.managers[].subordinates[].userName?str
Если мы запросили атрибут без указания квадратных скобок, а источник данных вернул список, то мы получим только первый элемент из этого списка или null, если список пустой.
Для получения сразу нескольких атрибутов у вложенного значения можно использовать фигурные скобки:
manager.subordinates[]{userName:"userName?str",firstName:"firstName"}
В результате получим следующую структуру:
[
{
"userName": "ivan.ivanov",
"firstName": "Ivan"
},
{
"userName": "petr.petrov",
"firstName": "Petr"
}
]
В атрибутах есть поддержка пост-процессоров, которые позволяют выполнять операции над результатом перед тем как вернуть его клиенту.
Пост-процессоры описываются после атрибута через символ вертикальной черты «|».
Для процессора «or» есть короткая запись через «!»
documentAmount?num!0
В процессоре «or» можно использовать другие атрибуты:
title?str!name?str
title?str|or("a:name?str")
В данном примере мы получим значение title или значение name, если title равен null или пустой строке.
Примечание
Данный атрибут приведен для примера и для получения «заголовок или имя» лучше использовать скаляр «?disp»
В полной форме нам нужно указать префикс «a:» чтобы обозначить, что нам нужно значение атрибута, а не константа «name?str» Если нам нужно строковое константное значение в короткой форме, то следует взять значение в кавычки:
title?str!"name"
Процессоры можно объединять:
title!name!"n-a"|presuf("prefix-","-suffix")
Взять заголовок;
Если заголовок пустой, то взять имя;
Если имя пустое, то взять константу «n-a»;
Добавить к результату пунктов 1-3 префикс «prefix-»;
Добавить к результату пункта 4 суффикс «-suffix».
Название |
Аргументы |
Описание |
Пример |
|---|---|---|---|
presuf |
prefix: Stringsuffix: String |
Добавить константу в начало и/или в конец строки. Значение суффикса можно не задавать. Если значение
префикса не нужно, а значение суффикса нужно, то первым аргументом можно передать пустую строку
|
name|presuf("prefix-","-suffix")при
name = "Имя" → "prefix-Имя-suffix" |
or |
orValue0: AnyorValue1: AnyorValueN: Any |
Вернуть запасное значение, если атрибут равен null или пустой строке. Если аргумент является строкой
и начинается на «a:», то оставшаяся часть атрибута воспринимается как другой атрибут, который
нужно вычислить и вернуть в результате.
Для последовательного выбора запасных значений используйте отдельные процессоры:
title!name!"n-a".В ecos-records 3.60.0-SNAPSHOT при пустом исходном значении вызов одного
or с несколькими аргументамифактически возвращает последний вычисленный аргумент, а не первый непустой.
|
|
rxg |
pattern: StringgroupIdx: Int = 1 |
Применить регулярное выражение ко всей строке и вернуть указанную группу. Если вся строка не соответствует шаблону, вернуть null |
"some-text" | rxg("some-(.+)") -> text"some-text-and-more" | rxg("(some)-(text)-(and)-(more)", 2) -> text |
join |
|
Объединить список значений в строку используя указанный разделитель |
|
hex (3.26.0+) |
delimiter: String = "" |
Представить base64 строку как HEX строку (список шестнадцатеричных чисел,
где каждый байт представлен двумя символами)
|
|
fmt |
format: Stringlocale: String = "en"timezone: String (необязательный) |
Отформатировать число или дату по указанному формату. Шаблон для дат — SimpleDateFormat,
для чисел — DecimalFormat
Без явной timezone используется UTC; если шаблон содержит
Z, z или X, используется зона исходной даты |
_created|fmt("yyyy__MM__dd")documentAmount|fmt("00000.00") |
cast |
type: { "str", "num", "bool" } |
Преобразует значение в указанный формат |
|
yaml |
Любую структуру приводит к YAML строке |
|
Таблица содержит основные процессоры. В библиотеке также зарегистрированы plus, uppercase и lowercase; список может расширяться реализациями процессоров.
Поисковые запросы
Группировка
В query можно задать атрибуты для группировки через параметр groupBy. Если Records DAO поддерживает группировку (реализует интерфейс RecsGroupQueryDao), то RecordsService ничего не делает с запросом и передает его как есть в DAO. Если же Records DAO не поддерживает группировку, то RecordsService пробует выполнить группировку самостоятельно используя дополнительные запросы. Этот механизм называется «автогруппировка».
Автогруппировка зависит от поддержки преобразования языка запроса. Если язык нельзя преобразовать для обработчика группировки, в сообщения запроса добавляется ошибка.
Работа с MLText полями (3.26.0+)
Если известно. что в каком-то атрибуте лежит строка или MLText структура (объект, где в качестве ключей локаль, а в значении соответствующая строка), то можно применить преобразование «mltext».
Пример:
some.att._as.mltext // получение актуального значения по локали пользователя
some.att._as.mltext.ru // получение значения для конкретной локали
some.att._as.mltext.closest.ru // получение значения для конкретной локали с попыткой вычислить ближайшее не пустое значение
some.att._as.mltext?json // получение значения для всех локалей (если some.att является строкой, то она будет соответствовать локали "en")
Преобразование работает для String, DataValue, MLText, ObjectData, JsonNode (jackson)
Использование динамических атрибутов в предикатах (3.26.0+)
При использовании поиска на основе языка предикатов для всех источников записей есть возможность указывать вместо значений динамически вычисляемые атрибуты.
Пример запроса с текущим пользователем:
{
"t": "eq",
"att": "actor",
"val": "${$user.userName}"
}
Если ${} один и занимает всю строку, то "${...}" меняется полностью на вычисленное значение. Таким образом результат вычисления шаблона может быть любым JSON типом включая null.
Динамические вставки можно использовать на любом уровне вложенности для любых значений в объектах (можно задавать t, att, val).
Список доступных атрибутов можно посмотреть в разделе «Контекстные атрибуты».
Контекстные атрибуты
Часто возникают ситуации, когда нужно загрузить атрибуты, которые не относятся напрямую к сущности, а являются контекстными.
Пример таких атрибутов:
Текущий пользователь
Текущая дата
Для доступа к таким атрибутам при запросе данных к имени атрибута в начале добавляется знак «$».
Т.о. если нам нужно получить имя текущего пользователя, мы можем загрузить следующий атрибут:
$user.userName
Если нам нужно получить текущую дату и отформатировать её:
$now|fmt("yyyy")
Список контекстных атрибутов, которые доступны во всех источниках:
Атрибут |
Описание |
|---|---|
user |
Текущий пользователь |
now |
Текущая дата |
auth |
Аутентификация текущего пользователя. С помощью этого атрибута можно проверить, является ли пользователь частью группы или глобальной роли:
|
str |
Атрибут для указания константного строкового значения |
ref |
Атрибут для указания ссылки на другую сущность |
appName |
Имя текущего приложения |
appInstanceId |
Идентификатор инстанса текущего приложения |
Если в серверном коде нужно расширить доступный список контекстных атрибутов, то работу с RecordsService нужно выполнять следующим образом:
val contextAtts = mutableMapOf<String, Any?>()
contextAtts["customVariable"] = RecordRef.valueOf("emodel/person@someuser")
val result = RequestContext.doWithAtts(contextAtts) {
recordsService.getAtt("any-record", "\$customVariable?disp").asText()
}
В качестве значений для контекстных атрибутов могут быть EntityRef’ы (для доступа к другим сущностям) или значения любых других типов.