Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Writing the WSML File
In most of the literature associated with the Microsoft SOAP Toolkit, the WSDL file is explained before the WSML. Basically, the WSDL file lists the various abstract services and messages that the SOAP server supports, whereas the WSML file explains how to link these abstract requests to physical COM object instances and methods.
Listing 1 shows the complete contents of OrderHandler.wsml.
Listing 1—The WSML File for the OrderHandler SOAP Service
<servicemapping name='OrderHandler'>
<service name='OrderHandler'>
<using PROGID='SXML.OrderHandler' cachable='0'
ID='OrderHandlerObject'/>
<port name='OrderHandlerSoapPort'>
<operation name='ProcessOrder'>
<execute uses='OrderHandlerObject' method='ProcessOrder'>
<parameter callIndex='1' name='strCustomerName'
elementName='strCustomerName'/>
<parameter callIndex='2' name='strCCNum'
elementName='strCCNum'/>
<parameter callIndex='3' name='strEmailName'
elementName='strEmailName'/>
<parameter callIndex='4' name='strEmailDate'
elementName='strEmailDate'/>
<parameter callIndex='5' name='astrPartNums'
elementName='astrPartNums'/>
<parameter callIndex='6' name='astrQuantities'
elementName='astrQuantities'/>
<parameter callIndex='-1' name='retval'
elementName='Result'/>
</execute>
</operation>
</port>
</service>
</servicemapping>
The three major entities exposed in this file are services, ports, and operations. A service is linked to a public SOAP service that's exposed in a WSDL file using the name attribute of the <servicemapping> element. Within the <servicemapping> element, a <service> element contains all the information required to link the abstract SOAP messages declared in the WSDL file to concrete COM object instances and methods.
Within a <service> element, one or more <using> elements declare the COM objects that will be exposed and give hints about how they may be used. These are the three attributes used in this example:
PROGID—This is the COM program ID of the object that must be instantiated.
cachable—This Boolean value indicates whether the object instance can be cached by the SOAP service for use in serving multiple SOAP requests.
ID—This is the XML ID that will be used by subsequent <execute> elements to indicate which object their methods apply to.
The <port> element contains one or more <operation> elements that define specific COM methods that can be invoked by the SOAP server. The port name is a linkage between the SOAP port declared in the WSDL <portType> element and the COM object operations defined in the WSML file. There is a one-to-one mapping between operations declared in the WSML <port> element and operations declared in the WSDL <portType> element.
An operation contains an <execute> element that defines precisely which COM object and method should serve a particular request. The execute element must include a uses attribute that references a particular COM object through a <using> element that is declared within the current <service> element. The method attribute gives the method name within the object that should be invoked. The <execute> element must contain <parameter> elements that map between the COM method parameters and the SOAP message elements that are declared in the corresponding <message> element of the WSDL document.
Each <parameter> element links a particular element from a SOAP request to a parameter position in a COM object method invocation. The callIndex attribute is a one-based index that indicates which position the current parameter occupies in the parameter list. If it's –1, it represents the return value of the method. The name attribute is not actually used by SOAP at the present time, but for documentation and consistency purposes it should be set to the COM method parameter name. The elementName attribute maps to a <part> declaration of a <message> element defined in the WSDL file.
Now, having defined the concrete linkages in the WSML file, we need to define the abstract SOAP interfaces in the WSDL file.