SOAP Resource Adaptor Guide

The SOAP Resource Adaptor lets SLEE services receive SOAP requests as events, and initiate SOAP requests to external systems.

Topics

Configuring the SOAP Resource Adaptor

configuring the resource adaptor using profiles and properties

Running the example SOAP RA service

installing and running the example service included with the SOAP Resource Adaptor

Other documentation for the SOAP Resource Adaptor including the changelog and links to the API JavaDoc and downloads, can be found on the SOAP Resource Adaptor product page.

Configuring the SOAP Resource Adaptor

Below are properties for configuring the SOAP Resource Adaptor (from the SOAP API), including properties for secure configuration.

Name Type Default Description Active reconfig?

Name	Type	Default	Description	Active reconfig?
`ListenAddress`	`String`	`127.0.0.1`	Local IP address that the SOAP resource adaptor will listen on for requests.	no
`ListenPort`	`Integer`	`8000`	Local TCP port that the SOAP resource adaptor will listen on for requests.	no
`BindAddresses`	`String`		Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the SOAP RA will listen on for requests. If BindAddresses is empty, ListenAddress and Listen Port will be employed. For syntax see Specifying bind addresses.	no
`MaxOutgoingConnections`	`Integer`	`30`	The maximum number of outgoing TCP connections the resource adaptor will open to a single host when sending requests to that host.	yes
`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 in case of asynchronous request, activity will end.	yes
`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.	yes
`MaxDepth`	`Integer`	`1`	Controls how many SOAP 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.	yes
`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".	yes
`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.	yes
`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.	yes
`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.	yes
`ServerName`	`String`	`Rhino-SOAP-Server/2.3`	The default value of the Server header set in outgoing responses. Applications may override this by setting the Server header in the response manually.	yes
`UserAgent`	`String`	`Rhino-SOAP-Client/2.3`	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.	yes
`AddressType`	`String`	`null`	Defines how the resource adaptor generates the javax.slee.Address object for SOAP 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.	yes
`MaxContentLength`	`Integer`	`262144`	Maximum value in bytes for the Content-Length header of the SOAP messages which have a message body. If this value is exceeded for incoming SOAPRequest (server mode), the connection is closed. For incoming SOAPResponse (client mode), application will see a 413 Client Error Response. MaxContentLength value update will apply to new connections.	yes
`WorkerCount`	`Integer`	`0`	The number of workers used by the server and client worker executors. 0 means use Netty default: 2 * `Runtime.availableProcessors()`	no
`AutomaticContentCompression`	`Boolean`	`false`	If enabled, the SOAP RA will compress outgoing responses automatically, while respecting the `Accept-Encoding` header (see RFC 2616 - section 14.3 for details).	no
`AutomaticContentDecompression`	`Boolean`	`true`	If enabled, the SOAP RA will decompress incoming responses automatically, while respecting the `Content-Encoding` header (see RFC 2616 - section 14.11 for details).	no
`SoapFactory`	`String`	`com.sun.xml.internal. messaging.saaj.soap.ver1_1. SOAPFactory1_1Impl`	The default value of the SoapFactory implementation class.	no
`SoapMessageFactory`	`String`	`com.sun.xml.internal. messaging.saaj.soap.ver1_1. SOAPMessageFactory1_1Impl`	The default value of the SoapMessageFactory implementation class.	no

ListenAddress

String

127.0.0.1

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

no

ListenPort

Integer

8000

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

no

BindAddresses

String

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

no

MaxOutgoingConnections

Integer

30

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

yes

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 in case of asynchronous request, activity will end.

yes

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.

yes

MaxDepth

Integer

1

Controls how many SOAP 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.

yes

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".

yes

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.

yes

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.

yes

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.

yes

ServerName

String

Rhino-SOAP-Server/2.3

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

yes

UserAgent

String

Rhino-SOAP-Client/2.3

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.

yes

AddressType

String

null

Defines how the resource adaptor generates the javax.slee.Address object for SOAP 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.

yes

MaxContentLength

Integer

262144

Maximum value in bytes for the Content-Length header of the SOAP messages which have a message body. If this value is exceeded for incoming SOAPRequest (server mode), the connection is closed. For incoming SOAPResponse (client mode), application will see a 413 Client Error Response. MaxContentLength value update will apply to new connections.

yes

WorkerCount

Integer

0

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

no

AutomaticContentCompression

Boolean

false

If enabled, the SOAP RA will compress outgoing responses automatically, while respecting the Accept-Encoding header (see RFC 2616 - section 14.3 for details).

no

AutomaticContentDecompression

Boolean

true

If enabled, the SOAP RA will decompress incoming responses automatically, while respecting the Content-Encoding header (see RFC 2616 - section 14.11 for details).

no

SoapFactory

String

com.sun.xml.internal. messaging.saaj.soap.ver1_1. SOAPFactory1_1Impl

The default value of the SoapFactory implementation class.

no

SoapMessageFactory

String

com.sun.xml.internal. messaging.saaj.soap.ver1_1. SOAPMessageFactory1_1Impl

The default value of the SoapMessageFactory implementation class.

no

Secure configuration

Name Type Default Description Active reconfig?

Name	Type	Default	Description	Active reconfig?
`SecureListenPort`	`Integer`	`0`	Local TCP port that the SOAP 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.	no
`SecureBindAddresses`	`String`		Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the SOAP 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 Specifying bind addresses.	no
`KeyStore`	`String`	`(empty)`	Path to JKS keystore file. System properties (such as `${rhino.dir.home}`) may be used.	no
`KeyStorePassword`	`String`	`(empty)`	Keystore password for file specified by KeyStore.	no
`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.	no
`TrustStorePassword`	`String`	`changeit`	Keystore password for file specified by TrustStore.	no
`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.	no
`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.	no
`NeedClientAuth`	`Boolean`	`false`	When set to true, this will set the same flag on the SSL Engine for incoming HTTPS connections, meaning a valid client certificate is required to connect. The client certificates can be retrieved from the `SOAPRequest` event using the `getClientDetails()` method.	no

SecureListenPort

Integer

0

Local TCP port that the SOAP 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.

no

SecureBindAddresses

String

Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the SOAP 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 Specifying bind addresses.

no

KeyStore

String

(empty)

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

no

KeyStorePassword

String

(empty)

Keystore password for file specified by KeyStore.

no

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.

no

TrustStorePassword

String

changeit

Keystore password for file specified by TrustStore.

no

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.

no

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.

no

NeedClientAuth

Boolean

false

When set to true, this will set the same flag on the SSL Engine for incoming HTTPS connections, meaning a valid client certificate is required to connect. The client certificates can be retrieved from the SOAPRequest event using the getClientDetails() method.

no

Specifying bind addresses

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

Running the Example SOAP RA Service

Below are basic instructions for deploying and testing the SOAP example services in your SLEE.

1

Start your SLEE:

$ cd $RHINO_HOME
$ ./start-rhino.sh

2

Go to the soap-examples folder:

$ cd soap-examples

3

Check the listen.port property in build.properties

The listen.port specifies the port that the SOAP RA will attempt to listen on when it is activated, and the port the test client will send to. The default port is 8000. Change it if necessary for your environment.

4

To deploy the examples, use the Ant deploy target:

$ ant deploy

This deploys the SOAP Resource Adapter and example SOAP services (Ping and Request).

5

To test the Ping service, use the simple SOAP client included with the examples. To compile and run it, use the run-test-client target:

$ ant run-test-client

The SOAP client
(src/com/opencloud/slee/example/soap/client/SoapClient.java):

reads a SOAP envelope from the file
(src/com/opencloud/slee/example/soap/client/pingtest.xml),
sends the envelope to the URL represented by the SOAP RA
(http://localhost:listening-port)
and prints the response received, sent by the Ping service
(src/com/opencloud/slee/example/soap/ping/SoapPingSbb.java).

6

To test the Ping service over secured connection (TLS) with client’s certificate, use the simple SOAP client included with the examples. To compile and run it, use the run-test-client-https target:

$ ant run-test-client-https

The SOAP client
(src/com/opencloud/slee/example/soap/client/SoapClient.java):

reads a SOAP envelope from the file
(src/com/opencloud/slee/example/soap/client/pingtest.xml),
sends the envelope to the secured URL represented by the SOAP RA
(https://localhost:secured-port)
reads the client’s certificate from the file
(soap-ra.ks)
and prints the response received, sent by the Ping service
(src/com/opencloud/slee/example/soap/ping/SoapPingSbb.java).

7

To test the Request service, use another SOAP client included with the examples. To activate and deactivate the service, use the run-request target and see the response on the Rhino log:

$ ant run-request

The SOAP client Request service
(src/com/opencloud/slee/example/soap/request/SoapRequestSbb.java):

sends the same request,
creates a SOAP request on activation,
and logs the response sent back.