The top level or root element in a WSDL file is wsdl:defintions. Construction of this element will be almost fixed except for the targetNamespace. When defining a new WSDL Service, this is the first step.

set wsdlDef wsd
set targetNamespace "http://www.united-e-way.org"
set tnsAlias tns

::wsdl::definitions::new $wsdlDef $targetNamespace $tnsAlias

 

If the WSDL file was printed at this time it would look something like this:

<?xml version="1.0" encoding="utf-8"?>
<wsdl:definitions
 targetNamespace="http://www.united-e-way.org"
 xmlns:tns="http://www.united-e-way.org"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:s="http://www.w3.org/2001/XMLSchema"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

</wsdl:definitions>

A  WSDL Message identifies the structure (type) of a one-way communication. In simple terms it is either the input to or the output of a WSDL operation. It is assumed that the developer has already defined types which will correspond to the WSDL Message, so the API for this step is fairly simple:

::wsdl::message::new $wsdlDef SaveDonationSoapIn SaveDonation

This would result in the following XML fragment within a WSDL File:

  
<wsdl:message name="SaveDonationSoapIn">
 <wsdl:part name="parameters" element="tns:SaveDonation" />
</wsdl:message>

The message type is SaveDonation. All message types are globally defined elements in the wsdl:types section of the WSDL file. This API call should also ensure that the associated type definition and any types it depends on become a part of the WSDL file, so that the above call would ensure that the following, and all dependent types would be included in the WSDL file:

<s:element name="SaveDonation">
  <s:complexType>
    <s:sequence>
      <s:element minOccurs="0" maxOccurs="1" name="donationData" type="tns:DonationData" />
    </s:sequence>
  </s:complexType>
</s:element>

A  WSDL Operation describes a single type of interaction possible between a client and server. An operation associates inputs and outputs with a message type. The order of the input/output is important, for instance an in-out order is characteristic of request/response, that is first there is an input to the server, then an output from the server.

Operations are defined in a WSDL file in a way which makes them dependent on the portType and the Binding. The tWSDL API will offer a separate independent API to define operations before including them in a portType. At this stage, the developer also needs to associate an operation with an internal API. The full details will need to be worked out for complex inputs or outputs, but in simple cases, just the name of the procedure will be required.

::wsdl::operation::new $wsdlDef SaveDonation {
 {input SaveDonationSoapIn}
 {output SaveDonationSoapOut}
} {::my::internal::proc}

This would result in an XML fragment like this:

<wsdl:operation name="SaveDonation">
  <wsdl:input message="tns:SaveDonationSoapIn" />
  <wsdl:output message="tns:SaveDonationSoapOut" />
</wsdl:operation>

Once all the WSDL Operations are defined as above, they can be combined into a portType. A portType is simply a collection of operations. Collecting them togeather as a whole allows the developer to offer a similar set of operations via different bindings.

::wsdl::portType::new $wsdlDef OPPSServiceSoap {

 ...

 SaveDonation

 ...

}

This would result in an XML fragment like this:

<wsdl:portType name="OPPSServiceSoap">

...

  <wsdl:operation name="SaveDonation">
    <wsdl:input message="tns:SaveDonationSoapIn" />
    <wsdl:output message="tns:SaveDonationSoapOut" />
  </wsdl:operation>

...

</wsdl:portType>

A  WSDL Binding adds a few concrete details to the more abstract portTypes. A binding associates each operation (an internal name) in a portType with an external name and specifies a number of other items such as document style and encoding type. More importantly, a binding specifies a specific protocol type. The supported protocol for tWSDL is SOAP 1.1 using document-literal.

::wsdl::binding::soap::document_literal::new  $wsdlDef OPPSServiceSoap OPPSServiceSoap {

 ...

 {SaveDonation http://www.united-e-way.org/SaveDonation}

 ...

}

The corresponding XML would look like this:

<wsdl:binding name="OPPSServiceSoap" type="tns:OPPSServiceSoap">
  <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />

...

  <wsdl:operation name="SaveDonation">
    <soap:operation soapAction="http://www.united-e-way.org/SaveDonation" style="document" />
    <wsdl:input>
      <soap:body use="literal" />
    </wsdl:input>
    <wsdl:output>
      <soap:body use="literal" />
    </wsdl:output>
  </wsdl:operation>

...

</wsdl:binding>

There are other additional API that could be useful here. For instance, a separate API to add operations to a binding one at a time instead of as a list. Note that this is a specific extension API ::wsdl::binding::soap::document_literal. Each binding type should be written as an extension. This affords maximum flexibility as to arguments given to the API. In this case all that is needed is a listing of the wsdl operations and their external name (soapAction).

WSDL Ports are not defined outside of a Service, but an API to create a port is useful. When a Service is created it can simply reference the WSDL Port. A WSDL Port is the the Web Address, or URL of the Service.

::wsdl::port::new $wsdlDef OPPSServiceSoap OPPSServiceSoap {
 http://qa3-oppsservice.united-e-way.org/OPPSService.asmx
}

Note that the data required for a port may differe between bindings, so the information is passed as a list as the third argument. In this case, the SOAP Binding is used, so the SOAP extension will use this data to configure the server and client.

<wsdl:port name="OPPSServiceSoap" binding="tns:OPPSServiceSoap">
  <soap:address location="http://qa3-oppsservice.united-e-way.org/OPPSService.asmx" />
</wsdl:port>

The final step in building a Web Service Description is to name the service. The API must associate the Name with one or more ports:

::wsdl::service::new $wsdlDef OPPSService {OPPSServiceSoap}

<wsdl:service name="OPPSService">
  <wsdl:port name="OPPSServiceSoap" binding="tns:OPPSServiceSoap">
    <soap:address location="http://qa3-oppsservice.united-e-way.org/OPPSService.asmx" />
  </wsdl:port>
</wsdl:service>