I like your type: Describe and invoke Spider web services based on service type

WSDL tools and techniques

  1. definitions are a WSDL document's root elements and contain all the namespace definitions used in the balance of the document.

  2. types depict the data blazon definitions used in message exchanges with the service. This department defines, for instance, how the parameters that pass to or return from method invocations are encoded in a programming language-neutral way.

    You lot tin can use whatever encoding format for your type system definitions. Even so, the WSDL specification document suggests using XML Schema Definitions, or XSD. XML Schema is a contempo W3C standard that attempts to go beyond certificate type definitions (DTDs) in defining an XML document's construction. XML Schema allows you to create a strong type organisation, like to how Java describes a type system. In other words, yous can unambiguously identify the information types of every element when encoding an XML document according to the XML Schema standard.

    XML Schema defines a fix of simple types, such as strings, doubles, or dates, and then specifies a mechanism for creating circuitous types out of those simple building blocks. That procedure resembles how y'all ascertain complex types in a programming language, except with XML Schema, that definition remains language-contained—you tin can use those types from Coffee, C++, or C#. Just XML Schema is non the only fashion to encode data types within a WSDL document. The WSDL documentation itself recommends the arrayType information type for arrays, based on the namespace http://schemas.xmlsoap.org/wsdl/. You lot will shortly see an example of that in the cruise Web service'south WSDL definition.

  3. message defines the messages exchanged with the service. For case, the return value from our prowl Web service transmits in bulletin grade. For each Web service message, the message section contains a bulletin chemical element, and each element specifies message parts as subelements.
  4. portType defines the bodily operations offered by the service. The cruise Spider web service has merely one operation, cruiseDestinations. That performance consists of ii message exchanges: a request (when a client invokes the method) and the response (the array of cruise destinations). Each operation might also include messages that indicate faults (exceptions) occurring during invocation.
  5. binding specifies the wire protocols used to access each portType. A portType can have many bindings. In other words, a service might provide access to its methods (operations) via numerous dissimilar protocols, such as SOAP, HTTP, RMI-IIOP (Net Inter-Orb Protocol), or RMI-JRMP (Coffee Remote Method Protocol, RMI'south default on-the-wire message protocol). The W3C'southward WSDL Recommendation describes three different protocol bindings: SOAP, HTTP GET and Mail service, and MIME (Multipurpose Internet Postal service Extensions) bindings. We will look at the Lather bounden while examining the cruise service'south WSDL.
  6. service describes the set up of ports to use when invoking the service. A service can have many ports, with each port having a name and a protocol binding. In addition, each port can have several URL addresses, which are likewise specified hither.

Figure 2 summarizes these six elements.

Figure two. WSDL document elements

Once a client retrieves a Spider web service's WSDL clarification, information technology tin examine the different ports that service offers and discover the names of the protocols those ports support from the service section. The client tin next examine what protocols those names refer to based on data in the binding section. The client can then choose the ports that it knows how to interact with. For instance, if the client can communicate via SOAP, it might then choose the service ports with Lather bindings. Finally, the customer would find the port types (operations), the messages those types entail, and those messages' data types. Based on the information in the WSDL document alone, a Web service'due south client can create a set of Java class files that enable it to directly invoke the service. Figure 3 illustrates the process of initiating service invocation based on a WSDL document'south information.

Figure 3. Initiate Spider web service invocation based on information in a WSDL document

Create WSDL from Java source code

The easiest manner to create a WSDL document for a Web service is with tools that automate the process. The Apache Axis package comes with one such tool, Java2WSDL. You tin can create a WSDL certificate for the cruise service with the following command (you should type this on a single line; also substitute the address to your ain server's accost):

coffee org.apache.centrality.wsdl.Java2WSDL -o cruise.wsdl      -fifty http://192.168.1.x:8080/centrality/servlet/AxisServlet      -n "urn:cruise" -S "CruiseService" CruiseService

The parameters are equally follows: -o specifies the output file, -l denotes the service's location, -n describes the service'southward unique namespace, while -S is the name we wish to give the service. The final parameter represents the name of the Coffee interface or class that defines the service. Given this control, the Java2WSDL tool produces the following document, saved in the cruise.wsdl file:

<?xml version="1.0" encoding="UTF-8"?> <wsdl:definitions     targetNamespace="urn:prowl"     xmlns:impl="urn:cruise-impl"     xmlns:intf="urn:prowl"     xmlns:apachesoap="http://xml.apache.org/xml-lather"     xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/lather/"     xmlns:soapenc="http://schemas.xmlsoap.org/lather/encoding/"     xmlns:xsd="http://www.w3.org/2001/XMLSchema"     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"     xmlns="http://schemas.xmlsoap.org/wsdl/">    <wsdl:types>       <schema xmlns="http://world wide web.w3.org/2001/XMLSchema" targetNamespace="urn:cruise">       <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>       <complexType name="ArrayOf_soapenc_string">         <complexContent>           <restriction base="soapenc:Array">               <attribute ref="soapenc:arrayType" wsdl:arrayType="soapenc:string[]"/>           </restriction>         </complexContent>       </complexType>       <chemical element name="ArrayOf_soapenc_string"          nillable="truthful" blazon="intf:ArrayOf_soapenc_string"/>       </schema>    </wsdl:types>    <wsdl:bulletin name="cruiseDestinationsResponse">       <wsdl:office proper name="return" type="intf:ArrayOf_soapenc_string"/>    </wsdl:message>    <wsdl:bulletin name="cruiseDestinationsRequest">    </wsdl:message>    <wsdl:portType proper noun="CruiseService">       <wsdl:operation proper name="cruiseDestinations">          <wsdl:input name="cruiseDestinationsRequest"                   message="intf:cruiseDestinationsRequest"/>          <wsdl:output name="cruiseDestinationsResponse"                   bulletin="intf:cruiseDestinationsResponse"/>       </wsdl:operation>    </wsdl:portType>    <wsdl:binding proper name="AxisServletSoapBinding" type="intf:CruiseService">       <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>       <wsdl:operation name="cruiseDestinations">          <wsdlsoap:operation soapAction=""/>          <wsdl:input proper name="cruiseDestinationsRequest">             <wsdlsoap:torso utilise="encoded"                     encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"                     namespace="urn:cruise"/>          </wsdl:input>          <wsdl:output proper name="cruiseDestinationsResponse">             <wsdlsoap:trunk utilize="encoded"                     encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"                     namespace="urn:cruise"/>          </wsdl:output>       </wsdl:operation>    </wsdl:binding>    <wsdl:service name="CruiseService">       <wsdl:port name="AxisServlet" bounden="intf:AxisServletSoapBinding">          <wsdlsoap:accost location="http://192.168.ane.10:8080/axis/servlet/AxisServlet"/>       </wsdl:port>    </wsdl:service> </wsdl:definitions>

This document features a WSDL document's six required parts. A few things to note about this file:

  • The WSDL document defines a target namespace of targetNamespace="urn:cruise".
  • The Java2WSDL tool converts the service method's array render type to wsdl:arrayType in the certificate's types section.
  • The bulletin section defines a request/response bulletin pair, each named subsequently the service method (for instance, <wsdl:bulletin name="cruiseDestinationsResponse">).
  • The WSDL file defines one performance for the service, corresponding to our Java class's sole method, <wsdl:functioning proper noun="cruiseDestinations">. The asking/response messages defined earlier constitute that service functioning.
  • The service defines a unmarried binding, based on Soap: <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>. The asking and response messages make up that SOAP operation'southward input and output.
  • Finally, the WSDL file designates a unmarried port, based on Java2WSDL'southward -l, or location, argument.

If yous placed this WSDL file on the Web, anyone could download it and interface with your service. Note that the ability to create WSDL documents from Java source code is not limited to Apache Axis; almost Spider web services tools feature this functionality, such as Glue, from The Heed Electric, and toolkits from Cape Clear Software, Sun Microsystems, IBM, BEA Systems, and others. I list several in Resources.

Create Java source code from WSDL

For Web service clients, tools are also bachelor for creating Java classes from a WSDL document. As you lot may take guessed, the WSDL2Java tool (not to be dislocated with the Java2WSDL tool) from Apache Axis offers that functionality. Given the WSDL document we just created, cruise.wsdl, you can generate Coffee classes with the following command (you might desire to copy cruise.wsdl to a new directory earlier running this command):

              java org.apache.centrality.wsdl.WSDL2Java prowl.wsdl

WSDL2Java offset examines the namespace specified by the WSDL document and creates a Java package with an identical name, in our case, prowl. It then places four Java source files inside that package. One of those files is CruiseService.java:

packet prowl; public interface CruiseService extends java.rmi.Remote {     public java.lang.String[] cruiseDestinations() throws java.rmi.RemoteException; }

That source lawmaking resembles our original Java interface except that information technology at present adheres to the semantics of a Remote Java interface (run across A Note on Distributed Computing for more on the semantics of remote method invocation). The other grade definitions help locate the service—based on the service endpoints—and interact with it via the SOAP bindings. A Spider web service client's programmer can incorporate these Coffee classes into her application and thereby collaborate with the service.

JWSDL: Programmatically create and edit WSDL documents

While automatically generating WSDL definitions based on Java classes frequently proves useful, the Java APIs for WSDL, or JWSDL, provide programmatic admission to creating, reading, and writing WSDL documents. The JWSDL is currently in evolution through the Coffee Customs Procedure (JCP) as Java Specification Request (JSR) 110. At the time of this writing, IBM provides a reference implementation of the proposed specification.

Unlike tools such as Axis's Java2WSDL, JWSDL does not map types or interfaces between WSDL descriptions and programming language types. Instead, programmatic interaction with WSDL documents offers different benefits: you can parse a WSDL file and examine the services it advertises along with those services' access ports, the protocols supported on those ports, and the operations and messages defined in the WSDL document. The JWSDL specification defines the javax.wsdl parcel.

Using JWSDL, you tin can detect services based on any of those technical attributes and invoke them dynamically. The on-the-wire protocol you decide to utilise, such as Soap, and so provides the type-mapping from XML to Java. When creating a WSDL document for a Web service, JWSDL offers complete flexibility in specifying and naming the elements on the WSDL description. Using JWSDL, we will extend the Web service customer to discover any services that implement the CruiseService, invoke them, and compile a chief listing of all available prowl destinations.

Remember that a service's type consists of the service's name, its operations' names, and the definitions of those operations' parameters and return types. For the cruise destination service, that means the following:

  1. The service proper name must be CruiseService within the urn:prowl namespace
  2. An operation with the name cruiseDestinations must be present and should consist of ane asking/response exchange
  3. That operation must crave no parameters and define a return type of arrayType (from the Lather namespace)

Once we find a Spider web service that matches those characteristics, we want to discover where to contact that service—the service's endpoint. In add-on, since our client can collaborate with the service via Lather but, we besides desire the service to offer at least one port with Lather binding.

The JWSDL API allows us to audit a set of WSDL documents, keeping only those matching the in a higher place criteria, and to extract from the matching documents information needed to contact each service. The JWSDL API separates design from implementation by offering a factory mechanism for accessing key API functionalities. The factory classes refer to interfaces, which an incarnation of the API can then fully implement. While I will use IBM's JWSDL implementation, WSDL4J, this case should besides work with other tools supporting JWSDL.

To read a WSDL file, you offset must obtain a WSDLReader from a factory and so parse the WSDL document into a definition. (Recall that definition is a WSDL document'due south root element.) Thereafter, JWSDL allows you to read and manipulate every element of that WSDL document.

Writing operations follow a symmetric process: you create a WSDLWriter from a factory and then write parts of a WSDL certificate as needed. JWSDL does not enforce semantic rules when writing new WSDL elements; it simply ensures correct syntax for the resulting document.

Finally, JWSDL likewise accounts for the extensible nature of WSDL definitions. The WSDL specification does not restrict protocol bindings to just Soap, HTTP, and MIME. JWSDL provides ExtensibilityElementdue south for those extensible document elements based on the WSDL specification. Even the SOAP bounden for a Spider web service is specified via JWSDL's extensibility infrastructure. Extensibility-related classes are located in the javax.wsdl.extensions, javax.wsdl.extensions.http, javax.wsdl.extensions.soap, and javax.wsdl.extensions.mime packages.

The following extension of the simple prowl service customer accepts a ready of WSDL files on the control line, finds the ones that are the CruiseService type, discovers the URL for the service's Lather port binding, and invokes each service instance to compile a master list of cruise destinations: