WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:HTTPBridgeOverlay
Description:Adapts low-level HTTPRequest / HTTPResponse objects in the HTTP transport root request to an ROC address space
Id:jetty.HTTPBridge
Category:overlay

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.

Parameters

The jetty.HTTPBridge prototype has the following initialisation parameters:

NameRulesTypingDefaultDescription
configOptionalIdentifier or XMLnull
configuration of bridge
exceptionHandlerOptionalStringnull
service to format unhandled exceptions
spaceMandatorySpace(none)
A nested space definition which the overlay will delegate all requests in to.
idOptionalStringnull
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:

<overlay>
  <prototype>jetty.HTTPBridge</prototype>
  <space>
    <!--wrapped space...--></space>
</overlay>
Import Requirements

To use HTTPBridgeOverlay overlay you must import the module urn:org:netkernel:tpt:http:

<import>
  <uri>urn:org:netkernel:tpt:http</uri>
</import>

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.

Configuration

The HTTPBridge should be configured to reside immediately after the HTTPTransport as shown in the following example:

<rootspace>
  <endpoint>
    <prototype>HTTPTransport</prototype>
  </endpoint>
  <overlay>
    <prototype>HTTPBridge</prototype>
    <config>
      <rewrite>
        <match>http://.*?/(.*)</match>
        <to>res:/$1</to>
      </rewrite>
    </config>
    <space>
      <!-- Wrapped Space --></space>
  </overlay>
  <fileset>
    <private />
    <regex>res:/etc/HTTPServerConfig.xml</regex>
  </fileset>
  <import>
    <private />
    <uri>urn:org:netkernel:ext:system</uri>
  </import>
  <import>
    <private />
    <uri>urn:org:netkernel:ext:layer1</uri>
  </import>
  <import>
    <private />
    <uri>urn:org:netkernel:tpt:http</uri>
  </import>
</rootspace>

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 httpRequest: and httpResponse: URI scheme, mapping them to the information in the underlying HTTPRequest and HTTPResponse objects.

Requests issued in the wrapped space for httpRequest: can retrieve information ... Requests issued with the SINK verb in the wrapped space for httpResponse: scheme 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.

Instantiation

To wrap an application space with the HTTPBridge overlay create the following overlay declaration

<overlay>
  <prototype>HTTPBridge</prototype>
  <exceptionHandler>res:/introspect/exceptionhandler</exceptionHandler>
  <config>
    <rewrite>
      <match>http://.*?/(.*)</match>
      <to>res:/$1</to>
    </rewrite>
    <defaultPostParamEncoding>UTF-8</defaultPostParamEncoding>
  </config>
  <space> Application Space </space>
</overlay>

exceptionHandler

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

<exceptionHandler>active:myExceptionHandler</exceptionHandler>

then the following request will be issued:

<request>
  <identifier>active:myExceptionHandler</identifier>
  <argument name="operand"> ...serialised xml literal ... </argument>
</request>

config

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.