WSDL

printer-friendly version of this section  Print  e-mail this section  E-Mail  add a public, group or private note  Add Note  add a bookmark about this section  Add Bookmark    

Java APIs for XML Kick Start
By Aoyon Chowdhury, Parag Choudhary

Table of Contents
Chapter 2.  Components of Web Services


The Web Services Description Language (WSDL) is an XML document that describes a Web service, specifies its location, and describes the interfaces and methods (called port and operations, respectively, in WSDL-speak) that can be executed on the Web service. This is similar to how a type library is used to describe a COM component, or the role that Interface Definition Language (IDL) plays in the CORBA architecture.

WSDL Example

Listing 2.3 shows a WSDL document that describes a Web service that returns the price of a book.

Listing 2.3 WSDL Document
<?xml version="1.0"?> <definitions name="BookPriceService"           targetNamespace="http://xxxx.xxxx/bookprice.wsdl"           xmlns:tns="http://xxxx.xxxx/bookprice.wsdl"           xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"           xmlns:xsd1="http://xxxx.xxxx/bookprice.xsd"           xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"           xmlns="http://schemas.xmlsoap.org/wsdl/">     <service name="BookPriceService">         <documentation>My first service</documentation>         <port name="BookPriceSoapPort" binding="tns:BookPriceBinding">            <soap:address location="http://xxxx.xxxx/bookprice"/>         </port>     </service>     <message name="GetBookPriceInput">         <part name="ISBNNumber" element="xsd:string"/>     </message>     <message name="GetBookPriceOutput">         <part name="result" type="xsd:float"/>     </message>     <portType name="BookPricePortType">         <operation name="GetBookPrice">            <input message="tns:GetBookPriceInput"/>            <output message="tns:GetBookPriceOutput"/>         </operation>     </portType>     <binding name="BookPriceSoapBinding" type="tns:BookPricePortType">         <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>         <operation name="GetBookPrice">            <soap:operation soapAction="http://xxxx.xxxx/GetBookPrice"/>            <input>                <soap:body use="encoded" namespace="http://xxxx.xxxx/bookprice"                           encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>            </input>            <output>                <soap:body use="encoded" namespace="http://xxxx.xxxx/bookprice"                           encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>            </output>         </operation>>     </binding> </definitions> 

This WSDL document describes a Web service that returns the price of a book. The Web service takes the ISBN number of the book as the key to look up the price information. The Web service exposes one method, GetBookPrice, which takes the ISBN number as an input parameter, and returns the price of the book as a float value.

Let's examine how the WSDL document describes the Web service. The root element of the WSDL document is the definitions element:

<definitions name="BookPriceService"           targetNamespace="http://xxxx.xxxx/bookprice.wsdl"           xmlns:tns="http://xxxx.xxxx/bookprice.wsdl"           xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"           xmlns:xsd1="http://xxxx.xxxx/bookprice.xsd"           xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"           xmlns="http://schemas.xmlsoap.org/wsdl/"> 

The name attribute of this element provides the name of the Web service. The namespace declarations provide the necessary identifiers that help uniquely identify the elements. Note that all the elements are defined in the WSDL namespace that is defined in http://schemas.xmlsoap.org/wsdl/. Therefore, this has been declared the default namespace for this WSDL document. Because we would be using elements from SOAP and XSD namespaces as well, these have also been appropriately defined.

The SOAP elements that are used within WSDL are also known as WSDL SOAP extension elements.

Next comes the service element:

<service name="BookPriceService">     <documentation>Query Book Price</documentation>     <port name="BookPriceSoapPort" binding="tns:BookPriceBinding">        <soap:address location="http://xxxx.xxxx/bookprice"/>     </port> </service> 

This element describes the Web service. The service element has the documentation and port elements. You can provide a human-readable description of a Web service within the documentation element. The port element specifies the address where the Web service can be accessed. Each port has a unique name and a binding attribute. It is important to remember that a Web service can be accessed by multiple mechanisms, such as HTTP GET or SMTP. In such a case, you will need to define three ports for the Web service, each with a unique name.

After the service and port have been decided, we need to define the request and response messages of the Web service:

<message name="GetBookPriceInput">         <part name="ISBNNumber" element="xsd:string"/>     </message>     <message name="GetBookPriceOutput">         <part name="result" type="xsd:float"/>     </message> 

These messages are required to do an RPC on a Web service. The request message is sent from the client to the Web service, and the response message is sent from the Web service to the client. The messages are protocol-independent, and can be used with any protocol such as HTTP GET.

The messages are defined using the message element. Each message element has zero or more part child elements. The part element describes the parameter or the return value and its data type, where the data types are as defined in the XML Schema specifications. Therefore, the GetBookPrice method of our Web service will mean two messages: a request message GetBookPriceInput and a response message GetBookPriceOutput.

It is important to remember that the SOAP specification requires that each part element must have the same name and data type as the parameter it represents.

Now that we have defined the messages, we need to tie them together as a request-response pair for a method call. This is done by using the operation element:

<portType name="BookPricePortType">         <operation name="GetBookPrice">            <input message="tns:GetBookPriceInput"/>            <output message="tns:GetBookPriceOutput"/>         </operation>     </portType> 

Using the input and output child elements, the operation element determines the input and output messages. The collection of all operations provided by the Web service is called a portType, and is defined using the portType element. You can give any name that you please to the portType.

After defining the messages, we need to determine how the abstract data types are represented physically. The SOAP 1.1 specifications can be used to decide the physical implementations of the abstract data types. This is done by using the binding element. The binding can have any name, as long as it is the same as used in the binding attribute of the port element:

<binding name="BookPriceSoapBinding" type="tns:BookPricePortType">     <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>     <operation name="GetBookPrice">        <soap:operation soapAction="http://xxxx.xxxx/GetBookPrice"/>        <input>            <soap:body use="encoded" namespace="http://xxxx.xxxx/bookprice"                       encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/"/>        </input>        <output>            <soap:body use="encoded" namespace="http://xxxx.xxxx/bookprice"                       encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/"/>        </output>     </operation>> </binding> 

Under the binding element, there is a SOAP WSDL extension element called soap:binding. This element determines the binding style (rpc or document) and the transport mechanism (SOAP over HTTP, SMTP, and so on). In our example, the binding style is rpc, and the transport mechanism is SOAP over HTTP.

Next, for each operation that the Web service provides, you need to specify the value of the SOAPAction HTTP header. This is achieved by using the operation element, with the name attribute having the value as that of the operation defined earlier. Within this operation element, you need to add the SOAP WSDL extension element operation, with the soapAction attribute specifying the HTTP header that the client sends when it invokes the Web service.

Finally, you need to specify the data encoding style for the input and output messages. This is done using the input and output elements, with a soap:body SOAP WSDL extension element. The value of the encodingStyle attribute of the soap:body SOAP WSDL extension element shows that the encoding style is as described in the SOAP 1.1 specification.


printer-friendly version of this section  Print  e-mail this section  E-Mail  add a public, group or private note  Add Note  add a bookmark about this section  Add Bookmark    
Top

[0672324342/ch02lev1sec4]

 
 


JavaT APIs for XML Kick Start
JAX: Java APIs for XML Kick Start
ISBN: 0672324342
EAN: 2147483647
Year: 2002
Pages: 133

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net