SOAP is a protocol for message exchange in which the message is XML-based and the transport is usually HTTP. A SOAP message consists of an envelope containing one or more header parts and a body part. A SOAP Web Service is a process which can deal with the formal structure of a SOAP message. A SOAP service is bound to a transport in order to receive messages and send responses. While the SOAP standard permits other transport bindings, HTTP is used almost exclusively in practice.

NetKernel transports, messages and address spaces are completely distinct making it straight forward to provide support for SOAP messaging. NetKernel support for SOAP is offered as a service and a special mode within the HTTP Bridge service.

NetKernel supports both SOAP v 1.1 and v 1.2 in all client and server tools.

Architecture

SOAP support is provided by a set of independent services which may be combined to create SOAP clients and SOAP services. The architectural relationship between the services is shown below:

Server-	    HTTPTransport
side          |
              v
	    HTTPBridge <------> wsDocumentation
	      |	   ^	                    ^
	      |	   |                        |
	      |    |                        |
	      |    ------> wsWSDLGenerator  |
	      |                   ^         |
	      | service req       |         |
	      |                   |         |
	      v                   |         |
Services    wsSOAPServer <----- SOAPServiceMap.xml
	      ^
	      |
_____________________________________________________________________
      	      |	    Modular NetKernel XML Service Implementations
	      |
SOAP	      v
Message	    Header/Body Processing <----> wsSOAPxxxx Accessors
Processing    |			   <----> Enterprise Systems
	      |				  [WS-* Application Stacks]
	      v
_____________________________________________________________________
	      | relay message
	      |
	      v
Client-	    wsSOAPClient  <--- ConfigSOAPClientBindings.xml
side	      |
	      v
	    wsSOAPHTTPClient
	      |
	      | service req
	      v
	    External SOAP Service        
      

This diagram shows that the SOAPServiceMap.xml configuration resource provides information for the wsSOAPServer wsdlGenerator, and wsDocumentation services.

There is complete separation of concern in NetKernel's SOAP support. One set of service is responsible for routing SOAP messages and other set is focused on message processing (such as message creation or extraction and fault detection).

In general a NetKernel service processing SOAP messages will receive three arguments.

parameter	description
message	The SOAP message to be processed
endpoint	URI of the SOAP endpoint
action	URI of the SOAP action

A service implemented using the DPML language can access an argument using the this:param:xxx URI. For example, the message argument has the URI this:param:message. It can also be valuable to use the toURI service to obtain the endpoint and action URIs as canonical URI documents. (Note: if the message argument is not present then the implementing service can assume that the request is SOAP 1.2 using the GET binding.)

A SOAP service on NetKernel is simply a NetKernel XML-service which processes SOAP message xml documents. The SOAP kit provides transport specific bindings and a generic SOAP server accessor which together map from the external SOAP interface to the internal implementing NetKernel service.

HTTP SOAP transport binding is provided as a special mode of the HTTPBridge accessor. The HTTP Bridge should be configured with a zone in SOAP mode. URL requests which match the zone will be processed according to the rules of the SOAP 1.1 or 1.2 HTTP transport bindings (see HTTPBridge document for details). The HTTP bridge will issue an internal request for service:wsSOAPServer... with the SOAP message together with the endpoint and action URIs as arguments.

Generally a module which hosts a SOAP service will export service:wsSOAPServer... and provide a mapping to the wsSOAPServer.

The internal NetKernel service which actually implements the service for a given SOAP endpoint is entirely flexible. NetKernel's SOAP server-side infrastructure is concerned with routing the SOAP message to the internal service which processes it - it does not perform any processing to either SOAP headers or body and delegates message processing up to the application-level service implementation.

A service implementation has total freedom over how it chooses to process the SOAP message - for example, it could implement business logic with custom accessors or use standard XML technologies from the NetKernel XML application server infrastructure.

Configuration

The SOAPServiceMap.xml configuration resource contains the information needed to map an external SOAP endpoint and port (also called a SOAP action) to a NetKernel service which processes SOAP messages. It also contains the information needed by the wsDocumentation service to generate documentation and the wsWSDLGenerator to generate WSDL meta information about the SOAP service.

This document defines services and ports:

element	description
service	Service name and endpoint URI
port	Information for a given service port

Any number of services may be specified and each service may have any number o fports. each port must have a unique endpoint/action combination.

A service is specified with the following fields:

element	description
name	Name of the service
endpoint	URI matching the service endpoint
wsdl	An optional URI referencing the wsdl definition of the service. If a value is not specified then an auto-generated definition will be provided.

A port is specified with the following fields:

element	description
name	Name of the port
type	Either doc or rpc. Currently only doc is supported.
endpoint	URI matching the service endpoint
action	SOAP action URI
int	The internal URI to which SOAP service requests on this port are passed.
doc	The internal URI where human readable documentation is located. This is provided by the wsDocumentation service.
messageIn	A container for a mandatory element field which provides the name of the root element of the incoming message. An optional schema field may be used to specify the URI to a custom schema for the message.
messageOut	A container for a mandatory element field which provides the name of the root element of the outgoing message. An optional schema field may be used to specify the URI to a customer schema for the message.