Встраивание API

REST API поставляется отдельным артефактом, поэтому его можно встроить в любое JAX-RS-приложение независимо от движка.

Предварительные требования

Классы REST API протестированы с реализациями JAX-RS RESTEasy и Jersey. Кроме того, в classpath должны быть классы движка и артефакт Jackson com.fasterxml.jackson.jakarta.rs:jackson-jakarta-rs-json-provider (с транзитивными зависимостями Jackson).

Необходимые шаги

Шаг 1: Добавьте REST API в проект как Maven-зависимость.

Импортируйте OpenBPM BOM, чтобы версии всех артефактов OpenBPM были согласованы.

<dependency>
  <groupId>io.openbpm.bpm</groupId>
  <artifactId>openbpm-engine-rest</artifactId>
  <classifier>classes</classifier>
</dependency>

Шаг 2: Добавьте нужные REST-ресурсы в JAX-RS-приложение. Пример:

@ApplicationPath("/")
public class MyApplication extends Application {
  @Override
  public Set<Class<?>> getClasses() {
    Set<Class<?>> classes = new HashSet<Class<?>>();
    // добавьте собственные классы
    ...
    // добавьте все REST-ресурсы OpenBPM Engine (или только те, которые нужны)
    classes.addAll(OperatonRestResources.getResourceClasses());

    // обязательно
    classes.addAll(OperatonRestResources.getConfigurationClasses());

    return classes;
  }
}

OperatonRestResources.getResourceClasses() возвращает два JAX-RS-ресурса, которые служат точками входа. Первый (io.openbpm.bpm.engine.rest.impl.NamedProcessEngineRestServiceImpl) предоставляет все описанные в этом справочнике REST-ресурсы по путям, начинающимся с /engine/{name}. Второй (io.openbpm.bpm.engine.rest.impl.DefaultProcessEngineRestServiceImpl) дает доступ к ресурсам движка по умолчанию по корневому пути /.

Чтобы предоставить только часть REST-ресурсов (например, только методы для определений процессов), реализуйте подкласс io.openbpm.bpm.engine.rest.impl.AbstractProcessEngineRestServiceImpl и зарегистрируйте его в JAX-RS-приложении. Набор доступных ресурсов такой подкласс задает методами с JAX-RS-аннотациями. Примеры смотрите в исходном коде NamedProcessEngineRestServiceImpl и DefaultProcessEngineRestServiceImpl. Примечание: путь к субресурсу всегда должен совпадать с путем, определенным в интерфейсе субресурса.

Класс конфигурации JacksonConfigurator нужен, чтобы поля с датами сериализовались правильно. Возможно, понадобится добавить и провайдеры Jackson: com.fasterxml.jackson.jakarta.rs.json.JacksonJsonProvider, io.openbpm.bpm.engine.rest.exception.JsonMappingExceptionHandler и io.openbpm.bpm.engine.rest.exception.JsonParseExceptionHandler. Нужно ли это, зависит от среды выполнения.

Чтобы ответы об ошибках имели формат, описанный в разделе Обзор, подключите RestExceptionHandler. ProcessEngineExceptionHandler преобразует любое исключение движка, которое классы REST API не обработали явно, в ошибку HTTP 500 с тем же форматом тела ответа. Чтобы в этот формат преобразовывались исключения любого вида, используйте io.openbpm.bpm.engine.rest.exception.ExceptionHandler вместо ProcessEngineExceptionHandler.

Остается связать REST API с процессным движком (или движками). Для этого создайте провайдер сервиса (Service Provider), реализующий интерфейс ProcessEngineProvider, и объявите его в файле META-INF/services/io.openbpm.bpm.engine.rest.spi.ProcessEngineProvider. Можно также объявить класс io.openbpm.bpm.engine.rest.impl.application.ContainerManagedProcessEngineProvider: он входит в REST API и использует методы класса io.openbpm.bpm.BpmPlatform.

Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.