Providing SOAP Web Services

Each SOAP web service is defined via a <Services/> node within the webservice configuration. Its attributes and child elements vary depending on the web service type.

The following SOAP web service types are available within the <Wsdl> child element's attribute mode:

RPC: The X4 Server generates a WSDL definition from the configuration data according to the RPC style, see Providing SOAP Web Services in RPC-Style
DOCUMENT: The X4 Server generates a WSDL definition from the configuration data according to the Document style, see Providing SOAP Web Services in Document Mode
EXTERNAL: Use external WSDL definition for the SOAP web service, see Providing SOAP Web Services with External WSDL Definition
NONE: No WSDL definition will be used/provided, see Providing SOAP Web Services without WSDL Definition
PROCESS: Select a process which creates the WSDL and returns it to the caller as HTTP content. The process result is thereby returned in its original form.

Schematic structure of a SOAP web service configuration (XML storage format)

XML

<Service type="Soap">
  <SoapVersion>
    <SOAP11/> <!-- for SOAP 1.1 support -->
    <SOAP12/> <!-- for SOAP 1.2 support -->
  </SoapVersion>
  <Wsdl mode="WSDL mode"/>
  <Namespace prefix="" namespace="" schemaLocation="URL to an XSD document"/>
  <Operation name="Operation name" process="Path to the X4 process as x4db:/ URL">
    <InputHandler type="Input mode"/>
    <OutputHandler type="Output mode"/>
    <Input>
      <Part name="Part name" type="Type (optional)" element="Element name (optional)" />
    </Input>
    <Output>
      <Part name="Part name" type="Type (optional)" element="Element name (optional)" />
    </Output>
  </Operation>
</Service>

Explanations:

The node<Services type="Soap"> defines an HTTP web service of the type SOAP.
The node <Wsdl> defines with its attribute mode the desired WSDL mode (e.g. EXTERNAL, see above).
The nodes <SOAP11/> and <SOAP12/> allow to define the SOAP versions used by the web service nutzt (either one or both parallel).
In any number of <Namespace> nodes a namespace for the definition of web services can be used.
In any number of <Operation> nodes an operation for the web service can be defined (see above).

The following namespaces are defined by the system:

xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap11="http://schemas.xmlsoap.org/wsdl/soap/ "
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/ "
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

Request Routing for SOAP Services

GET Requests: In WSDL mode NONE, a GET request is responded with the HTTP status 405 (method not allowed). In WSDL mode EXTERNAL, the response to the configured WSDL URL is an HTTP redirect. In case of the WSDL modes RPC and DOCUMENT, the X4 Server generates a WSDL from the service configuration as response.
POST Requests: In case of a POST request the complete request body is loaded to the memory, in order to initiate the routing on the operation.
1. First, it is looked for the SOAP document.
  - If it is not a multipart request, it is assumed that the request body contains the SOAP document.
  - If it is a multipart request (MTOM), it is looked for the MTOM package's start part.
2. The document found is read as XML and the SOAP version from the root element's namespace is determined. If it is not an accepted SOAP versions, it will be replied with an appropriate SOAP fault.
3. The Namespace and the Localname of the SOAP body's first child element is figured out from the XML document, and used to determine the operation within the service.
  - In case of the WSDL modes NONE, RPC and EXTERNAL, it is compared with the configured Namespace and Localname of the operation.
  - For the WSDL mode DOCUMENT the configuration of the first Input part is used. If it is an Element part (i.e. the attribute element contains a value) the Qualifiedname of the configured element is used. For Type parts (i.e. the attribute type contains a value) the part's name (attribute name) is used.
4. Then, the request ist prepared according to the input mode and passed to the configured process for the operation.
  
  SOAP requests with an empty Body element can't be processed.