Event protocol

This protocol allows a connection destination to be implemented by local handler for the transmit event.

Summary

Name: event
Resource name: Any value.
Description: Fires a transmit event to allow destination to be implemented by a local handler.
Operations: Any value.

Note that the event protocol is designed to simplify the custom implementation of an individual destination. If you wish to implement a protocol for more general use you should create a new protocol Transport implementation. For more information, see Creating a custom protocol transport.

Request and response format

There are no request or response formats defined for the event protocol. The transmit handler may process any header or body type required by the application.

Configuration

There are no configuration parameters defined for the event protocol.

Implementing a transmit event handler

The global context contains the following information about the outbound request when the transmit event is fired:

/connection/request/target: Destination resource name.
/connection/request/operation: Operation name.
/connection/request/headers/ header_name: List of values for request header.
/connection/request/protocol/_name: Name of the protocol requested by the application.
/connection/request/protocol/ parameter_name: Protocol configuration value.
/connection/request/body: Request body.

The object type of the request body will depend on the body supplied by the caller of the Connection API. If the caller used Connection.getRequestBodyOutputStream() then /connection/request/body will reference an InputStream from which the request body can be read.

The transmit event handler may inspect the request details as required and should pass back the appropriate response using the following keys:

/connection/response/headers/ header_name: List of values for response header.
/connection/response/status: Response status String.
/connection/response/body: Response body.

The response body may be any object type, including InputStream and Reader. It is good practice to include a Content-Type response header with a charset value where known, to allow the Connection API to convert between character and binary data as the application requests.

If multiple event handlers are found match the transmit event, they will be executed in sequence. Handler processing terminates when a handler sets any part of the /connection/response context. If none of the configured event handler set /connection/response then a null body value will be returned to the caller of Connection API.

If no event handlers have been configured matching the transmit event, a ConnectionException will be thrown to the caller of the Connection API.

Example event handler implementation

The following is an example of a simple transmit event handler written in Groovy, which builds a response body based on some of the properties of the request and includes a response header called myHeader.

def onTransmit() {
    target = connection.request.target[];
    operation = connection.request.operation[];
    connection.response.headers.myheader = ["1", "2", "3"];
    connection.response.body = target + ": operation=" +
        operation + " body=" + connection.request.body[];
}

Assuming the handler is saved as transmitHandler.groovy, the following configuration extract can be used to associate the handler with transmit events with a target of resource1:

/config/handlers += [{
    "events" : "transmit",
    "handler" : "transmitHandler.groovy",
    "conditions" : "/connection/request/target =~ resource1"
}]

A second piece of configuration is used to specify that the destination resource1 is to be directed to the event protocol:

/config/connection/destinations += {
    "resource1" : {
        "connection" : { "protocol" : "event"}
    }
}

With transmitHandler.groovy handler registered as the implementation of the destination, resource1, the following example Groovy script could be used to invoke the handler using the Connection API:

    Connection conn = new Connection("resource1", Connection.Operation.POST);
    conn.setRequestBody("Message text")
    Connection.Response resp = conn.getResponse();

    println(resp.getResponseBodyAsString());
    println(resp.getResponseHeader("myheader"));

The result of running this script would be something like this:

resource1: operation=POST body=Message text
[1, 2, 3]