O'Reilly logo

Java SOA Cookbook by Eben Hewitt

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Understanding WSDL

Problem

You have just deployed a simple web service and want to view its WSDL to understand the relation of your code to the deployed web service.

Solution

Inspect the WSDL by appending ?WSDL to the end of the service name. This is only a convention and is not required by any specification, but all of the major vendors (IBM, Microsoft, BEA/Oracle, Sun, JBoss) adhere to it.

Check out the following discussion on the key sections of a WSDL in order to better understand this important part of your web service contract.

Discussion

It’s hard to have a general discussion of WSDL sections because they change depending on choices you made in a specific service. So in this discussion, we examine the WSDL that is generated for the web service you created in Creating and Deploying the Simplest Web Service, Example 4-3.

Inspect the WSDL published to the Java 6 internal HTTP server by opening your web browser to http://localhost:9999/hello?wsdl. You should see something like Example 4-4.

Example 4-4. The Hello WSDL

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:tns="http://ch03.soacookbook.com/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
    targetNamespace="http://ch03.soacookbook.com/" 
    name="HelloWSService">
  <types></types>
  <message name="sayHello">
    <part name="arg0" type="xsd:string"></part>
  </message>
  <message name="sayHelloResponse">
    <part name="return" type="xsd:string"></part>
  </message>
  <portType name="Hello">
    <operation name="sayHello" parameterOrder="arg0">
      <input message="tns:sayHello"></input>
      <output message="tns:sayHelloResponse"></output>
    </operation>
  </portType>
  <binding name="HelloWSPortBinding" type="tns:Hello">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http">
    </soap:binding>
    <operation name="sayHello">
      <soap:operation soapAction=""></soap:operation>
      <input>
        <soap:body use="literal" namespace="http://ch03.soacookbook.com/"></soap:body>
      </input>
      <output>
        <soap:body use="literal" namespace="http://ch03.soacookbook.com/"></soap:body>
      </output>
    </operation>
  </binding>
  <service name="HelloWSService">
    <port name="HelloWSPort" binding="tns:HelloWSPortBinding">
      <soap:address location="http://localhost:9999/hello"></soap:address>
    </port>
  </service>
</definitions>

There are a few things to notice about the WSDL published by the endpoint. Let’s look at them to gain a better understanding of how this all works.

Types

This Types section of the WSDL is empty. Types is where a WSDL either imports or locally defines the XML schema types that the messages your web service exchanges will use. The reason this section is empty is that the messages defined by this web service use only strings, which are defined as a simple type in XML Schema—all web services will be able to use them out of the box. So it’s not necessary to put anything there.

Frequently, WSDLs will define a Types section that points to an external schema. In your WebLogic service created in Creating and Deploying a Service to WebLogic, the WSDL indicates the location of a schema, generated by the server at deploy time, that defines the types the messages will use:

<types>
<xsd:schema>
  <xsd:import namespace="http://soacookbook.com/" 
    schemaLocation="http://localhost:7777/TestWS/HelloWSService?xsd=1"/>
</xsd:schema>
</types>

That URI references a complete XML Schema document that indicates the values of the complex types used in the request and response messages.

If you are writing your own WSDL, you can define your types this way in an external schema, or define them entirely inline, like this:

<types>
<xsd:schema>
  <xsd:simpleType name="ID">
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[0-9]{5}"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>
</types>

In general, it’s considered a best practice not to define your types inline in order to keep the interface separate from the implementation as much as possible. Instead, refer to an external schema.

Messages

The Messages section of the WSDL contains definitions for the request and responses to be used in communicating with the service. You’ll notice that there is one message each for the request and response. The request message has the same name as the method invocation because you are doing RPC style here. The response is given the name of the operation appended with “Response”, which is the default according to the JAX-WS specification. Each of these messages has a part child. A message part is similar to a parameter to a method in that it has a name and a type. The name for the first part is “arg0”, which is the default. Subsequent arguments would be named “arg1”, and so forth. These names can be customized to make them easier to read and follow, which becomes increasingly important for more complicated WSDLs.

For the response, there is an element <part name="return" type="xsd:string">. Because the default parameter style value is “wrapped,” the value that gets returned by the web service will be wrapped within a single element with a name of “return” from which you can extract the rest of the payload. This is discussed in more detail in Choosing Encoding, Use, and Parameter Styles.

Binding

The Bindings section of the WSDL indicates the transport used to send messages to and from a web service. The default is SOAP, and other advanced options include HTTP, JMS, SMTP, and TCP. Because you specified that you wanted to bind your service to SOAP using the @SOAPBinding(style=SOAPBinding.Style.RPC) annotation on your Hello service interface implementation class, you get SOAP bindings as the message transport.

The <soap:binding> element features a transport attribute with a value of http://schemas.xmlsoap.org/soap/http. That means that the service will use SOAP 1.1 for the send and receive protocol for your messages. You can also specify SOAP 1.2, but 1.1 is the default, and using SOAP 1.2 is not widely recommended just yet, as the overwhelming majority of implementations currently are for 1.1.

You can also see that the <soap:binding> element features a style attribute with a value of “rpc”, which was written in this WSDL because of the @SOAPBinding(style=SOAPBinding.Style.RPC) annotation on the Hello service interface. The other option you could have provided there is “document.” This is discussed in detail in Choosing Encoding, Use, and Parameter Styles.

The service is given a namespace of http://ch03.soacookbook.com, which matches an exact reversal of the package name of the Java class defining the endpoint. Likewise, the operation name matches the method name in that class because you have not customized it.

Service

The Service section of the WSDL indicates that the name of the service will be HelloWSService. This is the name of the class that defined your service, with “Service” appended to it, which is how services with no customizations are named according to the JAX-WS specification. It also indicates that the “HelloWSPort” port will be bound using SOAP. The elements in that section are prefixed with soap, indicating that they are from the http://schemas.xmlsoap.org/wsdl/soap/ namespace.

The important location attribute here indicates where you can invoke the service, and this is what clients will use to invoke it. The next recipe shows you how to invoke this service.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required