Event protocol

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

Protocol summary
Request and response format
Configuration
Implementing a transmit event handler
- Example event handler implementation

Protocol 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. 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 can 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/cookies: List of Cookie values for request, if applicable.
/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 depends on the body supplied by the caller of the Connection API. If the caller used Connection.getRequestBodyOutputStream() then /connection/request/body references an InputStream from which the request body can be read.

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

/connection/response/headers/ header_name: List of values for response header.
/connection/response/cookies: List of Cookie values for response, if applicable.
/connection/response/status: Response status String.
/connection/response/body: Response body.

The response body can 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 are executed in sequence. Handler processing terminates when a handler sets any part of the /connection/response context. If none of the configured event handlers set /connection/response then a null body value is returned to the caller of Connection API.

If no event handlers have been configured matching the transmit event, a ConnectionException is 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.send();

    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]