Configuring protocols

Requests that are made using the Connection API have a collection of protocol configuration properties associated with them. The protocol configuration properties are used to send the request to the resource.

Protocol configuration and selection processing

Protocol configuration can be associated with a request in the following ways:

An application can use Connection.setProtocolConfiguration() to specify protocol configuration before sending the request.
Connection handlers configured for the destination can set or update the protocol configuration.
The final destination configuration can contain a connection configuration that sets or updates the protocol configuration.
Any default configuration for the named protocol is applied to the request after the protocol name is finalized.

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

If the request explicitly specifies a protocol, in /connection/request/protocol/_name, then the protocol name is selected.
If the request does not explicitly specify a protocol but the target resource, /connection/request/target, is a valid URL for a known protocol, then the protocol name will be selected. However, mailto: URLs are mapped to the smtp protocol.
If no protocol is identified, an Exception is raised, and the request is not sent.

After the protocol name is finalized and any default configuration is applied to the request, the connection infrastructure searches for an appropriate protocol implementation, or Transport, with which to send the request.

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

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 might have been set by the application or a connection handler.

The following example specifies the HTTPS configuration to use when sending requests to URLs that match the wild card name.

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

For more information about destination configuration and an overview of destination processing, see Configuring destinations.

A connection configuration can contain one or more of the following properties:

target: Target resource name, which overrides /connection/request/target
operation: Operation name, which overrides /connection/request/operation
protocol: Name of protocol to be invoked, which overrides /connection/request/protocol/_name
config: Protocol configuration properties, which requires protocol to be specified and which overrides /connection/request/protocol/ values

Specifying one of these connection properties sets the associated request context key, overriding any value that the application might set, 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/* are 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 might include. 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, specify default protocol configuration properties. The properties are applied to all requests that are 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.

The following example specifies the default hostname property for the smtp protocol. If a request that is 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 gives it the value specified by /config/connection/defaults/smtp/hostname.

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