Introduction

This trailmap walks through the implementation of SOAP services and shows how NetKernel can be used to host SOAP services or equally can be a client to remote services. The guide deconstructs a set of example SAOP services and associated clients. If you prefer a basic step-by-step approach, a HowTo guide is published here which shows how to develop SOAP services in a few follow-along steps.

The [install]/modules/test-ws.x.x.jar module contains a number of demonstration SOAP services. One of the demos is a number guessing game in which a game service chooses two random numbers between 1 and 100 which the player/client must guess in the least number of turns.

Whilst this game is simple, it demonstrates an important pattern of a stateful conversation implemented with SOAP services. It also demonstrates SOAP services with backend database integration - a pattern typical in service-oriented-architectures.

We will refer to the test-ws.x.x.jar module and recommend that you unzip it so that you can examine the module configuration and source code of the services and clients. The source to the game's client and server is located in the hilo/ directory.

We also recommend you refer to the reference guide for the NetKernel SOAP infrastructure located here.

The Game

As a demo we have created an auto-player client which uses an optimal algorithm to play the game - it produces a PNG image of it's result (below)

You can try the auto-player against the live service here. If you examine the standard-out you will see each turn is logged.

The auto-player client uses an HTTP SOAP client to repeatedly invoke the game's SOAP services which are hosted on the same NetKernel host - this is for demonstration purposes and is not generally a recommended pattern though it can be valuable for co-hosted test harnesses.

The game's workflow, using the auto-player client, is shown below. The client first sends a SOAP message to initiate a new game with the game server which returns a game id. The client then takes turns trying to guess the numbers. With each turn it issues a SOAP message containing the game id and two guesses and receives a reply indicating if the guesses are too low/high or correct.

You can examine the game's SOAP service documentation here.

Deconstructing the Service

In order to understand how a SOAP service is hosted on NetKernel we will first start with the service implementation, in this case the main game service. Later we will look at the module configuration to show how this internal NetKernel SOAP service is bound to a transport.

Take a look at the source code to the main game service - hilo/server/gameService.idoc. The first instruction is:

We don't need to concern ourselves with the specifics of the DPML process, instead we'll list some of the important parts which are relevant to SOAP message processing.

• Arguments - a SOAP message is routed to an internal NetKernel process by the NetKernel Soap infrastructure, we'll show how later. In general the implementing process will receive three arguments, the message, the endpoint URI and the action URI. In DPML the message argument can be obtained with the URI this:param:message
• The implementing process can manipulate the message in any way it likes. In this case the first instruction extracts the turn part from the message body and then uses it to create an SQL query using an XSLT transform.
• After querying the database and determining whether the guesses are correct, the process constructs a new SOAP message for the response. It inserts a response into the body of the new message and issues the whole message to the this:response of the DPML process.
• Exceptions - This example does not catch exceptions. Should an exception occur, it will percolate back up the NetKernel service request stack until it reaches the transport binding which initiated the internal service - this automatically captures NetKernel exceptions and issues a SOAP Fault message to the requesting client. Of course, if necessary a service may create an application-level SOAP fault message and issue this as it's response.

As you will have understood - a SOAP service implementation on NetKernel is nothing special, the only specifics are that it receives and should issue a SOAP message. But the implementation is just generic XML document processing - with, perhaps, the use of some wsSOAPxxx utility accessors for convenience.

Binding the Service to a Transport

A SOAP service on NetKernel is just like any other NetKernel process - now lets examine how a SOAP endpoint can be exposed on a transport and how messages received by the endpoint are routed to the implementing internal process .

Fulcrum

Transports are initialised in Fulcrum modules. By default, the front-end fulcrum hosts an HTTP transport on port 8080 which issues low-level HTTP requests into the internal address space of the fulcrum. The front-end fulrcum is configured to map all raw HTTP requests to the HTTP Bridge accessor for pre-processing before being reissued into the fulrcrum's address space.

The HTTP Bridge in the front end fulrcum uses a config file HTTPBridgeConfig.xml You can see the front-end modules config at [install]/front-end-fulcrum/module.xml and the HTTP bridge config at [install]/front-end-fulcrum/etc/HTTPBridgeConfig.xml. You will see that the HTTP bridge config has a special zone defined.

All HTTP requests with URLs matching this zone will be processed according to the SOAP 1.1/1.2 HTTP transport binding rules. Essentially the SOAP message is extracted from the HTTP request together with the SOAP action URI. In SOAP terminology the URL of the request is called the endpoint URI. The HTTP bridge will then reissue a request with a URI of the following form.

service:wsSOAPServer +message@[a_message]+endpoint@[an_endpoint] +action@[an_action]

This request should be matched by a module which hosts the SOAP service implementation and which is imported into the fulcrum.

test_ws module

The test_ws module hosts the games services and is imported into the front-end fulcrum by default. If you examine it's configuration module.xml you will see that it exports

which will match all requests for SOAP services with endpoints whose URLs match /soap/test/ - note this match also matches wsdlGenerator and wsDocumentation requests which will originate from the HTTP Bridge when the endpoint URL has ?WSDL or ?DOC query parts.

Don't worry if the detail of the module.xml config looks complex, besides the game the module also hosts a number of other test services and unit tests for the wsSOAPxxxx accessors. After the export, the next most important configuration is the rewrite rule

This appends a SOAPServiceMap config argument to all service:wsSOAPServer requests and moves it from the service: scheme to the active: scheme. Which produces an active URI of the form:

active:wsSOAPServer+message@[a_message] +endpoint@[an_endpoint] +action@[an_action] +config@ffcpl:/SOAPServiceMap.xml

The resulting URI will be matched by the generic mod_ws module, which you can see is imported into the test_ws, and will be handled by the wsSOAPServer accessor. Note, there is no significance in the use of the service: scheme by the HTTP bridge - it is simply a transient scheme used to avoid the possibility of accidentally invoking the wsSOAPServer without first providing a service map config.

wsSOAPServer

Our external SOAP service request has now reached the wsSOAPServer accessor which implements the mapper pattern. It works by looking in the config SOAPServiceMap for a port (internal service) which matches the endpoint and action URIs. From the port definition it determines the URI of the internal service implementation to invoke for the given request.

Finally the wsSOAPServer invokes the internal service implementation URI with the message, endpoint and action arguments, which is the last step in the binding and routing performed by the NetKernel SOAP infrastructure.

Service Descriptions

We noted earlier that requests on a URL endpoint ending with ?WSDL and ?DOC result in service:wsdlGenerator and service:wsDocumentation requests from the HTTP bridge. These follow the same routing as the wsSOAPServer requests but should ultimately be steered to the wsdlGenerator and wsDocumentation accessors. Their documentation explains how these use the SOAPServiceMap configuration to generate or serve descriptions for a given service.

Deconstructing the Client

The client to the game service is very simple - all it does is build a SOAP message and issue it to the service. The wsSOAPClient accessor requires a message, endpoint and action URIs. Based on the URI of the endpoint it automatically locates the correct Binding to use to invoke the service request. You can examine the source to the game client at hilo/client/gameClient.idoc.

You will see that the client is constructed with some trickery to make an unsubtle point - if the value of the x guess is odd it uses a SOAP 1.1 message, if the value is even it uses SOAP 1.2. The point of this is that the wsSOAPClient automatically performs the correct transport binding for the given version. More importantly you will recall that the service implementation is entirely independent of SOAP message version - no special work needs to be done to handle either version - in practice it is being randomly hit with 1.1 and 1.2 messages.

Finally the client tests for faults for each SOAP message it receives back from the SOAP service - if the message has a fault it is transformed into a NetKernel exception and thrown up to the calling requestor, a production service would perform more elaborate application specific error handling.

For completeness you might like to look at the auto-player which is located at hilo/client/gameEngine.idoc - this engine uses the client to make the SOAP requests but is itself entirely abstracted away from the underlying SOAP services. Equally, if the server-side service implementation wasn't designed to provide a simple all-in-one tutorial we would have implemented a similar abstraction for it such that the SOAP message processing would be in one layer which would call up to an abstracted game execution process.

As an exercise you might like to write an interactive client web-application which could take user input form data, make service requests and plot the progress of the game - this would demonstrate the combination of a web-front-end over a backend SOAP service.