User Guide

This section of the wiki contains information relevant to developers wishing to make use of the framework in their applications.

Adapters

REST adapter generator

The REST adapter generator is for use with the RAML Maven plugin. It generates REST adapters for incoming REST requests, driven from RAML definitions of your service endpoints.

Action mapping

The adapter generator has a mechanism to map incoming requests to actions within the framework. A combination of the resource endpoint and a content type is used to determine the action. For POST requests, the content type of the request body can be used. For GET requests, the accepted content type of the response body can be used.

The RAML Maven plugin currently only understands RAML 0.8 which does not support RAML annotations, etc. So to allow mappings to be defined within the RAML, the generator looks for custom blocks of YAML embedded within the description field of each resource.

The generator looks for a block within the description that is delimited with ... at the start and end. Each block can contain multiple (mapping) definitions, with the following fields:

• requestType - the content type of a POST body
• responseType - the content type of an accepted GET response body
• name - the name of the action that will handle the request

For example:

/users/{userId}:
  description: |
    Commands relating to updating a user
  post:
    description: |
        ...
        (mapping):
            requestType: application/vnd.user+json
            name: create-user
        (mapping):
            requestType: application/vnd.address+json
            name: update-address
        ...
    body:
        application/vnd.user+json:
            schema: !include json/schema/user.json
        application/vnd.address+json:
            schema: !include json/schema/address.json
  get:
    description: |
        ...
        (mapping):
            responseType: application/vnd.user+json
            name: get-user
        (mapping):
            responseType: application/vnd.user-summary+json
            name: get-user-summary
        ...
    responses:
        200:
            body:
                application/vnd.user+json:
                application/vnd.user-summary+json:

Logging

Logging is implemented within the framework using the SLF4J API. The framework components provide a couple of types of logging that can be turned on for diagnostic purposes:

• Message trace - this records the passage of a message through the framework components from entry point to exit point, using the message ID from the metadata of the message wherever possible to allow separate log lines to be related. Output is at TRACE level.
• JSON schema validation errors - these are logged at DEBUG level when an incoming message fails to validate against the relevant JSON schema.

Framework logging can be controlled by changing the logging level of the uk.gov.justice.services category.