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:HTTPTransportEndpoint
Description:A HTTP transport based on Jetty
Id:jetty.HTTPTransport
Category:transport

HTTPTransportEndpoint is a transport that must be instantiated from a prototype.

Parameters

The jetty.HTTPTransport prototype has the following initialisation parameters:

NameRulesTypingDefaultDescription
configOptionalIdentifier or XMLres:/etc/HTTPServerConfig.xml
Configuration for Jetty server
idOptionalStringnull
An identifier for created logical endpoint, if omitted a unique auto-generated value it will be used.
privateOptionalBooleanfalse
If included this parameter will mark the endpoint as private and it will not be exposed outside module.
maxQueueLengthOptionalInteger2147483647
Limit length of queue accepting pending requests

Here is an auto-generated example of how to instantiate an instance of HTTPTransportEndpoint:

<transport>
  <prototype>jetty.HTTPTransport</prototype>
</transport>
Import Requirements

To use HTTPTransportEndpoint transport you must import the module urn:org:netkernel:tpt:http:

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

HTTPTransport is a low-level HTTP server. The transport detects an external HTTP protocol requests arriving on a configured TCP/IP port and constructs a root request which it issues into its containing space. The root request identifier is the URL of the external HTTP request (Refer to the HTTPBridge documentation to see how to map the external URL to the normalized res:/ scheme). The transport wraps the low-level HTTPRequest and HTTPResponse objects into a HTTPRequestResponseRepresentation and adds it as the primary argument. The transport uses the SOURCE verb for the root request (The HTTP method is available through the httpRequest: address space).

Configuration

An HTTP transport is instantiated from its prototype in a space by using the following declaration (Refer to the HTTPBridge documentation for a configuration example of the transport and bridge)

<transport>
  <prototype>HTTPTransport</prototype>
</transport>

The HTTPTransport will issue a request for the resource res:/etc/HTTPServerConfig.xml using the SOURCE verb to obtain its configuration information. This resource must be present in space in which the transport is configured.

HTTPServerConfig.xml is a XML document containing configuration information for the Jetty HTTP server library. Please consult the Jetty web site (http://www.eclipse.org/jetty/documentation/current/reference-section.html#jetty-xml-syntax) for details about the various configuration options.

The following link shows an example and is the default configuration for the Front-end fulcrum.

Example Configuration

NetKernelHandler

The HttpTransport must have one Jetty handler implementing org.netkernel.http.transport.INetKernelHandler - the example above shows a configuration of two handlers. The first is the NetKernelWebSocketHandler - which will deal with WebSocket upgrade requests. The second and fallback default is the NetKernelHandler which handles all regular HTTP requests.

TCP/IP Port

The TCP/IP port used by the Jetty server is set in a configuration line; the following sets the port to 8080:

<Set name="port">8080</Set>

SSL

To add SSL sockets examine /etc/HTTPServerConfig.xml in the front-end fulcrum and uncomment the following optional settings...

<Configure> ... Other Options Not Shown...
  <!--TLS Configuration - UNCOMMENT THE FOLLOWING THREE STATEMENT BLOCKS TO ENABLE TLS-->
  <!-- =========================================================== -->
  <!-- Create a TLS specific HttpConfiguration based on the -->
  <!-- common HttpConfiguration defined above -->
  <!-- Add a SecureRequestCustomizer to extract certificate and -->
  <!-- session information -->
  <!-- =========================================================== -->
  <New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
    <Arg>
      <Ref refid="httpConfig" />
    </Arg>
    <Call name="addCustomizer">
      <Arg>
        <New class="org.eclipse.jetty.server.SecureRequestCustomizer" />
      </Arg>
    </Call>
  </New>
  <!-- ============================================================= -->
  <!-- Create a TLS (SSL) Context Factory -->
  <!-- ============================================================= -->
  <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath">
      <Property name="jetty.base" default="." />/
      <Property name="jetty.keystore" default="/home/pjr/workspace/keystore" />
    </Set>
    <Set name="KeyStorePassword">
      <Property name="jetty.keystore.password" default="test123" />
    </Set>
    <Set name="KeyManagerPassword">
      <Property name="jetty.keymanager.password" default="test123" />
    </Set>
    <Set name="TrustStorePath">
      <Property name="jetty.base" default="." />/
      <Property name="jetty.truststore" default="/home/pjr/workspace/keystore" />
    </Set>
    <Set name="TrustStorePassword">
      <Property name="jetty.truststore.password" default="test123" />
    </Set>
    <Set name="EndpointIdentificationAlgorithm" />
    <Set name="NeedClientAuth">
      <Property name="jetty.ssl.needClientAuth" default="false" />
    </Set>
    <Set name="WantClientAuth">
      <Property name="jetty.ssl.wantClientAuth" default="false" />
    </Set>
    <Set name="ExcludeCipherSuites">
      <Array type="String">
        <Item>SSL_RSA_WITH_DES_CBC_SHA</Item>
        <Item>SSL_DHE_RSA_WITH_DES_CBC_SHA</Item>
        <Item>SSL_DHE_DSS_WITH_DES_CBC_SHA</Item>
        <Item>SSL_RSA_EXPORT_WITH_RC4_40_MD5</Item>
        <Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
        <Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
        <Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item>
      </Array>
    </Set>
  </New>
  <!-- =========================================================== -->
  <!-- Add a SSL Connector with protocol factories -->
  <!-- =========================================================== -->
  <Call name="addConnector">
    <Arg>
      <New id="sslConnector" class="org.eclipse.jetty.server.ServerConnector">
        <Arg name="server">
          <Ref refid="Server" />
        </Arg>
        <Arg name="acceptors" type="int">
          <Property name="ssl.acceptors" default="-1" />
        </Arg>
        <Arg name="selectors" type="int">
          <Property name="ssl.selectors" default="-1" />
        </Arg>
        <Arg name="factories">
          <Array type="org.eclipse.jetty.server.ConnectionFactory">
            <Item>
              <New class="org.eclipse.jetty.server.SslConnectionFactory">
                <Arg name="next">http/1.1</Arg>
                <Arg name="sslContextFactory">
                  <Ref refid="sslContextFactory" />
                </Arg>
              </New>
            </Item>
            <Item>
              <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                <Arg name="config">
                  <Ref refid="sslHttpConfig" />
                </Arg>
              </New>
            </Item>
          </Array>
        </Arg>
        <Set name="host">
          <SystemProperty name="netkernel.http.frontend.host" default="0.0.0.0" />
        </Set>
        <Set name="port">
          <Property name="netkernel.http.frontend.secure.port" default="8443" />
        </Set>
        <Set name="idleTimeout">
          <Property name="ssl.timeout" default="30000" />
        </Set>
        <Set name="soLingerTime">
          <Property name="ssl.soLingerTime" default="-1" />
        </Set>
        <Set name="acceptorPriorityDelta">
          <Property name="ssl.acceptorPriorityDelta" default="0" />
        </Set>
        <Set name="acceptQueueSize">
          <Property name="ssl.acceptQueueSize" default="0" />
        </Set>
      </New>
    </Arg>
  </Call>
</Configure>

A Java keystore must be configured to hold your SSL certificate and must be referenced using a regular file path and not a URI. For details see the Jetty Wiki.

NCSA standard request logging

To add NCSA standard request logging, add the following to the Jetty configuration file:

<Call name="addHandler">
  <Arg>
    <New id="Logger" class="org.eclipse.jetty.server.handler.RequestLogHandler">
      <Set name="requestLog">
        <New id="RequestLogImpl" class="org.eclipse.jetty.server.NCSARequestLog">
          <Set name="filename">./log/FEFNetKernelHTTP_yyyy_mm_dd.log</Set>
          <Set name="filenameDateFormat">yyyy_MM_dd</Set>
          <Set name="retainDays">90</Set>
          <Set name="append">true</Set>
          <Set name="extended">true</Set>
          <Set name="logCookies">false</Set>
          <Set name="LogTimeZone">GMT</Set>
        </New>
      </Set>
    </New>
  </Arg>
</Call>

HTML5 WebSockets

By default the Front-end fulcurm enables HTML5 WebSockets. It registers the org.netkernel.http.transport.NetKernelWebSocketHandler with this declaration...

<Call name="addHandler">
  <Arg>
    <New id="NetKernelWebSocketHandler" class="org.netkernel.http.transport.NetKernelWebSocketHandler" />
  </Arg>
</Call>

If this handler detects a WebSocket request it adds a WebSocket object to the HTTPRequestResponseRepresentation issued by the HTTPTransport.

The HTTPBridge is able to detect WebSocket requests and will automatically construct a WebSocket Transport from which WebSocket events are issued as ROC requests

maxQueueLength Parameter

By default Jetty allows an unbounded queue of inbound requests to build up if requests all arrive through the same open connection. This parameter overrides the default jetty value of Integer.MAX_VALUE. Unfortunately this parameter can only be set in the constructor of the jetty server and so it cannot go into the general config.