Revisiting the Stock Quote Web Service

Structure of the WSDL Document

The WSDL document describes each piece of the Web Service from each of the elements found in the XML (besides the standard SOAP elements) to the transport and the name.

The main six parts or elements of the WSDL document include: definitions, types, message, portType, binding, and service. Table 4.1 summarizes what each section describes.

Table 4.1: The Parent Elements That Make up an XML Document

Element	Purpose
definitions	The root element of the WSDL document. Defines many of the namespaces used for a particular description.
types	Defines the elements and primitive types found in the XML of the SOAP request and response.
message	Names the request and response messages.
portType	Ties a particular request and response message to a particular service.
binding	Indicates the type of transport (i.e., HTTP) used by the service. Also describes the contents of the message such as literal, meaning to take the XML at face value, or image/gif.
service	Actually names the services and provides an element to document what the service actually accomplishes.

Each of the sections is covered in greater detail later in the chapter. To help illustrate the structure of the WSDL document, Figure 4.2 uses a diagram.

Figure 4.2: Illustrates the structure of the WSDL document along with any child elements of each major section.

You’ll notice in Figure 4.2 that several of the elements actually have child elements as well. For example, the types element has an element that describes the elements found in the XML; it may contain several elements for a Web Service that contains many methods.

Now that you have been briefly introduced to each section of a WSDL document, the following sections go into greater detail.

definitions

definitions is the root element of the WSDL document. The beginning of the document may look like the following.

    <definitions name="GetStockQuote></definitions>

This only defines the name of the Web Service. To be useful, however, the definitions tag will need to define several different namespaces to support the different primitive types and the types created by the GetStockQuote Web Service. Once the namespaces are added, the definitions element now looks like the following.

   <definitions name="GetStockQuote         targetNamespace="http://advocatemedia.com/GetStockQuote.wsdl"         xmlns:myns = "http://advocatemedia.com/GetStockQuote.wsdl"         xmlns:myXsd = "http://advocatemedia.com/GetStockQuote.xsd"         xmlns:soap = "http://schemas.xmlsoap.org/wsdl/soap"         xmlns="http://schemas.xmlsoap.org/wsdl/">     </definitions>

Table 4.2 describes what each namespace definition does for the WSDL document.

Table 4.2: Detailed Information about What Each Namespace Definition Does for the WSDL Document

Namespace Definition	Placeholder	Description
targetNamespace	http://advocatemedia.comGetStockQuote.wsdl/	Defines the namespace for this document.
Myns	http://advocatemedia.com/GetStockQuote.wsdl	A more precise definition for this document.
MyXSD	http://advocatemedia.com/ GetStockQuote.xsd	Namespace for the schema types defined here.
xmlns:soap	http://schemas.xmlsoap.org/wsdl/soap	Namespace for the SOAP elements used in the document.
xmlns	http://schemas.xmlsoap.org/wsdl/	Sets the default namespace for SOAP elements.

Remember that a namespace is just a unique placeholder for a set of elements in an XML document. The URL is just a unique value and is not necessarily a URL to which you may point your browser.

types

The types element defines the different elements used within the Web Service. The elements defined here are for the variables in our Stock Quote Web Service. Just like with SOAP, WSDL uses the types from the schema standard so that standard types are used.

The types element defines a schema in the middle of our WSDL document. By doing this, a WSDL document is able to use the types defined in the schema standard rather than having to create its own.

Take a look at the following example and notice that several elements are defined.

    <types>         <schema           targetNamespace="http://advocatemedia.com/GetStockQuote.xsd"           xmlns="http://www.w3.org/2000/10/XMLSchema">           <element name="StockQuoteRequest">              <complexType>                <all>                  <element name="symbol" type="string"/>                </all>              </complexType>           </element>           <element name="StockQuoteResponse">              <complexType>                <all>                  <element name="price" type="float"/>                </all>              </complexType>           </element>          </schema>        </types>

StockQuoteRequest and StockQuoteResponse are the parent elements of the request and response documents. The elements that actually contain values (i.e., symbol and price), are the children. The types for these child elements also are defined here. symbol is defined as a string and price is defined as a float.

message

Now the WSDL document needs to describe and name both the request and response message. This comes after the type definition and gives a path back to the types in the message. The message elements look like the following.

    <message name="GetStockQuoteRequest">        <part name="body" element="myXSD:StockQuoteRequest"/>     </message>    <message name="GetStockQuoteResponse">        <part name="body" element="myXSD:StockQuoteResponse"/>     </message>

Notice that the element definitions have the names of the parent elements in the SOAP document. The namespace myXSD is used as a prefix so that the application using the WSDL document knows to find the definitions for these elements in the types portion of the document.

This gives the request and response messages a name so the applications or Web pages using this service know the name of the message to send and expect back when using a particular service. Note that this is protocol independent because there is no mention of HTTP or SMTP.

Note

The value of the name can be anything, but you should select something that is meaningful to you.

portType

To use the two messages defined in the previous section with the message element, you must define them as the request and response for a particular service.

This is done with the portType command, as shown in the following example.

 <portType name="GetStockQuotePort">       <operation name="GetStockQuote">           <input message="myns:GetStockQuoteRequest"/>           <output message="myns:GetStockQuoteResponse"/>       </operation>   </portType> 

GetStockQuote is now considered the name of the operation. The operation is the request for the price of a particular stock and the response is in the form of a price for that stock. The input and output messages just combine the two definitions used earlier so that the client knows that a particular request and response message belongs to a particular method in a Web Service.

Note

If this were a more complex Web Service, there would be several portType, message, and other elements. The example we’re using here is very simple so the WSDL isn’t too complex.

binding

The binding in a WSDL document indicates the type of transport that a Web Service uses. For example, if an XML document transmits its contents in the body, then the WSDL document needs to define that. If the document transmits its contents in Base64 encoding, then that would need to be defined here as well.

The binding name can be anything you wish. In this case, the name is GetStockQuoteBindingName.

Note

Tools generating WSDL will use their own algorithms for naming the different sections.

The next element is soap:binding. It defines the style of the binding and the transport. There are two styles to choose from: RPC and document. RPC indicates that a message contains parameters and that there are return values. When the style attribute contains document, the request and response are passing XML documents within the body of the SOAP message.

The namespace in the transport indicates which protocol is used for the Web Service. In this case, we use HTTP by looking at the namespace. This is the required namespace for the HTTP transport. If using another transport such as SMTP, you can specify your own namespace, but the name must contain the transport like this: http://advocatemedia.com/smtp/. It is interesting to note that a WSDL document must specify the transport, but it cannot specify the address of the service according to the standard.

The next part of the WSDL document, where the input and output elements reside, defines the contents of the request and response messages. In this case, the example uses the contents of the document without any encoding. If either message contained any encoding such as Base64 or image/gif, it would be indicated here.

<binding name="GetStockQuoteBindingName" type="GetStockQuotePort ">       <soap:binding             style="rpc"             transport=" http://schemas.xmlsoap.org/soap/http"/>       <operation name="GetStockQuote">           <soap:operation               soapAction="http://advocatemedia.com/GetStockQuote"/>           <input>               <soap:body use="literal"/>           </input>           <output>               <soap:body use="literal"/>           </output>       </operation>    </binding>

The only part of the Web Service left to define in the WSDL is the actual service.

Defining the service

Now that the transport, actions, content, style of message, and many other things have been defined, it is time to actually define the service. The service element, as shown in the following code example, actually defines the name of the service along with documentation and the location of the service. The following is the code.

    <service name="AdvocateMediaGetStockQuotes">         <documentation>Simple Web Service to                        Retrieve a stock quote</documentation>         <port name="GetStockQuotePort"               binding="myns:GetStockQuoteBindingName">           <soap:address                 location="http://advocatemedia.com/GetStockQuote"/>         </port>     </service>

The documentation element gives a developer the opportunity to provide some added information about what the Web Service accomplishes. The soap:address names the Web Service as a whole.