The HTTP Scenario Pack adds support for the Hypertext Transfer Protocol to the OpenCloud Scenario Simulator.

Topics

Topic

Explains how to…​

Configuring the HTTP Scenario Pack

configure the scenario pack

Examples

install and run the HTTP examples

Documentation for the OpenCloud Scenario Simulator and other Scenario Packs, including links to changelogs and downloads, can be found on the Scenario Simulator product page

Configuration

HTTP Scenario Pack configuration consists of:

  1. Scenario Simulator Command script file

  2. HTTP Scenario Pack configuration properties

  3. XML schema configuration files

Scenario Simulator Command Script File

Scenario Simulator Command Script Files by default can be found under location: <scenario_simulator>/http-examples/config/*.commands.

There are scripts for client and server setup with and without TLS support. These files contains scenario simulator commands. Usage of a commands script file is recommended but not required as it is possible to run all the required commands manually from the simulator prompt.

Below is the content of the setup-client.commands script file:

set-endpoint-address client client.opencloud.co.nz:9999
create-local-endpoint client http
bind-role client client

set-endpoint-address server server.opencloud.co.nz:8080
bind-role server server

The first set-endpoint-address command sets the address of "client" to client.opencloud.co.nz:9999.

The second set-endpoint-address commands sets the address of "server" to server server.opencloud.co.nz:8080.

Command bind-role binds the client endpoint address to scenario role client and server endpoint address to scenario role server

HTTP Scenario Pack configuration properties

Below are properties for configuring the HTTP Scenario Pack, including properties for secure configuration:

Configuration properties
Name Type Default Description

IsClient

Boolean

true

Specifies whether the protocol adaptor will act as an HTTP client. If set to true (default), then it allows outgoing connections and sending HTTP requests.

IsServer

Boolean

true

Specifies whether the protocol adaptor will act as an HTTP server. If set to true (default), then it will listen on for HTTP requests.

MaxOutgoingConnections

Integer

20

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

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

ViaReceivedBy

String

null

Value that will be used as Via received-by (according to RFC 2616 - section 14.45) when Via header field marked as AUTO in an HTTP scenario message.

Secure configuration properties
Name Type Default Description

SecureServer

Boolean

false

Controls if the protocol adaptor will listen on for HTTPS requests. If set to true, then a KeyStore must be provided that contains the private key for the server.

KeyStore

String

(empty)

Path to JKS keystore file.

KeyStorePassword

String

(empty)

Keystore password for file specified by KeyStore.

TrustStore

String

(empty)

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.

SecureOutgoingConnections

String

(empty)

List of endpoint addresses (host_address[:port], where port is optional) to which all outgoing TCP connections opened by the protocol adaptor will be secure.

XML Schema Configuration Files

Scenario Simulator supports loading of external XML schemas to extend the range of supported data types as part of given scenario protocol schema.

In order to use an external XML schema in the HTTP Scenario Pack the XML schema needs to be installed according to the installation instructions below.

1

Copy the XML schema file into directory <scenario_simulator>/protocols/http-xml-schemas/

2

Configure the prefixes and xpaths mappings according to your needs in the configuration files: prefixes.cfg and xpaths.cfg located in directory <scenario_simulator>/protocols/http-xml-schemas/

For more details on how to configure the prefixes and xpaths mappings see the instructions below.

Prefix to namespace mapping configuration

Scenario Simulator provides a configuration of prefixes to target namespaces mappings. This configuration is used in order to assign unique prefixes to XML schema namespaces.

Prefixes are configured in the prefixes.cfg file located in directory <scenario_simulator>/protocols/http-xml-schemas/. After being defined the prefixes can be used within configuration of xPath expressions for selection of XML elements from installed XML schemas. In addition, depending on given XML schema qualification of local elements and attributes, the configured prefixes will be used in generated instance documents or XML fragments in encoded HTTP messages. Otherwise, if there is no prefix configured for given target namespace, a unique prefix will be generated.

Prefixes to namespaces mappings should be given in format as follows:

prefix=namespace

Where:

prefix    - is a valid prefix as defined in 'Namespaces in XML 1.0 (Third Edition) W3C Recommendation 8 December 2009'.
namespace - is a valid namespace name of existing schema as defined in 'Namespaces in XML 1.0 (Third Edition) W3C Recommendation 8
            December 2009'.

Example:

so=http://www.example.com/shiporder

Where 'so' is a prefix and 'http://www.example.com/shiporder' is the target namespace of the shiporder schema.

Note:

  1. External XML schema file should follow 'XML Schema Part 0: Primer Second Edition W3C Recommendation 28 October 2004' under http://www.w3.org/TR/xmlschema-0/.

  2. In case invalid schema file used or invalid mapping defined, when starting Scenario Simulator and Editor the error will be displayed describing the problem.

  3. <scenario_simulator> is the directory of your local installation of the Scenario Simulator.

  4. 'Namespaces in XML 1.0 (Third Edition) W3C Recommendation 8 December 2009' document can be found under http://www.w3.org/TR/xml-names/.

Field name to XML element mapping configuration

Scenario Simulator provides a configuration of field names to XML elements mappings. This configuration is used in order to assign unique field names under which the pointed XML elements from the installed XML schemas will be accessible as HTTP Message-Body types in the Scenario Simulator and Editor. Fields names to XML elements mappings are configured in the xpaths.cfg file located in directory <scenario_simulator>/protocols/http-xml-schemas/xpaths.cfg. Field name to XML element mapping should be given in format as follows:

field_name[COLON charset *(COMMA charset)]=xpath_expression

Where:

field_name       - is the name of the field representing XML element, used as HTTP Message-Body type.
charset          - is the optional character set, e.g. 'UTF-8'. If no charset is defined, then the default charset 'UTF-8' will be used.
xpath_expression - is the XPath expression which should evaluate to a single XML element defined in the XML schema. In the expression
                   as part of element path it is required to use prefixes declared in prefixes.cfg configuration file.

Example:

shiporder=/so:shiporder
shiporder:UTF-8=/so:shiporder
shiporder:UTF-8,windows-1250=/so:shiporder

Where prefix 'so' is defined in prefixes.cfg as 'so=http://www.example.com/shiporder'.

Note:

  1. The field_name must be unique.

  2. When more than one charset is declared, then a separate scenario field for each charset will be created representing the same XML element but having different underlying charset defined.

  3. It is possible to define more than one field_name for the same XPath expression.

  4. In case of incorrect mappings defined, e.g. duplicated prefixes configured or illegal field / charset name defined or invalid XPath expression used, when starting the Scenario Simulator and Editor the error will be displayed describing the problem.

Examples

The HTTP scenario pack is bundled with example configuration and scenario files.

The examples may be found in the <scenario_simulator>/http-examples directory.

The basic HTTP examples are stand-alone scenarios using the Scenario Simulator only. The HTTP Rhino examples show HTTP integrating with the Rhino TAS.

Basic HTTP Examples

Prerequisites

1

Add the following entries to /etc/hosts, substituting appropriate IP addresses for each simulator if they run on a remote server. In this example all simulators are running on the local host.

127.0.0.1 client client.opencloud.co.nz
127.0.0.2 server server.opencloud.co.nz

2

Start separate scenario simulators for each endpoint as needed for the examples below. The examples assume the working directory is the simulator base directory, i.e. the parent directory of the one containing this file.

To start scenario simulator instances without TLS:

$ ./scenario-simulator.sh -l simulator-server.log -f http-examples/config/setup-server.commands
$ ./scenario-simulator.sh -l simulator-client.log -f http-examples/config/setup-client.commands

To start scenario simulator instances with TLS:

$ ./scenario-simulator.sh -l simulator-server.log -f http-examples/config/setup-server-tls.commands
$ ./scenario-simulator.sh -l simulator-client.log -f http-examples/config/setup-client-tls.commands
Examples
Example 1. get.scen

A basic http GET request

  • requires client and server endpoints

  • load scenario on both endpoints: load-scenario http-examples/scenarios/get.scen

  • run session from "client" endpoint: run-session get

Example 2. redirect.scen

URL redirect

  • requires client and server endpoints

  • load scenario on both endpoints: load-scenario http-examples/scenarios/redirect.scen

  • run session from "client" endpoint: run-session redirect

Example 3. soap.scen

SOAP GET/200 exchange

  • requires client and server endpoints

  • load scenario on both endpoints: load-scenario http-examples/scenarios/soap.scen

  • run session from "client" endpoint: run-session soap

Example 4. OneAPISMS.scen

OneAPISMS send and status query

  • requires client and server endpoints

  • load scenario on both endpoints: load-scenario http-examples/scenarios/OneAPISMS.scen

  • run session from "client" endpoint: run-session OneAPISMS

Example 5. xcap.scen

Document creation, fetch and modification

  • requires client and server endpoints

  • load scenario on both endpoints: load-scenario http-examples/scenarios/xcap.scen

  • run session from "client" endpoint: run-session xcap

Important

For incoming http connections address to endpoint matching is based only on IP address ignoring the port. If two or more endpoints addresses resolve to the same host then simulator will consistently match incoming dialogs to only one of those endpoints.

If running more than one cooperating simulator instance locally that uses http it is recommended to define each endpoint with different local loop address example:

127.0.0.1 client
127.0.0.2 server
-----

HTTP Rhino examples

This page details examples of HTTP scenario integrating with Rhino, including

  • a ping scenario that uses RhinoSDK as the server, responding to GET request with the request contents

  • a pingSecure scenario that uses RhinoSDK as the server, responding to GET request with the request contents, using secure connection

Prerequisites

1

Add the following entries to /etc/hosts, substituting appropriate IP addresses for each simulator if they run on a remote server. In this example all simulators are running on the local host.

127.0.0.1 client client.opencloud.co.nz
127.0.0.2 server server.opencloud.co.nz

2

Deploy the HTTP resource adaptor and the Ping example HTTP service.

Examples
Example 6. HTTP example

Start one scenario-simulator session with the command:

./scenario-simulator.sh -l client.log -f http-examples/rhino-integration/config/setup-client.commands -e 'load-scenario http-examples/rhino-integration/scenarios/ping.scen'

Run ping session with the command:

run-session ping
Example 7. HTTPS example

Copy the keystore file to rhino home dir:

cp http-examples/rhino-integration/config/http-ra.ks $RHINO_HOME/

Update configuration of the http resource adaptor on the rhino server using rhino console commands:

updateraentityconfigproperties httpra SecureListenPort 8002 KeyStore "${rhino.dir.home}/http-ra.ks" KeyStorePassword changeit
deactivateraentity httpra
activateraentity httpra

Start scenario-simulator session with the command:

./scenario-simulator.sh -l client.log -f http-examples/rhino-integration/config/setup-client-tls.commands -e 'load-scenario http-examples/rhino-integration/scenarios/pingSecure.scen'