+

Search Tips   |   Advanced Search

WSDL

WSDL is an Extensible Markup Language (XML)-based description language. This language was submitted to the World Wide Web Consortium (W3C) as the industry standard for describing web services. The power of WSDL is derived from two main architectural principles: the ability to describe a set of business operations and the ability to separate the description into two basic units. These units are a description of the operations and the details of how the operation and the information associated with it are packaged.

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definitions of endpoints and messages are separated from their concrete network deployment or data format bindings. This separation supports the reuse of abstract definitions: messages, which are abstract descriptions of exchanged data, and port types, which are abstract collections of operations. The concrete protocol and data format specifications for a particular port type constitutes a reusable binding. A port is defined by associating a network address with a reusable binding, and a collection of ports defines a service. Therefore, a WSDL document is composed of several elements.

The following is the structure of the information in a WSDL file:

A WSDL file contains the following parts:

A WSDL file describes a web service with the following elements:


portType

The description of the operations and associated messages. The portType element defines abstract operations.

<portType name="EightBall">
  <operation name="getAnswer">
    <input message="ebs:IngetAnswerRequest"/>
    <output message="ebs:OutgetAnswerResponse"/>
  </operation>
</portType>


message

The description of input and output parameters and return values.

<message name="IngetAnswerRequest">
  <part name="meth1_inType" type="ebs:questionType"/>
</message>
<message name="OutgetAnswerResponse">
  <part name="meth1_outType" type="ebs:answerType"/>
</message>


types

The schema for describing XML types used in the messages.

<types>
  <xsd:schema targetNamespace="...">
    <xsd:complexType name="questionType">
      <xsd:element name="question" type="string"/>
    </xsd:complexType>
    <xsd:complexType name="answerType">
    ...
</types>


binding

The bindings describe the protocol used to access a portType, as well as the data formats for the messages defined by a particular portType element.

<binding name="EightBallBinding" type="ebs:EightBall">
  <soap:binding style="rpc" transport="schemas.xmlsoap.org/soap/http">
  <operation name="ebs:getAnswer">
  <soap:operation soapAction="urn:EightBall"/>
    <input>
      <soap:body namespace="urn:EightBall" ... />
      ...


Service

The services and ports define the location of the Web service.

The service contains the web service name and a list of ports.


Ports

The ports contain the location of the web service and the binding used for service access.
<service name="EightBall">
  <port binding="ebs:EightBallBinding" name="EightBallPort">
    <soap:address location="localhost:8080/axis/EightBall"/>
  </port>
</service>

When creating Java API for XML Web Services (JAX-WS) or Java API for XML-based RPC (JAX-RPC) web services, we can use a bottom-up development approach when you start from JavaBeans or an enterprise bean, or we can use a top-down development approach when you start with an existing Web Services Description Language (WSDL) file.

When creating JAX-WS web services for this product, we can start with either a WSDL or an implementation bean class. If you start with an implementation bean class, then use the wsgen command line tool to generate all the web services server artifacts, including a WSDL if requested. If you start with a WSDL, then use the wsimport command line tool to generate all the web services artifacts for either the server or client side.

When creating JAX-RPC web services for this product, first have an implementation bean that includes a service endpoint interface. Then, we use the Java2WSDL command-line tool to create a WSDL file that defines the web services. If we are starting with the WSDL to generate the implementation bean class, run the WSDL2Java command line tool against the WSDL file to create Java APIs and deployment descriptor templates.


Multipart WSDL and WSDL publication

The product supports deployment of web services using a multipart Web Services Description Language (WSDL) file. In multipart WSDL files, an implementation WSDL file contains the wsdl:service. This implementation WSDL file imports an interface WSDL file, which contains the other WSDL constructs. This supports multiple web services using the same WSDL interface definition.

The <wsdl:import> element indicates a reference to another WSDL file. If the <wsdl:import> element location attribute does not contain a URL, that is, it contains only a file name, and does not begin with http://, https:// or file://, the imported file must be located in the same directory and must not contain a relative path component. For example, if META-INF/wsdl/A_Impl.wsdl is in your module and contains the <wsdl:import="A.wsdl" namespace="..."/> import statement, the A.wsdl file must also be located in the module META-INF/wsdl directory.

IBM recommends that you place all WSDL files in either the META-INF/wsdl directory, if we are using EJB, or the WEB-INF/wsdl directory, if we are using JavaBeans components, even if relative imports are located within the WSDL files. Otherwise, implications exist with the WSDL publication when we use a path like <location="../interfaces/A_Interface.wsdl"namespace="..."/>. Using a path like this example fails because the presence of the relative path, regardless of whether the file is located at that path or not. If the location is a web address, it must be readable at both deployment and server startup.

We can publish the files located in the META-INF/wsdl or the WEB-INF/wsdl directory through either a URL address or file, including WSDL or XML Schema Definition (XSD) files. For example, if the file referenced in the <wsdl-file> element of the webservices.xml deployment descriptor is located in the META-INF/wsdl or the WEB-INF/wsdl directory, it is publishable. If the files imported by the <wsdl-file> are located in the wsdl/ directory or its subdirectory, they are publishable.

If the WSDL file referenced by the <wsdl-file> element is located in a directory other than wsdl, or its subdirectories, the file and its imported files, either WSDL or XSD files, which are in the same directory, are copied to the wsdl directory without modification when the application is installed. These types of files can also be published.

If the <wsdl-file> imports a file located in a different directory (a directory that is not -INF/wsdl or a subdirectory), the file is not copied to the wsdl directory and not available for publishing.

For JAX-WS web services, you can use an annotation to specify the location of the WSDL. Use the @WebService annotation with the WSDLLocation attribute. The WSDLLocation attribute is optional. If this attribute is not specified, then WSDL is generated and published from the information found in the web service classes. We can optionally specify the location of the WSDL file in the webservices.xml deployment descriptor. However, any information defined in the webservices.xml deployment descriptor overrides any corresponding information specified by annotations.


Related:

  • Web Services for Java EE specification
  • Generate Java artifacts for JAX-WS applications
  • Developing a WSDL file for JAX-RPC applications
  • Making deployed web services applications available to clients
  • wsimport command for JAX-WS applications
  • wsgen command for JAX-WS applications
  • Java2WSDL command for JAX-RPC applications
  • WSDL2Java command for JAX-RPC applications
  • Web services specifications and APIs
  • WSDL 1.1