Быстрый старт с Interactor

1. Выберите корневую сущность

Для процесса интерфейс обычно наследуют от ProcessInteractor. Для других сущностей используются CustomerInteractor, UserInteractor, CommonContractInteractor и остальные корневые интерфейсы из таблицы сущностей.

Перед созданием нового процессного интерфейса найдите существующий по @ProcessInteractorReference или по наследованию от ProcessInteractor: один тип процесса должен иметь один основной интерфейс, а повторяемые части лучше вынести в аспекты.

@ProcessInteractorReference(typeIds = [11011])
interface CameraInstallationProcess : ProcessInteractor
@ProcessInteractorReference(typeIds = 11011)
public interface CameraInstallationProcess extends ProcessInteractor {
}

typeIds служит метаданными для поиска подходящего интерфейса по типу процесса. При обычном Interactor.create соответствие не валидируется.

2. Опишите операции

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

interface CameraInstallationProcess : ProcessInteractor {
    @BindAddressParam(90)
    fun getAddressOrNull(): ParameterAddressValue?

    @BindAddressParam(90)
    @NotNull(message = "В процессе #objectId не указан адрес")
    fun getAddress(): ParameterAddressValue

    @BindAddressParam(90)
    @DropCache
    fun setAddress(value: ParameterAddressValue?)
}

Общие соглашения обработчиков:

  • метод без аргументов и с не-void результатом считается чтением;

  • операция записи определяется аргументами, возвращаемым void/Unit и, для коллекционных обработчиков, префиксом set, add/plus, remove/delete или clear;

  • неподдерживаемая сигнатура приводит к IllegalStateException или IllegalArgumentException во время вызова.

3. Создайте proxy

val process = Interactor.create<CameraInstallationProcess>(processId)
CameraInstallationProcess process = Interactor.create(
    processId,
    CameraInstallationProcess.class
);

По умолчанию используется текущий ServerContext. В фоновом коде или тесте контекст можно передать явно:

val process = Interactor.create(processId, CameraInstallationProcess::class.java, context)

Один proxy привязан к одному id и одному ServerContext. Для другого объекта создайте новый экземпляр.

4. Добавьте валидацию

Ограничения на параметрах проверяются до вызова обработчика, а ограничения на методе — после получения результата.

@BindTextParam(120)
@NotEmpty(message = "В процессе #objectId не указан серийный номер")
fun getSerialNumber(): String?

@BindTextParam(120)
@DropCache
fun setSerialNumber(@NotEmpty(message = "Серийный номер пуст") value: String)

При нарушении выбрасывается BGMessageException. Полный список и особенности null приведены в разделе о валидации.

5. Настройте кеширование

@EnableCache на интерфейсе или методе включает кеш для не-void методов. Ключ состоит из метода и значений аргументов. Кеш принадлежит одному proxy и не синхронизируется с изменениями, сделанными через другой proxy или напрямую через сервисы.

@EnableCache
interface CameraInstallationProcess : ProcessInteractor {
    @BindTextParam(120)
    fun getSerialNumber(): String?

    @BindTextParam(120)
    @DropCache
    fun setSerialNumber(value: String?)
}

@DropCache очищает весь кеш proxy перед выполнением помеченного метода. Помечайте им каждую операцию, способную изменить данные, от которых зависят кешируемые методы.

Аннотация интерфейса проверяется на method.declaringClass. Поэтому @EnableCache на дочернем интерфейсе кеширует объявленные в нём методы, но не включает кеш для методов, унаследованных от неаннотированного родителя. Если кеш нужен для конкретного унаследованного контракта, включайте его в интерфейсе, где методы объявлены, либо переопределяйте нужные методы с аннотацией.