Module

urn:org:ten60:netkernel:ext:http:client

URI

active:httpState

Purpose

The HTTP Client accessors httpGet, httpPost httpPut and httpDelete are services which issue HTTP client requests. Although HTTP/REST is a stateless protocol there are situations in which client-side state is necessary - for example applications which issue session cookies.

The httpState data accessor is a service which manages and stores URI addressable HTTP state resources, these are used to hold state across different invocations of the http client accessors.

Cookies

An HTTP-state resource will store all server-generated cookies. When a state resource containing cookies is presented to an HTTP client accessor the accessor will use the state to automatically present a stored cookie to the issuing server with each HTTP request. The HTTP client will automatically SINK a new state resource to the httpState accessor if the remote server issues/updates cookies.

Credentials

An HTTP-state resource can store access control credentials. Stored credentials will be automatically used to access an HTTP server using simple, digest or NT domain access control protocols - for how to register credentials, see NEW below.

Usage

NEW

A NEW request to active:httpState will create a new HTTP state resource and return the URI of the state resource.

Registering Access Control Credentials

An HTTP state resource can hold credentials (username, password) for basic, digest and NT domain HTTP authentication protocols.

The basic NEW request will just specify a URI of... active:httpState

When issuing a NEW request you can optionally provide a credentials argument... active:httpState+credentials@[credentials reference]

When issuing a NEW request you can optionally provide an id to determine the URI of the resulting state resource... active:httpState+id@my-id

The credentials argument must be an XML document of the following form.

Note realm is optional - if not supplied then the username password will be issued with all requests to the given host. The NTRequestHost and NTDomain are only required when the server is using Microsoft's proprietary NTDomain HTTP authenticaiton mechanism.

The result of a NEW is the URI to the newly created state resource, such as:

active:httpState+id@ABCDABCDACBD123412334

SOURCE

A SOURCE request to an active:httpState URI will return the HTTP state resource at the URI.

eg SOURCE active:httpState+id@ABCDABCDACBD123412334 returns a state resource.

SINK

A SINK request to an active:httpState will replace the state resource at the given URI by a supplied IAspectHttpState resource.

NB This is generally not a user-level operation, it is performed by the HTTP client accessors if the state is changed by the remote HTTP request.

DELETE

A DELETE request to an active:httpState will delete the state resource.

To prevent wasted resources you should can clean up the httpState by deleting any state resources when you are finished with them. However unused states are currently discarded after 10 minutes.

EXISTS

Tests that the given state resource exists.