About the HTTP Resource Adaptor

The HTTP Resource Adaptor:

  • provides a generic HTTP interface for SLEE services

  • supports Hypertext Transfer Protocol (HTTP), as specified RFC1945 and RFC2616

  • is bidirectional; applications can receive incoming HTTP requests and also initiate outgoing HTTP requests

  • implements a subset of HTTP/1.1 (request methods GET, HEAD, POST, PUT and DELETE)

  • supports incoming and outgoing HTTPS.

Topics

This document includes the following topics:

Topic Explains how to…​

Configuring the HTTP Resource Adaptor

configure the resource adaptor using profiles and properties

Events and Activities

use event types, activities, ACI and SBB interfaces

Running the Example HTTP service

install and run the example service included with the HTTP Resource Adaptor

More information

Download

Tip Download an evaluation version of the HTTP Resource Adaptor package.

Configuring the HTTP Resource Adaptor

Below are properties for configuring the HTTP resource adaptor (from the HTTP API), including properties for secure configuration.

Name Type Default Description

ListenAddress

String

127.0.0.1

Local IP address that the HTTP resource adaptor will listen on for requests.

ListenPort

Integer

8000

Local TCP port that the HTTP resource adaptor will listen on for requests.

BindAddresses

String

Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the HTTP RA will listen on for requests. If BindAddresses is empty, ListenAddress and Listen Port will be employed. For syntax see note below Secure configuration.

MaxOutgoingConnections

Integer

5

The maximum number of outgoing TCP connections the resource adaptor will open to a single host when sending requests to that host.

OutgoingRequestTimeout

Long

10000

The time (in ms) that the resource adaptor will wait for a response to an outgoing request before failing the request. The application will see a 500 Server Error response and the activity is ended.

OutgoingIdleTimeout

Long

60000

The time (in ms) that the resource adaptor will keep an outgoing TCP connection open for, with no activity on the connection.

MaxDepth

Integer

1

Controls how many HTTP requests may be queued up on a single connection without receiving a response from the server. This is known as "HTTP pipelining". A value of 1 is strongly recommended if the server does not support non-persistent connections. When the connection closes (which it always will if they are non-persistent) the other requests in the pipeline will have to be re-sent on another connection. A value of 1 is also recommended for slow or unreliable servers, to avoid head-of-line blocking.

QueueTimeout

Long

5000

The time (in ms) that a request can be held on the queue waiting for an outgoing connection before timing out and firing an event with response code 500 and reason "timed out waiting for server connection".

NewConnectionDelay

Long

100

When a burst of (send) requests occurs, the resource adaptor queues them, and only creates new connections if they cannot be sent on existing connections. NewConnectionDelay is the time in milliseconds that the resource adaptor will wait for an outgoing connection to become available before creating a new one. If the server does not support persistent connections, it is strongly recommended that this value be set to 0.

IncomingRequestTimeout

Long

5000

The time (in ms) that the resource adaptor will wait for the SLEE to send a response to an incoming request before failing the request. The resource adaptor will automatically send an error response to the client and end the activity.

IncomingIdleTimeout

Long

60000

The time (in ms) that the resource adaptor will keep an incoming TCP connection open for, with no activity on the connection.

ServerName

String

Rhino-HTTP-Server/2.2

The default value of the Server header set in outgoing responses. Applications may override this by setting the Server header in the response manually.

UserAgent

String

Rhino-HTTP-Client/2.2

The default value of the User-Agent header set in outgoing requests. Applications may override this by setting the User-Agent header in the request manually.

AddressType

String

null

Defines how the resource adaptor generates the javax.slee.Address object for HTTP events. Default is to not use any address. Setting this to the value uripath will make the resource adaptor use a URI address with the value of the path in the request URL. For example, http://localhost/test/zzz?query=yyy will create an address with address plan AddressPlan.URI and value "/test/zzz". Responses have no address.

MaxContentLength

Integer

1048576

Maximum value in bytes for the Content-Length header of the HTTP messages which have a message body. If this value is exceeded, the application will see a 413 Client Error Response. MaxContentLength value update will apply to new connections.

WorkerCount

Integer

0

The number of workers used by the server and client worker executors. 0 means use Netty default: 2 * untime.availableProcessors()

AutomaticContentCompression

Boolean

false

If enabled, the HTTP RA will compress outgoing responses automatically, while respecting the Accept-Encoding header (see RFC 2616 - section 14.3 for details). This applies only to the following supported content encodings: gzip, deflate. If there is no matching encoding, no compression is done. For multiple values of Accept-Encoding header, encoding format is chosen according to following priorities: gzip, deflate. The qvalue parameter and * wildcard are ignored in current version of HTTP RA.

AutomaticContentDecompression

Boolean

true

If enabled, the HTTP RA will decompress incoming responses automatically, while respecting the Content-Encoding header (see RFC 2616 - section 14.11 for details). This applies only to the following supported content encodings: gzip, deflate. If there is no matching encoding, no decompression is done.
Note ThreadPoolSize, MaxChannelMemorySize and MaxTotalMemorySize are not currently used. In future, they will support configuration of the Netty OrderedMemoryAwareThreadPoolExecutor.

Secure configuration

Name Type Default Description

SecureListenPort

Integer

0

Local TCP port that the HTTP resource adaptor will listen on for HTTPS requests. If set to a value greater than 0, then a KeyStore must be provided that contains the private key for the server.

SecureBindAddresses

String

Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the HTTP RA will listen on for requests. If SecureBindAddresses is empty, ListenAddress and SecureListenPort will be employed. If a SecureBindAddress is specified then a KeyStore must be provided that contains the private key for the server. For syntax see note below.

KeyStore

String

(empty)

Path to JKS keystore file. System properties (such as ${rhino.dir.home}) may be used.

KeyStorePassword

String

(empty)

Keystore password for file specified by KeyStore.

TrustStore

String

${java.home}/lib/security/cacerts

Path to JKS keystore for trust certificates. The special value <<TRUST ALL>> may be used to bypass trust checks.

TrustStorePassword

String

changeit

Keystore password for file specified by TrustStore.

CipherSuites

String

(empty)

List of cipher suites to pass to SSLEngine.setEnabledCipherSuites(). An empty value means the method won’t be called and all cipher suites are enabled.

SSLSessionTimeout

Integer

0

Value to pass to SSLContext.setSessionTimeout() after the context is created. A value of 0 means the method won’t be called.
Note

BindAddresses and SecureBindAddresses are specified as a comma-separated list of {node}host:port elements.

This allows entities running on two nodes on the same host to use different ports, for example: {101}0.0.0.0:8000,{102}0.0.0.0:8001.

It also allows entities running on different hosts to specify an interface to listen on that is specific to each host, for example: {101}192.168.1.100:8000,{102}192.168.1.101:8000.

Events and Activities

Below are details of events, activities, and the ACI and SBB interfaces for the HTTP Resource Adaptor.

Events

The HTTP resource adaptor emits the following event types:

Note All listed classes are in the com.opencloud.slee.resources.http package.

Event ID

name=com.opencloud.slee.resources.http.HttpRequest.GET,vendor=OpenCloud,version=2.2

Event Object

HttpRequest

Activity Object

IncomingHttpRequestActivity

Description

The resource adaptor received an HTTP GET request.

Event ID

name=com.opencloud.slee.resources.http.HttpRequest.POST,vendor=OpenCloud,version=2.2

Event Object

HttpRequest

Activity Object

IncomingHttpRequestActivity

Description

The resource adaptor received an HTTP POST request.

Event ID

name=com.opencloud.slee.resources.http.HttpRequest.HEAD,vendor=OpenCloud,version=2.2

Event Object

HttpRequest

Activity Object

IncomingHttpRequestActivity

Description

The resource adaptor received an HTTP HEAD request.

Event ID

name=com.opencloud.slee.resources.http.HttpRequest.PUT,vendor=OpenCloud,version=2.2

Event Object

HttpRequest

Activity Object

IncomingHttpRequestActivity

Description

The resource adaptor received an HTTP PUT request.

Event ID

name=com.opencloud.slee.resources.http.HttpRequest.DELETE,vendor=OpenCloud,version=2.2

Event Object

HttpRequest

Activity Object

IncomingHttpRequestActivity

Description

The resource adaptor received an HTTP DELETE request.

Event ID

name=com.opencloud.slee.resources.http.HttpResponse,vendor=OpenCloud,version=2.2

Event Object

HttpResponse

Activity Object

OutgoingHttpRequestActivity

Description

The resource adaptor received a response to an earlier outgoing HTTP request. Only one response event type is defined (instead of separate events 2xx, 3xx and so on), because the resource adaptor assumes that applications will always want to see the HTTP response, regardless of the status-code value.

Activities

The HTTP resource adaptor creates two types of activities:

Activity Object Description

IncomingHttpRequestActivity

This activity is created when the resource adaptor receives a HTTP request. The activity object has methods for creating and sending a response to the request. The activity ends when the response is sent. In addition, if for some reason a SBB does not send a response in time, the resource adaptor will automatically send an error response back to the client, ending the activity. The timeout is specified by the IncomingRequestTimeout configuration property.

OutgoingHttpRequestActivity

This activity is created when a SBB sends an outgoing HTTP request. There is nothing that can be done with the activity, it is only there so that the SBB may attach to it in order to receive the response asynchronously.

Activity Context Interface Factory

The ACI Factory interface is HttpActivityContextInterfaceFactory.

SBB Interface

The SBB Interface is HttpProvider. This interface must be used for creating and sending outgoing requests. If the service only deals with incoming requests, then this interface does not need to be used.

Running the Example HTTP Service

HTTP resource adaptor package includes an example "Ping" service. This service simply responds with a page displaying the request contents.

Install and run the service

Below are basic instructions for deploying and testing the HTTP example service in your SLEE, followed by an excerpt of SBB code showing how a client sends and a server processes HTTP requests.

1

Install the service:

$ cd examples
$ ant

2

Navigate to http://localhost:8000/ in a web browser.

HTTPS

To enable HTTPS:

1

Generate a keystore for the server:

$ keytool -keystore http-ra.ks -storepass changeit -genkeypair
Warning The http-ra.ks file should be placed in the Rhino home directory. The resource adaptor has a default FilePermission allowing it to read ${rhino.dir.home}/http-ra.ks. If you put the file elsewhere or give it a different name, you will need to update the security permissions for the resource adaptor entity.

2

Configure the resource adaptor entity and restart it:

rhino$ client/bin/rhino-console
[Rhino@localhost (#0)] updateraentityconfigproperties httpra SecureListenPort 8002 KeyStore "${rhino.dir.home}/http-ra.ks" KeyStorePassword changeit
[Rhino@localhost (#1)] deactivateraentity httpra
[Rhino@localhost (#2)] activateraentity httpra

3

The URL https://localhost:8002/ should now display the same page as before, using HTTPS.

Sample code

Below are excerpts of SBB code showing how servers can process HTTP requests, and clients can send them.

Server

Below is an excerpt of SBB code showing how incoming HTTP requests can be processed.

import com.opencloud.slee.resources.http.*;

...

// SBB event handler
public void onGET(HttpRequest event, ActivityContextInterface aci) {
    IncomingHttpRequestActivity activity = (IncomingHttpRequestActivity) aci.getActivity();
    // Send a redirect response...
    HttpResponse response = activity.createResponse(302, "Moved Temporarily");
    response.setHeader("Location", "http://anotherserver/index.html");
    try {
        activity.sendResponse(response);
    } catch (IOException e) {
        warn("unable to send response", e);
    }
}

Client

Below is an excerpt of SBB code showing how outgoing HTTP requests can be made.

import com.opencloud.slee.resources.http.*;

...

public void setSbbContext(SbbContext sbbContext) {
    this.sbbContext = sbbContext;
    Context sbbEnv = (Context) new InitialContext().lookup("java:comp/env");
    provider = (HttpProvider) sbbEnv.lookup("slee/resources/http/2.2/provider");
    acif = (HttpActivityContextInterfaceFactory) sbbEnv.lookup("slee/resources/http/2.2/acifactory");
    ...
}

public void onSomeEvent(SomeEvent event, ActivityContextInterface aci) {
    ...
    HttpRequest newRequest = provider.createRequest(HttpRequest.POST, new URL("http://someserver/service.jsp"));
    newRequest.setContentAsString("text/plain; charset=\"utf-8\"", "test message");

    OutgoingHttpRequestActivity activity = provider.sendRequest(newRequest);
    ActivityContextInterface newACI = acif.getActivityContextInterface(activity);
    // attach so we will receive response...
    newACI.attach(sbbContext.getSbbLocalObject());
}

public void onHttpResponse(HttpResponse event, ActivityContextInterface aci) {
    trace("Received " + event.getStatusCode() + " response");
    byte[] data = event.getContent();   // Or getContentAsString() if appropriate
    // process response content...
}

// instance vars
private SbbContext sbbContext;
private HttpProvider provider;
private HttpActivityContextInterfaceFactory acif;

Resource Adaptor Type API

Tip HTTP Resource Adaptor Type API Javadoc

Changelog

Version 2.2.0.14

  • The resource adaptor configuration property "MaxContentLength" default value has been increased from 256KB to 1024KB, and is now passed through to the transport layer. (HTTP-155)

Version 2.2.0.13

  • Removed incorrect handling of "Expect: 100-continue" header. (HTTP-136)

Version 2.2.0.12

  • Fixed an AssertionError thrown when closing a connection due to no response from the server. This error prevented the resource adaptor from firing an answer event (with response code 500) as it did previously. (HTTP-132)

Version 2.2.0.11

  • Add a getRequestURI() method to HttpRequest, to expose the Request-URI exactly as it appears in the Request-Line of a request. (HTTP-122)

Version 2.2.0.10

  • Fixed a bug which caused HTTP message decoding errors under load when acting as a server. (HTTP-83)

  • Fixed a bug which leaked timer threads when a resource adaptor entity was deactivated and reactivated. (HTTP-79)

  • Added support for response content compression and decompression. These are activated by the new config properties: "AutomaticContentCompression" and "AutomaticContentDecompression". (HTTP-72)

Version 2.2.0.9

  • RA now responds with "HTTP/1.0 400 Bad Request" to HTTP Request containing invalid version before closing the connection. Previously connection was closed without a response. (HTTP-24)

  • Add bytesRx / bytesTx client and server RA statistics representing number of bytes received and number of bytes sent respectively. (HTTP-32)

  • Eagerly end activities when corresponding connection is closed by remote peer. Previously such activities where ended lazily when a response was sent by SBB. If response was never generated such an activity would be alive until administratively removed. (HTTP-61)

  • Fixed an issue where URLs of incoming requests were being created with the IP address and port of the client rather than the server. (HTTP-62)

Version 2.2.0.8

  • Add a new config property "BindAddresses" that allows a different bind address (network address and port combination) to be specified for each node in a cluster. It is a string property with the format "{node}address:port,{node}address:port,…​". This allows entities running on two nodes on the same host to use different ports, for example: "{101}0.0.0.0:8000,{102}0.0.0.0:8001". It also allows entities running on different hosts to specify an interface to listen on that is specific to each host, for example: "{101}192.168.1.100:8000,{102}192.168.1.101:8000". (HTTP-46)

  • Add a new config property "SecureBindAddresses" that works the same way as "BindAddresses", but for the HTTPS listeners. (HTTP-47)

  • Additional permissions have been added to allow keystores to be read from more locations without needing to update the security policy. The new locations are the files "http-ra.ks" and "http-ra.trust.ks" in the Rhino base directory (previously there was only a permission for http-ra.ks in the Rhino node directory), and anything in the "keystores" directory under Rhino base. (HTTP-59)

  • Removed the default values for ListenAddress and ListenPort from the resource adaptor configuration properties.

Version 2.2.0.7

  • Add a new config property "NeedClientAuth". When set to true it will set the same flag on the SSL Engine for incoming HTTPS connections, meaning a valid client certificate is required to connect. (HTTP-43)

Version 2.2.0.6

  • Fix a null pointer exception in inactive RA entities, when multiple RA entities exist. (HTTP-39)

Version 2.2.0.5

  • If the URL used to create a request has no path (e.g. "http://localhost"), use "/" as the requested resource. This restores the behaviour of previous releases. (HTTP-37)

Version 2.2.0.4

  • Fixed a bug that prevented response headers from being sent. (HTTP-36)

  • Fixed URL for Netty and Guava libraries in example deployment scripts. (HTTP-35)

Version 2.2.0.2

  • The HTTP transport layer used by the resource adaptor is now implemented using Netty. (HTTP-28)

  • Added TLS support to the HTTP RA (for both incoming and outgoing connections). (HTTP-15)

  • The packaging of the libraries and examples for the HTTP RA has been improved. (HTTP-20)

  • Incoming requests will now timeout correctly and send an error answer to the client. (HTTP-2)

  • 100 Continue responses will not be fired as events and will not end the activity; the request will remain pending until the full response arrives. (HTTP-13)

  • Renamed ReconnectTimeout configuration property to NewConnectionDelay, which is a better description of its purpose. Changed its default value from 1500ms to 100ms. (HTTP-5)

  • Changed default value of configuration property MaxDepth from 5 to 1. (HTTP-5)

  • Changed default value of configuration property MaxOutgoingConnections from 5 to 30. (HTTP-5)

  • Tracer names are no longer prefixed with "resource.<entity name>". (HTTP-8)

  • An alarm is now raised if no valid license is found when activating HTTP and SOAP RAs. (HTTP-11)

  • The HTTP load generator that was in the old Web Connectivity Pack is not included in this HTTP package. (HTTP-26)