Kotlin/Java Backend
Для работы с RecordsAPI на kotlin/java бэкенде предусмотрена библиотека ecos-records - https://github.com/Citeck/ecos-records
Подключив библиотеку можно создать RecordsServiceFactory и получить оттуда все сервисы для работы с RecordsAPI.
Инициализация сервисов инкапсулирована в RecordsServiceFactory и не требует обязательного наличия DI механизмов.
Основной сервис для работы с RecordsAPI - ru.citeck.ecos.records3.RecordsService. Пример использования:
val serviceFactory = RecordsServiceFactory()
val recordsService = serviceFactory.recordsServiceV1
val value = HashMap<String, String>()
value["someKey"] = "someValue"
val attributeValue = recordsService.getAtt(value, "someKey").asText()
println(attributeValue) // someValue
RecordsServiceFactory serviceFactory = new RecordsServiceFactory();
RecordsService recordsService = serviceFactory.getRecordsServiceV1();
Map<String, String> value = new HashMap<>();
value.put("someKey", "someValue");
String attributeValue = recordsService.getAtt(value, "someKey").asText();
System.out.println(attributeValue); // someValue
Здесь мы создаем новую мапу с одним значением и получаем из неё атрибут с именем someKey через RecordsService.
Есть два основных сценария использования RecordsService:
Чтение собственных значений Map или бина, как в примере выше, выполняется локально без собственного DAO. Если значение содержит ссылки и запрошены атрибуты связанных записей, разрешение ссылок может обратиться к DAO.
Работа с ссылками (
EntityRef). В этом режиме сервис взаимодействует с источниками данных, функционал которых реализован через следующие интерфейсы:
Интерфейс |
Описание |
|---|---|
|
Базовый интерфейс для всех остальных ниже по списку. Содержит только один метод — |
|
Для поиска записей |
|
Для получения атрибутов по заранее известным идентификаторам записей |
|
Для создания или редактирования записей |
|
Для удаления записей |
Примечание
В скобках указаны варианты интерфейсов, где в метод приходит только один идентификатор записи. По своей сути эти интерфейсы отличаются от множественного варианта только отсутствием необходимости писать перебор идентификаторов вручную. Но если есть какие-либо оптимизации, которые можно реализовать при пакетной обработке записей, то следует реализовывать интерфейсы, которые принимают коллекции записей.
Records DAO - реализация абстрактного понятия «Источник данных». Один Records DAO может представлять разные источники данных.
При работе с Records DAO в зависимости от типа действия происходит следующее:
Мы передаем в RecordsQueryDao поисковый запрос и ждем на выходе следующие типы значений (поддерживаются как коллекции этих значений так и значения в одном экземпляре):
EntityRef- ссылки на сущности. Если мы получаем ссылки, то сервис обращается к соответствующемуRecordsAttsDaoдля получения атрибутов;String- текстовый результат означает что мы вернули идентификаторы записей, по которым нам нужно получить атрибуты через RecordsAttsDao. Если в строке не указан другой Records DAO, то используется тот же, у которого мы вызывали query;RecsQueryRes- список записей вместе с данными об их общем количестве;Any- любое другое значение, которое обрабатывается с использованием реализаций интерфейсаAttValueFactory.
Получение атрибутов по идентификаторам записей. Этот метод используется либо с результатом Query из предыдущего пункта либо посредством прямого вызова recordsService.getAtts(...).
Метод возвращает любое значение, которое обрабатывается с использованием реализаций интерфейса AttValueFactory.
Изменение или создание записей через RecordMutateDao.
В Records API создание записи происходит при мутации записи с пустым локальным идентификатором. Т.е. если мы хотим создать сущность в микросервисе emodel в источнике данных types-repo то делаем следующее:
// здесь следует обратить внимание на строку 'emodel/types-repo@'.
// Согласно структуре RecordRef'а (ссылка внизу) здесь
// (AppName - "emodel", SourceId - "types-repo", LocalId - "" (пустая строка))
let newRecord = Records.get('emodel/types-repo@');
newRecord.att("id", "id-value");
newRecord.att("name", "Custom name");
// В resultRecord будет объект записи со ссылкой, которую вернул источник.
// Правила назначения ID, включая возможность задать поле id вручную,
// определяются целевым DAO. UUID не является общим требованием Records API.
let resultRecord = await newRecord.save();
Удаление записей через RecordsDeleteDao.
AttValue - интерфейс, который представляет собой значение, с которым умеет работать RecordsService при получении атрибутов. Ниже приведены сокращённые сигнатуры без throws Exception:
Promise<?> init() // инициализация значения перед тем как начать вычисление атрибутов
Object getId() // идентификатор значения. Может быть как строкой, так и EntityRef
Object getDisplayName() // значение для скаляра "?disp"
String asText() // значение для скаляра "?str"
Object getAs(String type) // значение для спец. атрибута "_as"
Double asDouble() // значение для скаляра "?num"
Boolean asBoolean() // значение для скаляра "?bool"
Object asJson() // значение для скаляра "?json"
Object asRaw() // значение для скаляра "?raw"
Object asBin() // значение для скаляра "?bin"
boolean has(String name) // значение для спец. атрибута "_has"
Object getAtt(String name) // получить значение атрибута по его имени
AttEdge getEdge(String name) // получить мета-информацию об атрибуте по его имени
Object getType() // получить ECOS тип значения
AttValueFactory - интерфейс для преобразования произвольных типов данных в имплементацию AttValue
// Проинициализировать фабрику. В основном используется для получения конвертеров для других типов.
// Например: attValuesConverter.getFactory(DataValueAttFactory.class)
void init(AttValuesConverter attValuesConverter)
// Получить реализацию AttValue для значения
AttValue getValue(T value)
// Получить список доступных типов значений, которые может обрабатывать данная фабрика
List<Class<?>> getValueTypes()
// Получить приоритет фабрики. Чем выше приоритет, тем важнее фабрика в случае если для одного и того же типа нашлось две фабрики.
int getPriority()
Для регистрации произвольных AttValueFactory нужно в библиотеке или микросервисе создать следующий файл:
resources/META-INF/services/ru.citeck.ecos.records3.record.atts.value.factory.AttValueFactory
Внутри этого файла должно быть полное имя класса (вместе с пакетом) с вашей реализацией интерфейса AttValueFactory
Если для значения не нашлось подходящего AttValueFactory, то используется стандартная фабрика BeanValueFactory.
Эта фабрика работает со значением как с бином, у которого ищутся геттеры для атрибутов.
Например, если у нас есть следующий бин:
static class TestDto {
private String field;
public void setField(String value) {
this.field = value;
}
public String getField() {
return field;
}
}
То с точки зрения BeanValueFactory у этого бина есть значение с одним атрибутом «field». Пример работы:
RecordsServiceFactory serviceFactory = new RecordsServiceFactory();
RecordsService recordsService = serviceFactory.getRecordsServiceV1();
TestDto value = new TestDto();
value.setField("field-value");
String attributeValue = recordsService.getAtt(value, "field").asText();
System.out.println(attributeValue); // field-value
Если же мы хотим изменить имя атрибута не меняя названия методов, то можно воспользоваться аннотацией AttName:
static class TestDto {
private String field;
public void setField(String value) {
this.field = value;
}
@AttName("otherName")
public String getField() {
return field;
}
}
...
TestDto value = new TestDto();
value.setField("field-value-2");
String attributeValue = recordsService.getAtt(value, "otherName").asText();
System.out.println(attributeValue); // field-value-2
Аннотация @AttName помогает задать произвольное имя атрибута. Её можно использовать:
На геттере, чтобы дать произвольное название атрибуту;
На сеттере для конвертации DTO -> Схема атрибутов для запроса; (см. методы
recordsService.getAtts(Any record, Class<?> atts))Аннотация на поле работает как для сеттера так и для геттера если они есть;
Аннотация @AttName может в качестве аргумента принимать значение "...".
Такая запись означает, что все атрибуты из поля с этой аннотацией будут доступны так же и в нашем значении. Пример:
static class ParentDto {
@AttName("...")
private ChildDto child = new ChildDto(); // опустим сеттер, чтобы не усложнять пример
public ChildDto getChild() {
return child;
}
}
static class ChildDto {
public String getValue() {
return "abc"; // геттер не обязательно должен отдавать значение поля. Его поведение может быть произвольным
}
}
...
ParentDto value = new ParentDto();
// Если бы аннотация AttName отсутствовала, то до значения 'abc' мы бы могли добраться так:
// recordsService.getAtt(value, "child.value").asText();
// Но с аннотацией @AttName("...") можно обращаться к вложенному атрибуту так:
String attributeValue = recordsService.getAtt(value, "value").asText();
System.out.println(attributeValue); // abc
Так же особое значение имеют аннотации AttName где в качестве аргумента указан один из скаляров с вопросительным знаком.
Например: @AttName("?str"). Такие геттеры вызываются при загрузке скаляров.
BeanValueFactory также ищет в бине ряд специальных методов по их имени и аргументам. Возвращаемое значение должно соответствовать назначению метода:
Object getId() // значение для скаляра ?id
Object getAsStr() // значение для скаляра "?str"
Object getAsNum() // значение для скаляра "?num"
Object getAsBool() // значение для скаляра "?bool"
Object getAsJson() // значение для скаляра "?json"
Object getAsRaw() // значение для скаляра "?raw"
Object getAsBin() // значение для скаляра "?bin"
Object getEcosType() // значение для атрибута "_type"
Object getAs(String name) // значение для спец. атрибута "_as"
boolean has(String name) // значение для спец. атрибута "_has"
AttEdge getEdge(String name) // значение для спец. атрибута "_edge"
Object getAtt(String name) // Значение атрибута по имени если не получилось найти геттер для него
Для отображаемого имени нашего бина BeanValueFactory ищет следующие методы в порядке убывания приоритета (используется первый найденный):
Object getDisplayName()
Object getLabel()
Object getTitle()
Object getName()
Типы данных в Kotlin/Java
Метод ObjectData set/add
set — установить значение по ключу. Аналог метода put в Map.
add — добавить элемент к массиву. Сам по себе ObjectData является аналогом Map,
и для него add имеет мало смысла напрямую, но add первым аргументом может принимать
путь до вложенного массива.
Например:
ObjectData data = ObjectData.create();
data.set("arr", new LinkedList<Object>());
data.add("$.arr", "new-element");
Формат с $ — стандарт JsonPath. Методы ObjectData предоставляются библиотекой ecos-commons.