Configuring protocols

Requests made using the Connection API have a collection of protocol configuration properties associated with them which will eventually be used to send the request to the resource.

Each protocol implementation defines the protocol configuration it supports or requires. For more information about the protocols implementations and their configuration, see Protocol reference.

Protocol configuration and selection processing

Protocol configuration can be associated with a request in a number of ways:

1. An application can use Connection.setProtocolConfiguration() to specify protocol configuration before sending the request.
2. Connection handlers configured for the destination can set or update the protocol configuration.
3. The final destination configuration may contain a connection configuration which sets or updates the protocol configuration.
4. Once the protocol name has been finalized, any default configuration for the named protocol will be applied to the request.

When the connection infrastructure has executed any connection handlers and is ready to send the request, the following rules determine the name of the protocol that will be used.

• If the request explicitly specifies a protocol configuration (/connection/request/protocol/_name) then the protocol name is selected.
• Otherwise, if the target resource (/connection/request/target) is a valid URL then the protocol name is assumed to be the URL scheme name.
  • Note that mailto: URLs are mapped to the smtp protocol.
• Otherwise, the protocol name is set to unresolved.

Once the protocol name has been finalized and any default configuration applied to the request, the connection infrastructure looks for a appropriate protocol implementation (or Transport) with which to send the request.

Connection configuration for a destination

A destination configuration can include a connection configuration to specify the protocol and configuration that should be used. A connection configuration overrides any similar configuration that may have been set by the application or a connection handler.

The following is a simple example specifies the HTTPS configuration which should be used when sending requests to URLs matching the wild card name value. For more information about destination configuration and an overview of destination processing, see Configuring destinations.

/config/connection/destinations += [{
        "name" : "https://www.projectzero.org/*",
        "connection" : {
                "protocol" : "https",
                "config" : { "httpsConfig" : "myHttpsConfig" }
        }
}]

A connection configuration can contain the following properties:

Specifying one of these connection properties sets the associated request context key, overriding any value that may have been set by the application or a connection handler. In addition, if the value specified by protocol does not match /connection/request/protocol/_name then all values previously set under /connection/request/protocol/* will be deleted; that is changing the name of the protocol destroys any previous protocol configuration.

Note that using the target property replaces the target resource name including any URL parameters it may have included.

For more information about the configuration properties supported by each protocol implementation, see Protocol reference.

Specifying default protocol configuration

In addition to specifying protocol configuration for individual destinations, it is possible to specify default protocol configuration properties. These will be applied to all requests using the protocol but do not yet have a value for the property.

Default protocol configuration properties are specified under the /config/connection/defaults/xxx key, where xxx is the protocol name.

For example, the following extract specifies the default hostname property for the smtp protocol. If a request using the smtp protocol does not have a /connection/request/protocol/hostname value when the protocol implementation is about to be invoked, then the connection infrastructure will give it the value specified by /config/connection/defaults/smtp/hostname.

/config/connection/defaults/smtp/hostname = "smtp.yourdomain.com"