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:HTTPSessionOverlay
Description:Provides a session address space for HTTP client-server Cookie sessions
Id:jetty.HTTPSession
Category:transparent overlay

HTTPSessionOverlay is a transparent 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.HTTPSession prototype has the following initialisation parameters:

NameRulesTypingDefaultDescription
configOptionalIdentifier or XMLnull
configuration of session
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 HTTPSessionOverlay:

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

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

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

The HTTPSession overlay manages the association between local session context and HTTP Cookies exchanged with browser clients. This allows NetKernel applications to maintain the illusion of a session with a browser while using the stateless HTTP protocol.

When an HTTP request arrives with a recognized cookie, the overlay will dynamically insert the session's space into the request context. This allows all subsequent processing of the request to retrieve or store session state. If a request arrives without a cookie, the HTTPSession overlay will create a new empty session space and insert the associated cookie into the response sent back to the browser.

The inserted space resolves requests for the session: scheme and support the full set of ROC verbs (see below for details).

Configuration

To add HTTP cookie based session context to an application, wrap an application space with the HTTPSession overlay as shown in the following example:

<overlay>
  <prototype>HTTPSession</prototype>
  <config>
    <maxSessions>500</maxSessions>
    <expiryPeriod>300000</expiryPeriod>
  </config>
  <space> Application Space </space>
</overlay>

Where the optional config parameter is an XML document with the following optional tags. The values shown here are the default values if none is specified.

<config>
  <maxSessions>64</maxSessions>
  <minDuration>300000</minDuration>
  <maxDuration>3000000</maxDuration>
  <cookiePath>/</cookiePath>
  <cookieName>NETKERNEL_SESSION_COOKIE</cookieName>
  <autoReconnect>true</autoReconnect>
</config>

  • maxSessions - the maximum number of simultaneous sessions managed by the overlay.
  • cookiePath - the path from the root of the HTTP server where the cookie will be placed. The browser will return the cookie on all requests with URLs at or below this path. An example path is "/tools/"
  • cookieName - the name of the cookie used to hold the session token. If no name is specified the name defaults to "NETKERNEL_SESSION_COOKIE".
  • autoReconnect - a boolean value, if true then an expired session will be automatically renewed if available, if false an expired session exception will be thrown.
  • minDuration - the session will be remain valid for at least these many milliseconds with no activity
  • maxDuration - the session will remain valid for at most these many milliseconds with no activity

If the maximum number of sessions is exceeded then a "Too Many Sessions" exception will be thrown. When sessions expire and autoReconnect isn't true a "Session Expired" exception will be thrown.

Note: the HTTPSession overlay must itself be wrapped by the HTTPBridge overlay at some point in the request scope.

session:

Session values may be read and written to using the session:scheme.