 SOAP Reference A reference guide to SOAP 1.1 / 1.2 Server and Clients |
| Index > Books > Declarative Development Guide > Reference Library > SOAP Reference |
Rate this page:  |   IntroductionThe 1060 NetKernel SOAP Kit provides a generic SOAP server and client both of which have specific HTTP bindings. Also provided are a number of utility accessors for processing SOAP messages. The SOAP kit's emphasis is on doc/lit based SOAP services which are a natural fit with NetKernel's declarative XML processing environment. All of the SOAP Accessors are SOAP v1.1 and v1.2 compatible - this includes the HTTP client and server bindings as well as the utility accessors. ArchitectureThe SOAP Kit consists of a set of independent NetKernel accessors which may be combined to provide SOAP clients and SOAP services. The architectural relationship between the accessors 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
The fundamental design principle of the SOAP Kit is to provide inbound and outbound mapping from SOAP specific transport bindings to a service implementation hosted as a generic NetKernel service. Since many of SOAP's higher-level application sets are immature, and indeed, even the foundations of SOAP 1.1 versus SOAP 1.2 are in flux, the architecture is designed to accommodate future WS layers as application stacks implemented as NetKernel processes. Since NetKernel is intrinsically service-oriented and transport-independent the translation to and from SOAP is relatively straightforward. SOAP ServerA 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 Server BindingHTTP 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. wsSOAPServerThe wsSOAPServer accessor is transport independent and implements the mapper pattern - it receives a request with a SOAP message and associated endpoint and action URIs as arguments - using the endpoint and action it resolves the internal URI of the NetKernel service which implements the service that processes the SOAP message. It issues the message, endpoint and action arguments to the implementing internal service and returns the processed result to the original requestor. The wsSOAPServer requires a SOAPServiceMap config document which holds the SOAP service and port specification. The service map is also used as the basis for the wsdlGenerator accessor which dynamically generates WSDL description documents. Service ImplementationThe 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. In order to assist with the specifics of SOAP message processing a number of declarative utility accessors are provided:
ArgumentsIn general an implementing NetKernel service will receive three arguments.
A process implemented using the dpml runtime can access an argument using the this:param:xxx uri, for example the message argument has uri 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. FaultsA service implementation is responsible for processing header and body parts according to it's application specific needs. Where appropriate it should implement the necessary processing in order to comply with SOAP specifications (SOAP 1.1 or SOAP 1.2). For example, if it encounters an inconsistent message part, like a mustUnderstand header which is not understood, it should generate and return the appropriate SOAP Fault. Intermediary ServiceIf a service is acting as an intermediary it may, after performing it's function, relay the message to another service using the SOAP client infrastructure. A service implementation is responsible for knowing which actor/role it currently has. WSDL GenerationThe wsdlGenerator can be used to dynamically generate a WSDL description for a service endpoint. It uses information from the SOAPServiceMap to generate the WSDL document - if necessary the schema or the entire WSDL description can be overridden (see wsdlGenerator doc). The HTTPBridge will direct SOAP mode requests for URLs with a ?WSDL query to the wsdlGenerator service. wsDocumentationWSDL is a machine readable formal description of a SOAP service. Whilst this is concise it is frequently useful to provide a human readable description of a service. The HTTPBridge will direct SOAP mode requests for URLs with a ?DOC query to the wsDocumentation service. This implements the mapper pattern and uses the SOAP service map config file and endpoint URI to locate and issue a request to the internal URI which provides the documentation for the service. The ws_test module provides examples of a service with static HTML documentation and a service which uses the NetKernel docxter engine to dynamically generate HTML documentation. SOAP ClientThe NetKernel wsSOAPClient is a transport independent SOAP client. It locates a specific SOAP transport binding client based upon the URI of the endpoint of the SOAP service. By default an HTTP SOAP client binding is provided. The SOAP client can be used in any NetKernel process to interact with remote SOAP services. It is the responsibility of the process to generate the client request SOAP message with appropriate header and body parts for the given SOAP service. The message is then issued to the service using the wsSOAPClient accessor. It is very simple to issue doc/lit messages and also relatively straightforward to act as an RPC client by creating a message body which conforms to the SOAP RPC encoding rules. SOAP with AttachmentsSOAP with attachments is currently an unstandardized extension to SOAP and a likely cause of incompatiblity between different SOAP servers (see Steve Loughran's Fear of Attachments). Until there is more stability we have chosen not to support proprietary SOAP attachments. For now there are two choices for a future-proof and compatible way to exchange
binary data. The first is to Base-64 encode your binary content and add it as the text of an element in the body part of the SOAP message - a base-64 encoding/decoding utility
is provided in the ext_layer1 module, References
 |
Preface
Technology Tour
Reference Library
