|Description:||Adapts low-level HTTPRequest / HTTPResponse objects in the HTTP transport root request to an ROC address space|
HTTPBridgeOverlay is an overlay. You must instantiate an instance of the overlay from its prototype, this will create a new instance within your application space.
The jetty.HTTPBridge prototype has the following initialisation parameters:
|config||Optional||Identifier or XML||null|
configuration of bridge
service to format unhandled exceptions
A nested space definition which the overlay will delegate all requests in to.
An identifier for created logical endpoint, if omitted a unique auto-generated value it will be used.
Here is an auto-generated example of how to instantiate an instance of HTTPBridgeOverlay:
To use HTTPBridgeOverlay overlay you must import the module urn:org:netkernel:tpt:http:
HTTPBridge is an overlay that transforms the root request issued by the HTTPTransport into a normalized, uniform ROC address space. The overlay handles requests issued to the httpRequest: and httpResponse: spaces and maps them to the low-level underlying HTTPRequest and HTTPResponse objects provided by the transport. See the overview for a diagram and general perspective.
The HTTPBridge should be configured to reside immediately after the HTTPTransport as shown in the following example:
and as depicted in the overview diagram.
The overlay takes the HTTPRequestResponseRepresentation object passed as the primary argument in the HTTP transport's root request and dynamically constructs an address space which it inserts into the request scope. The overlay then issues a sub-request into its wrapped space.
The inserted dynamic space handles requests for the
httpResponse: URI scheme,
mapping them to the information in the underlying HTTPRequest
and HTTPResponse objects.
Requests issued in the wrapped space for
retrieve information ...
Requests issued with the SINK verb in the wrapped space for
cause state to be accumulated and subsequently written to the
HTTPResponse output stream when the request completes processing.
If an exception is received for the sub-request - the bridge will make a request to the specified exceptionHandler interface passing the exception as the operand argument for processing. The response of the exception handler request is serialized to the HTTPResponse output stream and the appropriate HTTP response code is set.
If a rewrite is specified in the config parameter the sub-request identifier will be the transform of the incoming request by the rewrite regular expression.
To wrap an application space with the HTTPBridge overlay create the following overlay declaration
This String parameter defines the base identifier of an active URI for service which will format any unhandled exception caught by the HTTPBridge. This is useful for converting the raw XML of an exception to an error for human consumption, particularly if the client is a web browser. See Exception Handling doc for more details on how exceptions are handled in NetKernel. If you omit the exceptionHandler parameter then no formatting of the exception will take place and the client will receive the raw exception XML.
The handling service is called with a pass-by-value operand argument of a IBinaryStreamRepresentation serialised form of the exceptions XML. For example if you specify
then the following request will be issued:
The config parameter takes an XML document which specifies regex URL rewriting and an assumed default encoding of HTTP POST parameters.
Usually the rewrite use used to drop the http scheme and host name and move the requested URL into the res: scheme.
The optional defaultPostParamEncoding tag specifies the expected encoding of HTTP post parameters as this usually cannot be determined from the request. This value defaults to UTF-8.