User Guide

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

• Messages

Code generators

There are several code generators available to generate adapters for incoming requests and clients for outgoing requests. The generated adapters and clients will be driven from RAML definitions of your service endpoints. The generators are for us with the RAML Maven plugin.

REST adapter generator

The REST adapter generator generates REST adapters for incoming REST requests.

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:

Messaging adapter generator

The messaging adapter generator generates messaging adapters for incoming JMS requests. Adapter generation is driven from a messaging RAML:

#%RAML 0.8
title: Messaging RAML to generate Cakeshop event listener
baseUri: message://event/listener/message/cakeshop
version: v1
/cakeshop.event:
  post:
    body:
        application/vnd.cakeshop.recipe-added+json:
            schema: !include json/schema/cakeshop.recipe-added.json
            example: !include json/add-recipe.json

• baseUri denotes type of component (e.g. event listener, event processor) and service name.
• resource uri contains name of the destination (topic/queue).
• Media type(s) of the body contains name of the event/command that later need to handled in a developer written handler, e.g:

@ServiceComponent(Component.EVENT_LISTENER)
public class RecipeAddedEventListener {

    @Handles("cakeshop.recipe-added")
    public void handle(final JsonEnvelope envelope) {
        //your code to handle recipe-added events
    }
}

It's also possible generate adapter that will handle all messages by specifing general json media type: application/json

#%RAML 0.8
title: Messaging RAML to generate Cakeshop event listener
baseUri: message://event/listener/message/cakeshop
version: v1
/cakeshop.event:
  post:
    body:
        application/json:

Your handler to handle all events would then look like this:

@ServiceComponent(Component.EVENT_LISTENER)
public class AllEventListener {

    @Handles("*")
    public void handle(final JsonEnvelope envelope) {
        //your code to handle all events
    }
}

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.