|WHITE MESA SOFTWARE|
|Home Download Links Documentation|
A Windows NT Service for providing SOAP Services
SummaryThe White Mesa SOAP Services implementation consists of:
The White Mesa SOAP server functions as an multithreaded HTTP server capable of handling HTTP GET requests for document retrieval as well as SOAP service requests. As a SOAP server it accepts SOAP 1.1 or 1.2 requests. These can be originated by any client application, stand alone or browser based. The processing of the request message results in a SOAP response message returned to the client as the entity body of the HTTP response. A WSDL (Web Services Description Language) document is referenced by the server to obtain information about the SOAP service requested, such as SOAP Version or RPC parameter data typing.
SOAP version: The behavior of client libraries and the Server is determined by the choice of SOAP binding used for a service endpoint (port). This is specified in the WSDL document which describes the service. If a SOAP 1.1 binding is specified for a port, then SOAP version 1.1 will be used, and so on.
In support of SOAP RPC style services, any number of COM servers may be exposed as SOAP services, mapped to different request URI's. Likewise, Document style services are supported by mapping COM based service providers to request URI's. These mappings are maintained through the control panel applications, which make it easy to set up and maintain service configurations.
Common Log Format, User Agent, and SOAP message trace logging facilities are available. These can be turned on/off and filenames set in the control panel applications. An time periodic log rotation feature is available if desired. The rotation interval is specified in the configuration file, adjustable over a range of 1 to 1193 hours (49 days).
An installation program is furnished which installs the server and other applications properly. The control panel apps and other demonstration services are ready to run immediately. (See the Important Notes Page for details)
The White Mesa SOAP Server is available under the terms of this License.
RPC Style Services
Any COM Automation server may be exposed as a SOAP RPC style service. Although any SOAP client may be used, the following describes a service call made by the C++ RPC client supplied in the White Mesa SOAP Service package.
The C++ client instantiates a SOAP Client object which manages the process of marshalling what looks like a IDispatch:Invoke call as a SOAP RPC request to the server. The SOAP Client obtains necessary information such as service URL, SOAP version, etc. by examining the WSDL document containing the description of the SOAP service desired. This is accomplished by calling into a WSDL Client object which encapsulates the functionality required for obtaining and parsing the WSDL document. The client then connects to the server and transmits an HTTP POST request, the entity body or payload of which is the SOAP request envelope representing the method invocation. This consists of the method name and the values of any "in" or "in/out" parameters. The message may contain SOAP Header blocks as well.
The SOAP server instantiates an Processor object which handles the request. It parses the SOAP request message. Any Header blocks are then processed by instantiating the appropriate COM server(s) and passing in an interface pointer to the wmsoapmsg2 object encapsulating the parsed SOAP message. The Header processor COM server may fetch Header blocks for processing, pass back Header blocks for insertion in the response message, or generate a SOAP Fault message if Header processing fails. Next, to process the method call, the proper COM server (specified in the service configuration) is instantiated and the method call made. Next, the Header processors are invoked a second time to allow any further processing. The SOAP response message is then constructed and returned to the client. This message is a representation of the return value and the values of any "in/out" or "out" parameters. Type information needed for serialization/deserialization of SOAP RPC messages is found by the server in the WSDL document associated with the service. The client, upon receipt of the response message, decodes and unmarshalls any return value or parameters for the use of the caller.
SOAP 1.2 RPC operations which simply perform a data retrieval action may be invoked using an HTTP GET request, in accordance with the SOAP 1.2 "Web Method" feature. In this case the method must have no input parameters, as there is no input SOAP message to convey them. The White Mesa SOAP server expects the following convention to be followed for SOAP 1.2 RPC services invoked using HTTP GET: The URL used to invoke the RPC is composed by appending the method name to the URL of the base SOAP service. For instance, to invoke method "getTime" on a service defined with request URI "/clock/*" the request message should be sent to URL "http://example.org/clock/getTime" if the service is located on host "example.org". In this manner any number of methods can be exposed by a service endpoint for HTTP GET invocations. The Automation server supporting the service would be called in the usual way as described above, with the exception that the Header processors are invoked only after the method is called, as the request contains no SOAP message, and thus no request message Header blocks need to be processed. Methods invoked using GET must of course have no [in] or [in,out] parameters, but they may have a return value, [out] parameters, or both.
Both "SOAP encoded" and "literal" RPC data serialization rules are supported. Some explanation is warranted here. SOAP RPC messages are constructed in accordance with conventions which are set forth in the SOAP 1.1 and 1.2 specifications. These conventions may be used in conjunction with either a "literal" or "encoded" serialization of parameter data values. The "literal" usage means that the parameter data items are represented in the message as XML instances which conform literally to XML schema definitions found in the WSDL decription for the service. The "encoded" usage means that the parameter data instances found in the message are the output of an encoding scheme which converts common programming language data types into XML representations. Both SOAP 1.1 and 1.2 define an encoding scheme for this purpose (among others). These SOAP encodings prescribe rules for serializing arrays, for instance, and offer a mechanism for passing parameters by reference. The behavior of the White Mesa client libraries and the Server in this respect is controlled by settings in the WSDL document describing the service. Either "literal" or "encoded" usage may be specified. If "encoded", only the standard SOAP 1.1 and 1.2 encodings are allowed. The serialization/deserialization of RPC messages is automatically managed in a manner transparent to the application objects that are parties to the RPC invocation. The service descriptions for "literal" and "encoded" RPC operations differ in several important respects, and it is the responsibility of the application designer to understand the relevant WSDL 1.1 rules. The White Mesa SOAP implementation follows the WS-I Basic Profile v1.0 guidelines for SOAP rpc/literal applications.
Document Style Services - SOAP 1.1
A Document style service is provided by a COM Automation server implementing a Dispatch interface with the following method:
Any SOAP 1.1 client may be used. The client connects to the server and transmits an HTTP POST request, the entity body or payload of which is the SOAP 1.1 request message. This contains the XML document(s) which represents the service request, encapsulated within the SOAP Body element. The SOAP message may contain SOAP Header blocks as well.
The SOAP server instantiates an Processor object which handles the request. It parses the SOAP request message. Any Header blocks are then processed by instantiating the appropriate COM server(s) and passing in an interface pointer to the wmsoapmsg2 object encapsulating the parsed SOAP message. The Header processor COM server may fetch Header blocks for processing, pass back Header blocks for insertion in the response message, or generate a SOAP Fault message if Header processing fails. Next, to process the SOAP Body element contents, the proper COM server (specified in the service configuration) is instantiated and the "OnProcessBody" method call made. A Dispatch interface pointer is passed in to the Body processor which is used to access the Iwmsoapmsg2 interface. This interface is used to interact with the COM object which encapsulates the parsed SOAP message during processing. The Body processor (service provider) uses this interface to obtain the XML document representing the request. This is presented in literal XML form and the processor is responsible for parsing it and acting upon the contents. By means of the same interface the processor may also pass in the literal XML that will form the Body of the response message returned to the client. Next, the Header processors are invoked a second time to allow any further processing. The SOAP response message is then constructed and returned to the client.
Document Style Services - SOAP 1.2
A Document style service is provided by a COM Automation server implementing a Dispatch interface with one or both of the following methods:
Any SOAP 1.2 client may be used.
In the case of an invocation using HTTP POST, the client connects to the server and transmits a request, the entity body or payload of which is the SOAP 1.2 request message. This contains the XML document(s) which represents the service request, encapsulated within the SOAP Body element. The SOAP message may contain SOAP Header blocks as well.
The SOAP server instantiates an Processor object which handles the request. It parses the SOAP request message. Any Header blocks are then processed by instantiating the appropriate COM server(s) and passing in an interface pointer to the wmsoapmsg object encapsulating the parsed SOAP message. The Header processor COM server may fetch Header blocks for processing, pass back Header blocks for insertion in the response message, or generate a SOAP Fault message if Header processing fails. Next, to process the SOAP Body element contents, the proper COM server (specified in the service configuration) is instantiated and the "OnProcessSoapPost" method call made. A Dispatch interface pointer is passed in to the Body processor which is used to access the Iwmsoapmsg2 interface. If desired, the service endpoint may be configured so that "extra path" information may be appended to the base endpoint request URI by the client, to be passed in to the processor. For instance, if a SOAP 1.2 service on host "example.org" is configured with endpoint URI "/maps/*" (note asterisk), and it was invoked with the URL "http://example.org/maps/France/Paris", then the "extra" path components "/France/Paris" would be passed in to the Body processor. In this way a base service URI can be defined which can be invoked using URLs which refer to any number of subordinate resources. This Iwmsoapmsg2 interface pointer is used to interact with the COM object which encapsulates the parsed SOAP message during processing. The Body processor (service provider) uses this interface to obtain the XML document representing the request. This is presented in literal form and the processor is responsible for parsing it and acting upon the contents. By means of the same interface the processor may also pass in the literal XML that will form the Body of the response message returned to the client. Next, the Header processors are invoked a second time to allow any further processing. The SOAP response message is then constructed and returned to the client.
In the case of an invocation using HTTP GET, a request message without a SOAP message is sent to the server. If desired, the service endpoint may be configured so that "extra path" information and/or a query string may be appended to the base endpoint request URI by the client, to be passed in to the processor. The manner in which this is done is the same as described above for HTTP POST, and allows request URIs to refer to subordinate resources or specify query parameters. For instance, for a service on host "example.org" configured with endpoint URI "/maps/*" (note asterisk) the client might send a request to a URL of the form "http://example.org/maps/usa/chicago", or perhaps"http://example.org/maps?country=usa&city=chicago". Both "extra" path information and query strings are passed in as arguments to the "OnProcessSoapGet" method call on the COM server instantiated to handle the message Body. As the request contains no SOAP message, the Body processor needs only use the Iwmsoapmsg2 interface pointer to pass in the literal XML that will form the Body of the response message returned to the client. Any Header processors registered for the service are invoked only after Body processing has taken place, so that Header blocks may be inserted into the Response message.
SOAP Extensions (Header Blocks)
As mentioned above, a mechanism is provided to support the processing of SOAP Header blocks in both the client and server side implementations. The mustUnderstand (1.1, 1.2), actor (1.1), role (1.2), and relay (1.2) attributes are recognized and obeyed. Each service's configuration may specify one or more Header processors to be called during message processing. The Header processor instances called during the request phase are kept around and called during the response phase so that state may be maintained. COM servers used as Header processors must implement a Dispatch interface with the following methods:
OnTestMUHeaderBlock() is used to determine whether any of the Header processors registered for a service endpoint support a particular Header block. It is only called by the SOAP processor when it encounters a Header block in a message with "mustUnderstand" set to "true" that is targeted at a role supported by the endpoint. If so, before any processing begins, the Header processors are queried to determine whether or not the Header block is "understood", based on its Qualified Name. If a Header processor returns VARIANT_TRUE when called, the SOAP processor assumes that the Header block will be understood and processed. If no Header processor responds in the affirmative, then the SOAP processor will abort processing and return a SOAP "MustUnderstand" Fault message to the sender.
OnProcessHeader() is called by the SOAP processor twice (once in the request phase, again in the response phase) for each COM component specified as a Header processor for a given service. A Dispatch interface pointer is passed in to the Header processor which is used to access the Iwmsoapmsg2interface. This interface is used to interact with the COM object which encapsulates the parsed SOAP message during processing. Rather than the Header blocks being "pushed" to the Header processor, in this model the Header processor "pulls" any Header block elements it is interested in. Within the scope of a single standard call, the Header processors may query the message object for any Header blocks they are interested in, in whatever order they wish to. This approach was attractive for complex processing scenarios, and also allows the Header processors to manipulate certain properties of the message, most importantly the Next Hop URL. Header block targeting is accomplished by means of the SOAP actor (1.1) or role (1.2) URI attribute. Each service configuration includes the specification of one or more actor URIs with which it is identified. Only Header blocks targeted at those particular actor URIs are "consumed" when accessed by the service's Header processors. Once Header processing is complete, the SOAP processor checks to make sure that all Header blocks with a 'mustUnderstand' attribute set to "true" and targeted at the service's actor or role URIs have been processed. If any have not, a SOAP fault results. More on Header block processing here...
A service may be operated either as an ultimate receiver in which case the Body is processed locally, or as an SOAP intermediary. An intermediary forwards the SOAP request to another SOAP node (usually a SOAP processor at a different IP address) for processing. Each service configuration specifies a Next Hop URL which controls the default behavior of the service. If empty, the service acts as an ultimate receiver. If not empty, the Next Hop URL is used to forward the request onward after the usual Header processing has occurred. A more dynamic form of routing is possible since any Header processor may alter the Next Hop URL value "on the fly", overriding the configured default URL. This is accomplished by a call to the Iwmsoapmsg2 interface mentioned above. This provides enough flexibility for the creation of interesting hop by hop message path models. A particular server instance (or node, listening on a distinct IP address) may expose many different services (mapped to distinct request URIs), whose individual configurations determine whether they behave as ultimate receivers or intermediaries. More on intermediary support here...
The White Mesa SOAP implementation relies on the use of WSDL (Web Services Description Language) to describe SOAP services. The built-in WSDL processor supports documents compliant with WSDL Version 1.1. The WSDL processor can access documents from the local filesystem or via HTTP. The SOAP binding extensions specified in WSDL are supported, and limited support for XML schema processing is present for processing schemas contained in WSDL documents. The WSDL import mechanism is supported, with location URLs limited to the "file:" and "http:" schemes. Once loaded by the White Mesa SOAP server, parsed WSDL documents are cached to improve performance. Cache size is configurable, and a simple LRU algorithm is used to drop entries when cache size is exceeded. The C++ client only loads and stores one WSDL document at a time.
SOAP request messages may be packaged using the WS-Attachments draft spec. If so, the server will detect and properly process such messages, recovering any data items which have been sent as DIME attachments referenced from within the SOAP message. Likewise, support is provided so that applications may send response messages which are DIME packaged. There is no symmetry requirement, that is, a normal SOAP request message may result in a DIME packaged response, and vice versa. DIME packaged SOAP messages are also fully supported when the server is operating as an intermediary. More on DIME support here...
SOAP 1.2 Web Method Feature
The White Mesa SOAP Server allows the use of both HTTP GET and POST methods to be used when sending a request message.
HTTP GET is appropriate when the object of the request is data retrieval, and the request URI is sufficient to identify the resource desired. The response returned by the service handler will be a SOAP 1.2 message, which may be DIME packaged if desired.
HTTP POST is appropriate when the object of the request is to convey data for storage or some other modification of the state of the resource identified by the request URI.
When acting as an intermediary, the White Mesa SOAP Server relays SOAP 1.2 requests using HTTP GET as well as those using POST.
The White Mesa client-side libraries fully support making SOAP 1.2 service request using either HTTP GET or POST. Again, this applies to DIME packaged request messages as well.
Whether or not SOAP 1.2 service endpoints allow the use of "extra" path information in request URIs is controlled by the declaration of the endpoint URI in the service configuration, using a "wildcard" notation. For instance an endpoint at host "example.org" configured with URI "/foo/*" (note asterisk) will be the target of any SOAP 1.2 request message sent to URLs beginning with "http://example.com/foo", with the balance of the request URI passed in as "extra" path information. So a message sent to "http://example.com/foo/maps/usa/chicago" would be dispatched to that service, with "extra" path components "/usa/chicago" passed in to the Body processor. If the endpoint URI is declared as simply "/foo" then only SOAP request messages sent to URL "http://example.org/foo" will be dispatched to the service, so a request sent to "http://example.com/foo/maps/usa/chicago" would result in an HTTP 404 Not Found response.
The parser can handle input in US-ASCII, UTF-8, and UTF-16 encodings (both little and big endian). WSDL files presented to the client and server may be in any of the above formats. Although both the client and the server can parse a received SOAP message in any of these formats, they currently transmit messages only in UTF-8 encoding. So if the supplied C++ client code is used in conjunction with the SOAP server, the resulting SOAP message envelopes will consist of XML encoded in UTF-8 format. Unicode data (as BSTR's) presented to the client side Automation Proxy or the server side Automation Stub objects will be properly converted to UTF-8 for transmission and back to Unicode again at the receiving end.
SOAP Data Encoding
The White Mesa SOAP Server and C++ client provide automatic encoding/decoding of SOAP RPC message bodies per the SOAP encoding rules. SOAP Header blocks using SOAP encoding are also automatically decoded, and it is possible to insert SOAP encoded Header blocks into messages as well. Decoding is controlled by SOAP-ENV:encodingStyle attributes found in SOAP messages, per the rules given in the spec for the SOAP version being used.
The SOAP encoding rules prescribe a method of encoding native data types into XML accessor elements using the XML Schema type system. In the White Mesa implementation, the native data types are those of the Automation type system (VARIANTS). A subset of the XML Schema simple data types are mapped onto the appropriate VARTYPE's in the implementation. Arrays are stored in VARIANT parameters as SAFEARRAYs of type VARIANT for marshalling into COM interfaces. Structs are encapsulated in a wmsoapstruct object, whose IDispatch pointer is stored in a VARIANT parameter as well. The xsd:base64Binary and xsd:hexBinary types are stored in VARIANT parameters as SAFEARRAYs of type UI1 (byte array). The xsd:date, xsd:time, and xsd:dateTime types are mapped to the DATE Automation type. The xsd:decimal type is mapped to the DECIMAL Automation type.
RPC Parameter Data Types
HTTP GET Facility
The SOAP server also services non-SOAP HTTP GET requests, so that it can furnish WSDL documents and other resources to clients on demand. This service is administered by the "control panel" applications mentioned above that allow remote configuration of the SOAP server (via SOAP RPC, of course).
Server Remote Control Panels
Two functionally equivalent sample "remote control panel" client apps are provided. The first is a standalone C++ app, the second a browser based DHTML app. These control a running server instance (local or on a remote host), by invoking a special SOAP RPC administrative service supported by the White Mesa SOAP server. As a security measure, a Digest Authentication scheme (similar to that in RFC 2617, based on username/password pairs) is employed to assure mutual authentication of client and server.The authentication information flows between client and server in the form of Header block elements and fault messages. At the server, Header blocks are processed by a dedicated Digest Authentication server (wmsoapauthsvc.exe), which is configured as a Header processor for the administrative service used by the control panel apps. This service is described in the WSDL document wmsoapsvrcp.wsdl. Username/password pairs may only be set locally (see Important Notes Page for details). A wide range of server configuration and SOAP service maintenance tasks are accomplished using the control panel applications. The MFC version looks like this:
Can be learned by looking at the source.
Platform and Compiler
Win32, native (unmanaged) C++ application. The client and server use Winsock2. The server manages client connections using I/O completion ports. Compiled using Visual C++ 7.0 and tested on Win2000 and WinXP. Makes heavy use of the Standard C++ template based container classes and exception handling features. The parser relies on Microsoft library routines for string handling and conversion. The standalone remote control panel for the SOAP service is an MFC app. The browser based control panel app requires IE 5.0 or higher.
Send questions, comments, etc. to:
|Home Download Links Documentation|
Copyright © 2003 by Robert Cunnings. firstname.lastname@example.org Last modified: June 29, 2003