Creating Web Services and Web Clients in Caché
Details of the Generated WSDLs
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Search:    

For reference, this appendix shows the parts of a sample WSDL document for a Caché web service, along with information about how keywords and parameters affect these parts. It discusses the following topics:

The signatures of your web methods also affect the WSDL, but this appendix does not discuss the details.
The WSDL is also affected by the XML projections of all XML-enabled classes used by the web service. See the book Projecting Objects to XML.
Note:
If the web service has a compiled policy configuration class, the <binding> section also includes elements of the form <wsp:Policy>. This book does not discuss how policies affect the WSDL, because the effects are determined by the WS-SecurityPolicy and other specifications.
For information on policy configurations, see Securing Caché Web Services.
Caché generates WSDL documents for convenience, but this is not required by the W3C specifications. For important notes on this topic, see Viewing the WSDL,” earlier in this book.
Overview of WSDL Documents
A web service has a WSDL document, a machine-readable interface definition. A WSDL document is written in XML, following the standard for the Web Services Description Language. It defines the contract for how the web service and its clients interact.
A WSDL has a root <definitions> element that contains additional elements that define the following:
The service, any schemas, and the messages are all associated with XML namespaces; these can all be in a single namespace or can be in different namespaces. Note that Caché support for SOAP does not support all possible variations. See the section Standards Supported by Caché,” earlier in this book.
Sample Web Service
This appendix shows parts of the WSDL of the following sample web service:
Class WSDLSamples.BasicWS Extends %SOAP.WebService
{

Parameter SERVICENAME = "MyServiceName";

Parameter NAMESPACE = "http://www.mynamespace.org";

Parameter USECLASSNAMESPACES = 1;

///  adds two complex numbers
Method Add(a As ComplexNumber, b As ComplexNumber) As ComplexNumber [ WebMethod ]
{
    Set sum = ##class(ComplexNumber).%New()
    Set sum.Real = a.Real + b.Real
    Set sum.Imaginary = a.Imaginary + b.Imaginary

    Quit sum
}
}
This web service refers to the following class:
///  A complex number
Class WSDLSamples.ComplexNumber Extends (%RegisteredObject, %XML.Adaptor)
{

/// real part of the complex number
Property Real As %Float;

/// imaginary part of the complex number
Property Imaginary As %Float;

}
Except where noted, the appendix shows parts of the WSDL for this web service. (In some cases, the appendix uses variations of this web service.)
Namespace Declarations
Before we examine the rest of the WSDL in detail, it is useful to see the namespace declarations used by the rest of the WSDL. The <definitions> element contains one namespace declaration for each namespace used in the WSDL. For the sample web service shown earlier in this appendix, these declarations are as follows:
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
xmlns:s="http://www.w3.org/2001/XMLSchema" 
xmlns:s0="http://www.mynamespace.org" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
targetNamespace="http://www.mynamespace.org">
The following parameters affect the namespace declarations:
Also, other namespaces (such as http://schemas.xmlsoap.org/wsdl/soap/) are included automatically as appropriate.
The namespace prefixes are all chosen automatically and cannot be customized.
<service>
When you examine a WSDL, it is useful to read it from the end to the beginning.
The final element within a WSDL is the <service> element, which defines the web service. For the sample web service shown earlier in this appendix, this element is as follows:
<service name="MyServiceName">
    <port name="MyServiceNameSoap" binding="s0:MyServiceNameSoap">
        <soap:address location="http://localhost:57772/csp/gsop/WSDLSamples.BasicWS.cls"/>
    </port>
</service>
This element is specified as follows:
<binding>
Before the <service> element, the WSDL contains <binding> elements, each of which defines message format and protocol details for operations and messages defined by a particular <portType> element.
In general, a WSDL can contain multiple <binding> elements, but the WSDL for a Caché web service contains only one.
For the sample web service shown earlier in this appendix, this element is as follows:
<binding name="MyServiceNameSoap" type="s0:MyServiceNameSoap">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" 
                  style="document"/>
    <operation name="Add">
        <soap:operation soapAction="http://www.mynamespace.org/WSDLSamples.BasicWS.Add" 
                        style="document"/>
        <input>
            <soap:body use="literal"/>
        </input>
        <output>
            <soap:body use="literal"/>
        </output>
    </operation>
</binding>
This element is specified as follows:
Note:
If the web service has a compiled policy configuration class, the <binding> section also includes elements of the form <wsp:Policy>. This book does not discuss how policies affect the WSDL, because the effects are determined by the WS-SecurityPolicy and other specifications.
For information on policy configurations, see Securing Caché Web Services.
<portType>
Before the <binding> section, a WSDL contains <portType> elements, each of which defines an individual endpoint by specifying a single address for a <binding> element. A <portType> element is a named set of abstract operations and the abstract messages involved.
In general, a WSDL can contain multiple <portType> elements, but the WSDL for a Caché web service contains only one.
For the sample web service shown earlier in this appendix, the <portType> element is as follows:
<portType name="MyServiceNameSoap">
    <operation name="Add">
        <input message="s0:AddSoapIn"/>
        <output message="s0:AddSoapOut"/>
    </operation>
</portType>
All aspects of this element are automatically kept consistent with other parts of the WSDL; there is no independent control of it.
<message>
Before the <portType> element, the <message> elements define the messages used in the operations. The WSDL typically contains two <message> elements for each web method. For the sample web service shown earlier in this appendix, these elements are as follows:
<message name="AddSoapIn">
    <part name="parameters" element="s0:Add"/>
</message>
<message name="AddSoapOut">
    <part name="parameters" element="s0:AddResponse"/>
</message>
This element is specified as follows:
<types>
Before the <message> elements, the WSDL includes a <types> element, which defines the schema or schemas used by the messages. The <types> element includes one or more <schema> elements, and these define the elements, types, or both used by the web service and its clients. For the sample web service shown earlier in this appendix, this element is as follows:
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.mynamespace.org">
        <s:element name="Add">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="a" type="s0:ComplexNumber"/>
                    <s:element minOccurs="0" name="b" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
        <s:complexType name="ComplexNumber">
            <s:sequence>
                <s:element minOccurs="0" name="Real" type="s:double"/>
                <s:element minOccurs="0" name="Imaginary" type="s:double"/>
            </s:sequence>
        </s:complexType>
        <s:element name="AddResponse">
            <s:complexType>
                <s:sequence>
                    <s:element name="AddResult" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
The following subsections discuss the primary variations:
Note:
The <types> section is also influenced by the XML projections defined for all XML-enabled classes used by the web service. The XML projections determine issues such as namespace use, null handling, and handling of special characters. See the book Projecting Objects to XML.
The SoapBindingStyle and SoapBodyUse keywords affect other parts of the WSDL, which in turn determine the structure of the <types> section.
Name Attributes
Each <schema> element can consist of elements, types, or both, depending on the message style. Each of element or type has a name attribute, which is specified as follows:
For example, suppose that we edited the sample web method as follows:
Method Add(a As ComplexNumber, b As ComplexNumber) 
As ComplexNumber [ WebMethod, SoapMessageName = MyResponseMessage]
{
    Set sum = ##class(ComplexNumber).%New()
    Set sum.Real = a.Real + b.Real
    Set sum.Imaginary = a.Imaginary + b.Imaginary

    Quit sum
}
In this case, the <types> section would be as follows:
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.mynamespace.org">
        <s:element name="Add">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="a" type="s0:ComplexNumber"/>
                    <s:element minOccurs="0" name="b" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
        <s:complexType name="ComplexNumber">
            <s:sequence>
                <s:element minOccurs="0" name="Real" type="s:double"/>
                <s:element minOccurs="0" name="Imaginary" type="s:double"/>
            </s:sequence>
        </s:complexType>
        <s:element name="MyResponseMessage">
            <s:complexType>
                <s:sequence>
                    <s:element name="AddResult" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
For more information, see Controlling the Message Name of the SOAP Response.” Also see the book Projecting Objects to XML.
Namespaces in <types>
The following parameters of the web service affect the use of namespaces within the <types> section:
The NAMESPACE parameter of each XML-enabled class also affects the <types> element of the WSDL.
Consider the following variation of the web service shown earlier:
Class WSDLSamples.Namespaces Extends %SOAP.WebService
{

Parameter SERVICENAME = "MyServiceName";

Parameter NAMESPACE = "http://www.mynamespace.org";

Parameter RESPONSENAMESPACE = "http://www.myresponsenamespace.org";

Parameter TYPENAMESPACE = "http://www.mytypes.org";

Parameter RESPONSETYPENAMESPACE = "http://www.myresponsetypes.org";

Parameter USECLASSNAMESPACES = 1;

///  adds two complex numbers
Method Add(a As ComplexNumberNS, b As ComplexNumberNS) As ComplexNumberNS [ WebMethod ]
{
    Set sum = ##class(ComplexNumberNS).%New()
    Set sum.Real = a.Real + b.Real
    Set sum.Imaginary = a.Imaginary + b.Imaginary

    Quit sum
}

}
The class WSDLSamples.ComplexNumberNS is as follows:
///  A complex number
Class WSDLSamples.ComplexNumberNS Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter NAMESPACE = "http://www.complexnumbers.org";

Property Real As %Float;

Property Imaginary As %Float;

}
For the WSDL of this web service, the <types> part is as follows:
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.mytypes.org">
        <s:import namespace="http://www.complexnumbers.org"/>
        <s:element name="Add">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="a" type="ns2:ComplexNumberNS"/>
                    <s:element minOccurs="0" name="b" type="ns2:ComplexNumberNS"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.complexnumbers.org">
        <s:complexType name="ComplexNumberNS">
            <s:sequence>
                <s:element minOccurs="0" name="Real" type="s:double"/>
                <s:element minOccurs="0" name="Imaginary" type="s:double"/>
            </s:sequence>
        </s:complexType>
    </s:schema>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.myresponsetypes.org">
        <s:import namespace="http://www.complexnumbers.org"/>
        <s:element name="AddResponse">
            <s:complexType>
                <s:sequence>
                    <s:element name="AddResult" type="ns2:ComplexNumberNS"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
Other Possible Variations
The following additional parameters also affect the <types> element:
WSDL Variations Due to Method Signature Variations
This section shows some WSDL variations caused by variations in the method signature.
Returning Values by Reference or as Output Parameters
To return values by reference or as output parameters, use the ByRef or Output keyword, as appropriate, within the signature of the web method. This change affects the schema and the SOAP response message.
For example, consider the following web method signatures, from methods in two different web services:
//from web service 1
Method HelloWorld() As %String [ WebMethod ]

//from web service 2
Method HelloWorld(ByRef myarg As %String) [ WebMethod ]
For the first web service, the <types> section is as follows:
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.helloworld.org">
        <s:element name="HelloWorld1">
            <s:complexType>
                <s:sequence/>
            </s:complexType>
        </s:element>
        <s:element name="HelloWorld1Response">
            <s:complexType>
                <s:sequence>
                    <s:element name="HelloWorld1Result" type="s:string"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
For the second web service, which returns the value by reference, the <types> section has a variation for the type that corresponds to the response message:
<types>
...
        <s:element name="HelloWorld2Response">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="myarg" type="s:string"/>
...
This indicates that the element contained in the <HelloWorld2Response> message is <myarg>, which corresponds to the name of the argument in the message signature. In contrast, this element is usually <methodnameResult>.
If you use the ByRef keyword instead of Output, that has the same effect on the WSDL.
For information on these keywords, see the chapter Methods in Using Caché Objects.
Other WSDL Variations for Caché Web Services
This section discusses other possible variations for WSDLs for Caché web services.
WSDL Differences for Caché SOAP Sessions
If the SOAPSESSION parameter is 1 for the web service, that affects the WSDL as follows:
WSDL Differences for Caché Binary SOAP Format
For a Caché web service that has the SOAPBINARY parameter specified as 1, the WSDL is enhanced as follows:
These WSDL extensions are valid according to the XML Schema, WSDL, and WS-I Basic Profile specifications and are expected to be ignored by all conforming web client toolkits.
Note:
If a Caché web service or web client uses the Caché binary SOAP format, you cannot use WS-Security or WS-Policy features with this web service or client. See Securing Caché Web Services.
WSDL Differences for One-Way Web Methods
If the return type of a method is defined as %SOAP.OneWay, the WSDL is different from the default in the following ways: