Hypertext Application Language (HAL)

Этот раздел перенесён из документации Camunda 7 и в дальнейшем будет доработан с учётом особенностей OpenBPM Engine

REST API предоставляет некоторые ресурсы в дополнительном media type. Media type HAL application/hal+json описывает формат, который содержит ссылки и информацию о других ресурсах. Это позволяет встраивать определение процесса или исполнителя задачи прямо в ответ, что, в свою очередь, сокращает число запросов, необходимых для получения всей информации об отдельной задаче или списке задач.

Чтобы работать с HAL, необходимо задать application/hal+json в качестве заголовка Accept. Ответ на HAL-запрос всегда имеет следующую структуру:

{
  "_links" : {},
  "_embedded" : {}
}

Свойство _links содержит реляционные ссылки (relational links), которые дают простой способ навигации между связанными ресурсами. Свойство _links содержит как минимум реляционную ссылку self. Свойство _embedded включает другие связанные ресурсы в представляющий ресурс. Каждый встроенный (embedded) ресурс будет структурирован как HAL-ресурс.

Пример: ресурс

Запрос

GET /task/a-task-id

Заголовок запроса:

Accept: application/hal+json

Ответ

{
  "_links" : {
    "self": {
      "href": "/task/a-task-id"
    },
    "assignee": {
      "href": "/user/demo"
    },
    ...
  },
  "_embedded" : {
    "group" : [{
      "_links" : {
        "self" : {
          "href" : "/group/management"
        }
      },
      "_embedded" : null,
      "id" : "management",
      ...
    }],
    "processDefinition" : [ {...}, {...} ],
    ...
  },
  "id" : "a-task-id",
  "name": "Assign Approver",
  "assignee": "demo",
  ...
}

Пример: коллекция

Запрос

GET /task

Заголовок запроса:

Accept: application/hal+json

Ответ

{
  "_links" : {
    "self": {
      "href": "/task"
    }
  },
  "_embedded" : {
    "assignee" : [{
      "_links" : {
        "self" : {
          "href" : "/user/demo"
        }
      },
      "_embedded" : null,
      id: "demo",
      ...
    }],
    "processDefinition" : [ {...} ],
    "task" : [{
      "_links" : {
        "self": {
          "href": "/task/a-task-id"
        },
        "assignee": {
          "href": "/user/demo"
        },
        ...
      },
      "_embedded" : {
        "variable" : [ {...}, {...} ]
      },
      "id" : "a-task-id",
      "name": "Assign Approver",
      "assignee": "demo",
      ...
    }, {
      ...
    }]
  },
  "count" : 2
}

Кэширование HAL-отношений

При генерации HAL-ответа связанные ресурсы разрешаются, чтобы встроить их. Некоторые из этих разрешённых ресурсов, такие как определения процессов или пользователи, изменяются редко. Кроме того, если информация о пользователе хранится во внешней системе (например, LDAP), каждый запрос будет обращаться к этой внешней системе, что является излишними накладными расходами. Чтобы сократить такие дорогостоящие запросы, REST API можно настроить на использование кэша для временного хранения таких отношений.

Это кэширование можно настроить в файле web.xml REST API (или OpenBPM Web Application в случае, когда REST API встроен в OpenBPM Web Application).

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <!-- ... -->

  <listener>
    <listener-class>io.openbpm.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  </listener>

  <context-param>
    <param-name>io.openbpm.bpm.engine.rest.hal.cache.config</param-name>
    <param-value>
      {
        "cacheImplementation": "io.openbpm.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
        "caches": {
          "io.openbpm.bpm.engine.rest.hal.user.HalUser": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "io.openbpm.bpm.engine.rest.hal.group.HalGroup": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "io.openbpm.bpm.engine.rest.hal.processDefinition.HalProcessDefinition": {
            "capacity": 100,
            "secondsToLive": 600
          }
        }
      }
    </param-value>
  </context-param>

  <!-- ... -->

</web-app>

Слушатель HalRelationCacheBootstrap

Для инициализации кэширования используется слушатель контекста HalRelationCacheBootstrap:

<listener>
  <listener-class>io.openbpm.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
</listener>

Он настраивается через параметр контекста io.openbpm.bpm.engine.rest.hal.cache.config. Конфигурация предоставляется в виде JSON и состоит из двух свойств:

Свойство Описание

cacheImplementation

Класс, который используется как кэш. Класс должен реализовывать интерфейс io.openbpm.bpm.engine.rest.cache.Cache. Простая реализация по умолчанию предоставляется классом io.openbpm.bpm.engine.rest.hal.cache.DefaultHalResourceCache.

caches

JSON-объект, указывающий, какие HAL-отношения должны кэшироваться. Каждый кэш HAL-отношения настраивается отдельно и идентифицируется кэшируемым классом HalResource. Возможные параметры конфигурации зависят от реализации кэша и должны быть доступны как сеттеры в классе реализации.

Параметры конфигурации DefaultHalResourceCache

Простая реализация кэша по умолчанию DefaultHalResourceCache предоставляет следующие параметры конфигурации:

Свойство Описание

capacity

Максимальное число записей кэша.

secondsToLive

Число секунд, в течение которых запись кэша действительна. Если запись кэша истекла, она удаляется и разрешается заново.

Список ресурсов, поддерживающих кэширование

  • Case Definition: io.openbpm.bpm.engine.rest.hal.caseDefinition.HalCaseDefinition

  • Group: io.openbpm.bpm.engine.rest.hal.group.HalGroup

  • Identity Links (of a Task): io.openbpm.bpm.engine.rest.hal.identitylink.HalIdentityLink

  • Process Definition: io.openbpm.bpm.engine.rest.hal.processDefinition.HalProcessDefinition

  • Task: io.openbpm.bpm.engine.rest.hal.task.HalTask

  • User: io.openbpm.bpm.engine.rest.hal.user.HalUser

Лицензия и атрибуция

Эта документация была создана на базе материала "Camunda 7 Docs" от Camunda, находится под лицензией Creative Commons Attribution-ShareAlike 3.0 Unported License .

Оригинал документации: https://docs.camunda.org