The WSDL File - Java

The WSDL file generated by wscompile is shown in Listing 20.4. It is worth taking a few moments to study this information because it provides a good insight into the way that Web Services work.

Listing 20.4 Generated GreetingService WSDL (GreetingService.wsdl)

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="GreetingService"
targetNamespace="urn:J2EE21Examples"
xmlns:tns="urn:J2EE21Examples" 
xmlns="http://schemas.xmlsoap.org/wsdl/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
<types/>
<message name="Greeting_sayHelloTo">
<part name="String_1" type="xsd:string"/>
</message>
<message name="Greeting_sayHelloToResponse">
<part name="result" type="xsd:string"/>
</message>
<portType name="Greeting">
<operation name="sayHelloTo" parameterOrder="String_1">
<input message="tns:Greeting_sayHelloTo"/>
<output message="tns:Greeting_sayHelloToResponse"/>
</operation>
</portType>
<binding name="GreetingBinding" type="tns:Greeting">
<soap:binding transport=http://schemas.xmlsoap.org/soap/http
 style
="rpc"/>
<operation name="sayHelloTo">
<soap:operation soapAction=""/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" 
use="encoded" 
namespace="urn:J2EE21Examples"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/" 
use="encoded" 
namespace="urn:J2EE21Examples"/>
</output>
</operation>
</binding>
<service name="GreetingService">
<port name="GreetingPort" binding="tns:GreetingBinding">
<soap:address location="REPLACE_WITH_ACTUAL_URL"/>
</port>
</service>
</definitions> 

The document consists of the following sections:

• The XML prolog (<?xml ...?>) and root element(definitions)—The namespace declarations on the root element show that the operations defined here belong in the namespace
  urn:J2EE21Examples and that this namespace is also represented by the tns prefix. The default namespace declaration indicates that all unqualified elements and attributes come from the W3C's WSDL definitions. The xsd prefix denotes types from the
  W3C XML Schema definition, whereas the soap prefix denotes types from the SOAP schema.

• The types section—There are no complex types in the Greeting interface, so all the type definitions required come from the XML Schema. Hence, the types element is empty.

• WSDL message definitions—These define two matched messages: a request and a response. The request (Greeting_sayHelloTo) takes a single string parameter, and the response (Greeting_sayHelloToResponse) also returns a single string.

• WSDL portType definitions—A portType is the equivalent of an interface definition. It contains one or more operation definitions, which in turn are built from the message definitions in the document. In this case, there is a single operation defined in the Greeting called sayHelloTo. This consists of the two messages, Greeting_sayHelloToRequest and Greeting_sayHelloToResponse, seen earlier.

• The binding element—Called GreetingBinding, it indicates that clients can access the Greeting port type through the SOAP protocol. Now that you have an interface (portType), you can define the protocols over which that interface can be accessed. The WSDL operation is mapped to a SOAP operation with input and output soap:body elements defined to map the request and response.

• Within this WSDL binding, a SOAP binding (soap:binding)
  is defined—Because SOAP can work with a variety of underlying transports and it can work in an RPC-centric or
  document-centric way, the attributes on the
  soap:binding indicate that it is an RPC-style binding that uses HTTP.

• Finally, an instance of the service is defined in the WSDL service element—A WSDL service contains a list of WSDL port elements. Each port element defines a specific instance of a server that conforms to one of the WSDL binding elements
  defined earlier.

• Again, in the case of the simple Greeting service, the service element (named GreetingService) contains a single WSDL port called GreetingPort. This specifies that a server conforming to the GreetingBinding can be found at the SOAP address defined by the location attribute.

This is a very simple WSDL document defining a very simple service. WSDL documents are typically far longer and more complex. Because
of this, WSDL is largely intended for manipulation by tools and applications.

By examining the WSDL document, you can see how the information defined in the wscompile configuration file forms part of the WSDL. The targetNamespace and tns prefix in the WSDL are associated with the targetNamespace defined in the configuration file. The name of the WSDL service comes from the name attribute of the service element in the configuration file. The WSDL port is formed by appending the string "Port" to the name of the interface defined as a child of the service element in the configuration file.

One thing to note about the generated WSDL is that it is not complete. All the relevant type definitions are there (none in this case, but you will see more later), as are the definitions of the operations and their parameters and the protocol bindings. However, in the SOAP address associated with the port element, there is no endpoint address (the location is set to "REPLACE WITH ACTUAL URL"). This is not surprising because this WSDL has been generated from a class on the disk and wscompile has no way of knowing where this service will be deployed. Part of the deployment process will involve filling out this WSDL endpoint information so that the WSDL can be employed by a Web Service client.

The Mapping File

The mapping file—mapping.xml—provides a link between information in the WSDL document and the Java code supplied to support the service defined. There is a 1-1 relationship between mapping files and WSDL documents, and there are other constraints on the WSDL to assist the mapping, such as there being only one service description in a WSDL file. A full list of these restrictions and a detailed description of the mapping file (termed the "JAX-RPC Mapping Deployment Descriptor") can be found in section 7.3 of the document Web Services for J2EE document that was produced by JSR109.

Thankfully, the mapping file for our simple Greeting service is itself simple. It starts with a standard prolog and the root element java-wsdl-mapping:

<?xml version="1.0" encoding="UTF-8"?>
<java-wsdl-mapping version="1.1" 
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns: "xsi=http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://www.ibm.com/webservices/xsd/
j2ee_jaxrpc_mapping_1_1.xsd">

Within the root, you define package-mapping elements that map the namespaces using the WSDL to Java packages in which you define your classes. For the simple service, you just need to indicate that the service defined in the WSDL document under the target namespace of urn:J2EE21Examples is associated with the code defined in the Java package wsexamples:

<package-mapping>
<package-type>wsexamples</package-type>
<namespaceURI>urn:J2EE21Examples</namespaceURI>
</package-mapping>

The remainder of the mapping file defines how the WSDL service, port and binding relate to the parts of the Java Greeting interface defined earlier. The full mapping file is shown in Listing 20.5.

Listing 20.5 Mapping File for the Simple Greeting Service
(mapping.xml)

java-wsdl-mapping version="1.1"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://www.ibm.com/webservices/xsd/
j2ee_jaxrpc_mapping_1_1.xsd">
<package-mapping>
<package-type>wsexamples</package-type>
<namespaceURI>urn:J2EE21ExamplesTypes</namespaceURI>
</package-mapping>
<package-mapping>
<package-type>wsexamples</package-type>
<namespaceURI>urn:J2EE21Examples</namespaceURI>
</package-mapping>
<service-interface-mapping>
<service-interface>wsexamples.GreetingService
</service-interface>
<wsdl-service-name xmlns:serviceNS="urn:J2EE21Examples"
>serviceNS:GreetingService</

wsdl-service-name>
<port-mapping>
<port-name>GreetingPort</port-name>
<java-port-name>GreetingPort</java-port-name>
</port-mapping>
</service-interface-mapping>
<service-endpoint-interface-mapping>
<service-endpoint-interface>wsexamples.Greeting
</service-endpoint-interface>
<wsdl-port-type xmlns:portTypeNS="urn:J2EE21Examples">portTypeNS:
Greeting
</wsdl-port-type>
<wsdl-binding xmlns:bindingNS="urn:J2EE21Examples">bindingNS:
GreetingBinding
</wsdl-binding>
<service-endpoint-method-mapping>
<java-method-name>sayHelloTo</java-method-name>
<wsdl-operation>sayHelloTo</wsdl-operation>
<method-param-parts-mapping>
<param-position>0</param-position>
<param-type>java.lang.String</param-type>
<wsdl-message-mapping>
<wsdl-message xmlns:wsdlMsgNS="urn:J2EE21Examples">wsdlMsgNS:
Greeting_sayHelloTo</

wsdl-message>
 <wsdl-message-part-name>String_1</wsdl-message-part-name> <parameter-mode>IN</parameter-mode> </wsdl-message-mapping> </method-param-parts-mapping> <wsdl-return-value-mapping> <method-return-value>java.lang.String</method-return-value><wsdl-message xmlns:wsdlMsgNS="urn:J2EE21Examples">
wsdlMsgNS:Greeting_sayHelloToResponse</

wsdl-message>
 <wsdl-message-part-name>result</wsdl-message-part-name> </wsdl-return-value-mapping> </service-endpoint-method-mapping> </service-endpoint-interface-mapping></java-wsdl-mapping>

Packaging and Deploying the Simple Web Service Using J2EE RI deploytool

This section shows how to deploy the simple Web Service to the J2EE RI. You will get the most out of this if you actually perform these steps (but if you're on a train or plane, just read the text and make do).

As usual, start up the PointBase database server and J2EE RI server before starting deploytool.