Hypertext Application Language (HAL)

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

The REST API provides some resources in an additional media type. The HAL http://stateless.co/hal_specification.html media type application/hal+json describes a format which contains links and information about other resources. This allows us to embed the process definition or assignee of a task directly into the response, which in turn reduces the number of necessary requests to gather all information about a single task or a list of tasks.

To interact with HAL, you have to set application/hal+json as Accept header. The response of a HAL request always has the following structure:

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

The property _links contains relational links that give an easy way to navigate between associated resources. A _links property contains at least a self relational link. The property _embedded includes other linked resources in the representing resource. Each embedded resource will be structured as a HAL resource.

Example: Resource

Request

GET /task/a-task-id

Request Header:

Accept: application/hal+json

Response

{
  "_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",
  ...
}

Example: Collection

Request

GET /task

Request Header:

Accept: application/hal+json

Response

{
  "_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
}

Caching of HAL Relations

During the generation of a HAL response, linked resources are resolved to embed them. Some of these resolved resources, like process definitions or users, are rarely modified. Also, if user information is stored in an external system (such as LDAP), every request will access this external system which is an unnecessary overhead. To reduce such expensive requests, the REST API can be configured to use a cache to temporary store such relations.

This caching can be configured in the web.xml file of the REST API (or the Camunda Web Application in case the REST API is embedded into the Camunda 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>

The HalRelationCacheBootstrap Listener

To bootstrap the caching, the HalRelationCacheBootstrap context listener is used:

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

It is configured by the context parameter io.openbpm.bpm.engine.rest.hal.cache.config. The configuration is provided as JSON and consists of two properties:

Property Description cacheImplementation <td> The class which is used as cache. The class has to implement the io.openbpm.bpm.engine.rest.cache.Cache interface. A simple default implementation is provided by the io.openbpm.bpm.engine.rest.hal.cache.DefaultHalResourceCache class. </td>

DefaultHalResourceCache Configuration Options

The simple default cache implementation DefaultHalResourceCache provides following configuration options:

Property Description capacity <td> The number of maximal cache entries. </td>

List of Resources Which Support Caching

  • 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