Overview

The HTTP Bridge Accessor is a post-processor designed to work closely with the HTTP transport. In the standard configuration the HTTP transport issues root requests using the http: scheme which are routed to the HTTP bridge. The HTTP bridge then issues a sub-request using the jetty: scheme which is subsequently mapped to the ffcpl: scheme. The rewrite rules to accomplish this are:

Applications may use the HTTP transport without the bridge if they need fine-grained control. However, the bridge gathers information from various parts of an HTTP request and converts this into a set of easy to use arguments in a single request. The services provided by the bridge makes the HTTP protocol easy to work with.

The HTTP bridge can be configured to provide the following services:

• Create parameter arguments for information in the HTTP request:
  • A param argument containing an XML name-value-pair (NVP) document with information from:
    • URL encoded form data
    • URL query data
  • A cookie argument from incoming Cookie information
  • A method argument capturing the HTTP method (GET, PUT, POST etc)
  • An argument for each listed HTTP header
  • Arguments for file uploads
• Handle multipart form data
• Test size of submitted resources and rejects if larger than a configurable maximum threshold
• Process application specified HTTP response codes
• Process application specified HTTP redirects
• Catch exceptions from internal requests and invokes exception handler URIs
• SOAP support
  • SOAP HTTP Binding - processes SOAP 1.1 and 1.2 requests and issues to SOAPServer
  • WSDL Generation - processes WSDL requests and maps to wsdlGenerator

Example

For an HTTP request consisting of the URL http://hostname:port/path/resource with POSTed URL encoded form data and a Cookie, the HTTP Bridge can convert the encoded form data into a name-value-pair XML document passed as the param argument, provide the cookie as a cookie argument and add the User-Agent and HTTP request method as arguments. All of this information is appended as arguments with the resulting request URI issued against the internal address space:

jetty://hostname:port/path/resource+method@xxx+cookie@yyy+User-Agent@zzz+param@qqq

Configuration

The HTTP Bridge configuration is provided as an XML document. The configuration comprises one or more zones each of which specifies processing rules for URLs which match that zone. The first zone matching a request will have its rules used for processing the request (this means a final catch-all zone can apply default processing).

A zone may be in normal or SOAP mode. In normal mode requests are processed as normal HTTP requests. In SOAP mode the request is processed according to SOAP binding standards (see below).

In the following list of configuration items for normal mode, match is required and all others are optional. In SOAP mode only match and SOAPMode are required.

match	A regular expression used to test a request's address URI for a match. If the URI matches the regular expression, the rules of the zone are used by the bridge to process the request.
SOAPMode	Specifies that all requests in this zone are processed using SOAP HTTP Bindings. See below for details. All other configuration elements are ignored in this mode.
passMethod	Create the method argument with the HTTP method as the value. (see passByURI for mode).
passHeaders	Create an argument for each HTTP header listed in a space separated list of headers. The listed header is used as the argument name. (see passByURI for mode).
passRemoteHost	Create the Remote-Host argument with the remote host IP address as the value. (see passByURI for mode).
passByURI	A mode flag indicating whether passMethod, passHeaders and passRemoteHost values are passed as RESTful active URI arguments of the form xxxxx@data:text/plain,XXXXXXX or by String value. If this tag is included then values are passed as data: scheme URI encoded information and are retrieved in code using "this:param:passMethod", etc. If this tag is omitted the values are passed as String values.
processQueries	Create the param argument which refers to an XML resource as a canonical NVP document containing name-value-pair information from the URL query parameters, HTML form fields and file uploads.
passCookies	Create the cookie argument which refers to an XML resource with Cookie information.
exceptionURI	A SOURCE request is issued for the specified URI if an exception is raised by the sub-request.
passRequestURL	Create the requestURL argument which contains the unmodified URL (including query parts).
maxEntitySize	The maximum size of any entity submitted with the request (in bytes).

Two default values may be set which will be used if not specified in a zone.

/HTTPBridgeConfig/defaultExceptionURI	The default URI to use if an exception is received from the issued sub-request
/HTTPBridgeConfig/defaultMaxEntitySize	The default maximum entity size submitted with any request

Distributed HTTP Bridge Configuration Resources

The configuration resource for the HTTP bridge may be distributed amongst several modules, each containing zone information pertaining to that module. The http-bridge-config service will merge these resources into a single resource used by the bridge.

The frontend fulcrum is configured to use this service which will examine all modules imported directly into the fulcrum looking for the exported resource ffcpl:/etc/HTTPBridgeConfig.xml. The service merges all discovered configuration resources into a single resource which can then be used by the HTTP bridge. (If configuration information is to be provided by modules more deeply embeded, the service configuration in the frontend fulcrum can be repeated in the first level modules to allow them to search their imported modules.)

Parameter Processing

Information provided in the HTTP using the POST method that is URL Encoded Form data (application/x-www-form-urlencoded) is converted into an XML document (NVP canonical form) containing name-value-pairs. This is best illustrated using an example. The following form created with the HTML show to the right

firstname surname

<form action="POST" target="dummy.idoc">   <input name="firstname">firstname</input>   <input name="surname">surname</input>   <input type="submit" value="submit" /> </form>

will produce the following XML parameter document:

This document is available as the argument param accessible as ("this:param:param").

Query Processing

If query processing is specified (<processQueries/>) then all URL query data (e.g. x=y in the URL http://host/path/resource?x=y ) is converted into name-value-pairs in an XML NVP canonical document and provided as the argument param. For example, the following URL (which is the result of an HTML form being submitted with the HTTP GET method):

dummy.idoc?firstname=John&lastname=Smith

will be processed into the same NVP param argument as show above in the URL Encoded Form data example.

Using Arguments from the Active URI

Many arguments processed by the HTTPBridge are provided as IAspectString objects. It may be useful to convert these into an XML canonical form using the StringToCanonicalString accessor.

XML Cookies

If HTTP cookie processing is specified the HTTPBridge will convert the cookie information into an XML document and provide that as the argument this:param:cookie. The HTTPCookie accessor can be used to obtain an XML representation of a cookie which has the following form.

Cookies may be set on the HTTP response by using the HTTPCookie accessor to set the cookie. HTTPCookie takes an XML representation of the cookie and sets the true cookie on the response.

Here's an example of an idoc that sets a cookie. The form of the XML cookie is exactly the same as that produced by HTTPCookie for a get cookie request.

The HTTPBridge detects cookies on the outbound response and sets the cookies on the HTTP response.

File Uploads

The HTTP Bridge will process one or more file uploads when the <processQueries/> configuration element is specified. For each HTML form field that specifies a file upload and which is named, an argument is provided using the HTML form field name as the argument name. Each file upload argument representation type is a raw IAspectReadableBinaryStream. In addition, each upload field is included in the XML NVP canonical document provided as the param argument ("this:param:param"). Here is an example:

Using this HTML to create an upload form:

where [mySubmitHandler] is the URL of the service which will handle the submission.

You will receive the following parameter document:

where [filename] is the final part (i.e. not the path) of the file uploaded. You will also receive an argument of the name upload which can be accessed using the URI this:param:upload from DPML or a scripting language.

HTTP Response Codes

The HTTPBridge will set application specified HTTP response codes set using the HTTPResponseCode Accessor.

HTTP Redirects

The HTTPBridge will detect and issue HTTP redirects declared by an application using the HTTPRedirect accessor.

Error Processing

If the sub-request issued by the HTTP bridge results in an exception being raised then the HTTPHandler will execute an exception process. The URI of the exception process is configured per zone and falls back to a default value if no URI is specified.

The requested exception URI will be called with a param argument containing the exception. If the exception handler itself causes an exception then it will be written as an XML exception document into the HTTP response stream.

SOAP Mode

When an zone is set to SOAP mode then all of its requests are processed using the SOAP HTTP binding rules. The request URL is the endpoint of the SOAP service, the action URI is extracted from the HTTP headers based on SOAP 1.1 or 1.2 rules depending on the message type or method of request.

The processed SOAP service request is mapped to the internal NetKernel address space with the following URI.

service:wsSOAPServer+message@[the SOAP message]+endpoint@[the endpoint URL]+action@[the action URI]

?WSDL

If the endpoint URL has a query ?WSDL the request will be treated as a request for a WSDL description of the service.

A WSDL request is mapped to the following URI.

service:wsdlGenerate+endpoint@[the endpoint URL]

?DOC

If the endpoint URL has a query ?DOC the request will be treated as a request for the HTML documentation for the service.

A DOC request is mapped to the following URI

service:wsDocumentation+endpoint@[the endpoint URL]

The wsDocumentation accessor will attempt to locate the documentation for the service based on an entry in the SOAPServiceMap