Configuring connection handlers

A connection handler is a small piece of logic that you can configure for a destination. The connection infrastructure invokes a configured connection handler before sending a request, and again when receiving the response.

Overview

Connection handlers can examine the contents of the request and response, and carry out simple processing. The following list contains examples of scenarios where a connection handler might be useful:

Logging requests sent to a destination and the responses received.
Manipulating the request or response headers.
Performing simple transformations of the request or response body.
Dynamically adding protocol configuration, such as when it cannot be statically determined by a connection configuration.

For more information about destination configuration and an overview of destination processing, see Configuring destinations. For a description of how to write a connection handler, see Creating a connection handler.

Configuring connection handlers for a destination

To use a connection handler, it must be included in the handlers list for a connection destination. Before sending the request to the target, the connection infrastructure invokes the request phases of the configured handlers in the order they appear in the list. After the response has been received, the response phases of the configured handlers are invoked in the reverse order.

Each element in the handlers list identifies a connection handler to be invoked and can optionally contain handler-specific configuration. There are two kinds of connection handler:

An event-based connection handler is identified by the value of the name attribute. This type of connection handler is implemented as a pair of event handlers and can be implemented by a Groovy or PHP script, or a Java™ class.
A class-based connection handler is identified by the value of the class attribute. The value of class must be the name of a Java class that implements the zero.core.connection.handlers.Handler interface.

Each handler in the handlers list must be identified using either a name or class attribute. If both the name and class attributes are specified, the name attribute is ignored.

The optional config attribute can be used to supply additional configuration to a connection handler. The value is a map of name-value pairs, which will be made available to the connection handler when it is invoked. The names and values that can be specified will depend on the connection handler implementation.

The following configuration example specifies that a single, event-based connection handler, myHandler1, is to be invoked for requests matching the destination name:

/config/connection/destinations += {
    "http://www.projectzero.org/*" : {
        "handlers" : [
            { "name" : "myHandler1" }
        ]
    }
}

In the second example, a second connection handler, myHandler2, is also specified for the destination. When invoked, myHandler2 will be given a configuration in which the value of param1 is value1.

/config/connection/destinations += {
    "http://www.projectzero.org/*" : {
        "handlers" : [
            { "name" : "myHandler1" },
            { "name" : "myHandler2",
              "config" : { "param1" : "value1" }
            }
        ]
    }
}

In this final example, a single class-based connection handler is configured:

/config/connection/destinations += {
    "http://www.projectzero.org/*" : {
        "handlers" : [{
            "class" : "zero.core.connection.handlers.logger.SimpleJavaLoggerHandler"
        }]
    }
}