Developing a Service using JAX-WS

You can develop a service using one of two approaches:

• Start with a WSDL contract and generate Java objects to implement the service.
• Start with a Java object and service enable it using annotations.
  For new development the preferred path is to design your services in WSDL and then generate the code to implement them. This approach enforces the concept that a service is an abstract entity that is implementation neutral. It also means you can spend more time working out the exact interface your service requires before you start coding.

However, there are many cases where you may need to service enable an existing application. While JAX-WS eases the process, it does require that you make some changes to source code of your application. You will need to add annotations to the source. It also requires that you migrate your code to Java 5.0.

WSDL First Development

Using the WSDL first model of service development, you start with a WSDL document that defines the service you wish to implement. This WSDL document could be obtained from another developer, a system architect, a UDDI registry, or you could write it yourself. The document must contain at least a fully specified logical interface before you can begin generating code from it.

Once you have a WSDL document, the process for developing a JAX-WS service is three steps:

1. Generate starting point code.
2. Implement the service's operations.
3. Publish the implemented service.

Generating the Starting Point Code

JAX-WS specifies a detailed mapping from a service defined in WSDL to the Java classes that will implement that service. The logical interface, defined by the wsdl:portType element, is mapped to a service endpoint interface (SEI). Any complex types defined in the WSDL are mapped into Java classes following the mapping defined by the Java Architecture for XML Binding (JAXB) specification. The endpoint defined by the wsdl:service element is also generated into a Java class that is used by consumers to access endpoints implementing the service.

The wsdl2java command automates the generation of this code. It also provides options for generating starting point code for your implementation and an ant based makefile to build the application. wsdl2java provides a number of arguments for controlling the generated code.

Running wsdl2java

You can generate the code needed to develop your service using the following command:
wsdl2java -ant -impl -server -d outputDir myService.wsdl

The command does the following:

• The -ant argument generates a Ant makefile, called build.xml, for your application.
• The -impl argument generates a shell implementation class for each portType element in the WSDL document.
• The -server argument generates a simple main() to launch your service as a stand alone application.
• The -d outputDir argument tells wsdl2java to write the generated code to a directory called outputDir.
• myService.wsdl is the WSDL document from which code is generated.

Generated code

Table1 describes the files generated for creating a service.

Table 1: Generated Classes for a Service

Implementing the Service

Once the starting point code is generated, you must provide the business logic for each of the operations defined in the service's interface.

Generating the implementation code

You generate the implementation class for your service with wsdl2java's -impl flag.

Tip If your service's contract included any custom types defined in XML Schema, you will also need to ensure that the classes for the types are also generated and available.

Generated code

The service implementation code consists of two files:

• portTypeName.java is the service interface(SEI) for the service.
• portTypeNameImpl.java is the class you will use to implement the operations defined for the service.

Implement the operation's logic

You provide the business logic for your service's operations by completing the stub methods in portTypeNameImpl.java. For the most part, you use standard Java to implement the business logic. If your service uses custom XML Schema types, you will need to use the generated classes for each type to manipulate them. There are also some CXF specific APIs that you can use to access some advanced features.

Example

For example, an implementation class for a service that defined the operations sayHi and greetMe may look like Example1

package demo.hw.server;

import org.apache.hello_world_soap_http.Greeter;

@javax.jws.WebService(portName = "SoapPort", serviceName = "SOAPService",
 targetNamespace = "http://apache.org/hello_world_soap_http",
 endpointInterface = "org.apache.hello_world_soap_http.Greeter")

public class GreeterImpl implements Greeter {

 public String greetMe(String me)
{
        System.out.println("Executing operation greetMe");
        System.out.println("Message received: " + me + "\n");
        return "Hello " + me;
     }

 public String sayHi()
{
        System.out.println("Executing operation sayHi\n");
        return "Bonjour";
     }
}

Java First Development

To create a service starting from Java you need to do the following:

1. Create a Service Endpoint Interface (SEI) that defines the methods you wish to expose as a service.

   Tip You can work directly from a Java class, but working from an interface is the recommended approach. Interfaces are better for sharing with the developers who will be responsible for developing the applications consuming your service. The interface is smaller and does not provide any of the service's implementation details.

2. Add the required annotations to your code.
3. Generate the WSDL contract for your service.

   Tip If you intend to use the SEI as the service's contract, it is not necessary to generate a WSDL contract

4. Publish the service.

Creating the SEI

The service endpoint interface (SEI) is the piece of Java code that is shared between a service and the consumers that make requests on it. When starting with a WSDL contract, the SEI is generated by the code generators. However, when starting from Java, it is the up to a developer to create the SEI.

There are two basic patterns for creating an SEI:

• Green field development
  You are developing a new service from the ground up. When starting fresh, it is best to start by creating the SEI first. You can then distribute the SEI to any developers that are responsible for implementing the services and consumers that use the SEI.

  Note The recommended way to do green field service development is to start by creating a WSDL contract that defines the service and its interfaces.

• Service enablement
  In this pattern, you typically have an existing set of functionality that is implemented as a Java class and you want to service enable it. This means that you will need to do two things:
  1. Create an SEI that contains only the operations that are going to be exposed as part of the service.
  2. Modify the existing Java class so that it implements the SEI.

     Note You can add the JAX-WS annotations to a Java class, but that is not recommended.

Writing the interface

The SEI is a standard Java interface. It defines a set of methods that a class will implement. It can also define a number of member fields and constants to which the implementing class has access.

In the case of an SEI the methods defined are intended to be mapped to operations exposed by a service. The SEI corresponds to a wsdl:portType element. The methods defined by the SEI correspond to wsdl:operation elements in the wsdl:portType element.

Tip JAX-WS defines an annotation that allows you to specify methods that are not exposed as part of a service. However, the best practice is to leave such methods out of the SEI.

Example2 shows a simple SEI for a stock updating service.

package org.apache.cxf;

public interface QuoteReporter
{
  public Quote getQuote(String ticker);
}

Implementing the interface

Because the SEI is a standard Java interface, the class that implements it is just a standard Java class. If you started with a Java class you will need to modify it to implement the interface. If you are starting fresh, the implementation class will need to implement the SEI.

Example3 shows a class for implementing the interface in Example2.

package org.apache.cxf;

import java.util.*;

public class StockQuoteReporter implements QuoteReporter
{
  ...
public Quote getQuote(String ticker)
  {
    Quote retVal = new Quote();
    retVal.setID(ticker);
    retVal.setVal(Board.check(ticker));[1]
    Date retDate = new Date();
    retVal.setTime(retDate.toString());
    return(retVal);
  }
}

Annotating the Code

JAX-WS relies on the annotation feature of Java 5. The JAX-WS annotations are used to specify the metadata used to map the SEI to a fully specified service definition. Among the information provided in the annotations are the following:

• The target namespace for the service.
• The name of the class used to hold the request message.
• The name of the class used to hold the response message.
• If an operation is a one way operation.
• The binding style the service uses.
• The name of the class used for any custom exceptions.
• The namespaces under which the types used by the service are defined.

  Tip Most of the annotations have sensible defaults and do not need to be specified. However, the more information you provide in the annotations, the better defined your service definition. A solid service definition increases the likely hood that all parts of a distributed application will work together.

Required Annotations

In order to create a service from Java code you are only required to add one annotation to your code. You must add the @WebService() annotation on both the SEI and the implementation class.

The @WebService annotation

The @WebService annotation is defined by the javax.jws.WebService interface and it is placed on an interface or a class that is intended to be used as a service. @WebService has the following properties:

Tip You do not need to provide values for any of the @WebService annotation's properties. However, it is recommended that you provide as much information as you can.

Annotating the SEI

The SEI requires that you add the @WebService annotation. Since the SEI is the contract that defines the service, you should specify as much detail as you can about the service in the @WebService annotation's properties.

Example4 shows the interface defined in Example2 with the @WebService annotation.

package com.iona.demo;

import javax.jws.*;

@WebService(name="quoteUpdater",
            targetNamespace="http://cxf.apache.org",
            wsdlLocation="http://somewhere.com/quoteExampleService?wsdl")
public interface QuoteReporter
{
  public Quote getQuote(@WebParam(name="ticker") String ticker);
}

The @WebService annotation in Example4 does the following:

1. Specifies that the value of the name attribute of the wsdl:portType element defining the service interface is quoteUpdater.
2. Specifies that the target namespace of the service is http://cxf.apache.org.
3. Specifies that the service will use the pre-defined WSDL contract which is published at http://somewhere.com/quoteExampleService?wsdl.

The @WebParam annotation is necessary as java interfaces do not store the Parameter name in the .class file. So if you leave out the annotation your parameter will be named arg0.

Annotating the service implementation

In addition to annotating the SEI with the @WebService annotation, you also have to annotate the service implementation class with the @WebService annotation. When adding the annotation to the service implementation class you only need to specify the endpointInterface property. As shown in Example5 the property needs to be set to the full name of the SEI.

package org.apache.cxf;

import javax.jws.*;

@WebService(endpointInterface="org.apache.cxf.quoteReporter",
            targetNamespace="http://cxf.apache.org",
            portName="StockQuotePort",
            serviceName="StockQuoteReporter",
            )
public class StockQuoteReporter implements QuoteReporter
{
public Quote getQuote(String ticker)
  {
  ...
  }
}

Optional Annotations

While the @WebService annotation is sufficient for service enabling a Java interface or a Java class, it does not provide a lot of information about how the service will be exposed as an endpoint. The JAX-WS programming model uses a number of optional annotations for adding details about your service, such as the binding it uses, to the Java code. You add these annotations to the service's SEI.

Tip The more details you provide in the SEIthe easier it will be for developers to implement applications that can use the functionality it defines. It will also provide for better generated WSDL contracts.

Defining the Binding Properties with Annotations

If you are using a SOAP binding for your service, you can use JAX-WS annotations to specify a number of the bindings properties. These properties correspond directly to the properties you can specify in a service's WSDL contract.

The @SOAPBinding annotation

The @SOAPBinding annotation is defined by the javax.jws.soap.SOAPBinding interface. It provides details about the SOAP binding used by the service when it is deployed. If the @SOAPBinding annotation is not specified, a service is published using a wrapped doc/literal SOAP binding.

You can put the @SOAPBinding annotation on the SEI and any of the SEI's methods. When it is used on a method, setting of the method's @SOAPBinding annotation take precedent.

The following table shows the properties for the @SOAPBinding annotation.

Example6 shows an SEI that uses rpc/literal SOAP messages.

package org.eric.demo;

import javax.jws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;

@WebService(name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface QuoteReporter
{
  ...
}

Defining Operation Properties with Annotations

When the runtime maps your Java method definitions into XML operation definitions it fills in details such as:

• what the exchanged messages look like in XML.
• if the message can be optimized as a one way message.
• the namespaces where the messages are defined.

The @WebMethod annotation

The @WebMethod annotation is defined by the javax.jws.WebMethod interface. It is placed on the methods in the SEI. The @WebMethod annotation provides the information that is normally represented in the wsdl:operation element describing the operation to which the method is associated.

The following table describes the properties of the @WebMethod annotation.

The @RequestWrapper annotation

The @RequestWrapper annotation is defined by the javax.xml.ws.RequestWrapper interface. It is placed on the methods in the SEI. As the name implies, @RequestWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the request message sent in a remote invocation. It is also used to specify the element names, and namespaces, used by the runtime when marshalling and unmarshalling the request messages.

The following table describes the properties of the @RequestWrapper annotation.

Tip Only the className property is required.

The @ResponseWrapper annotation

The @ResponseWrapper annotation is defined by the javax.xml.ws.ResponseWrapper interface. It is placed on the methods in the SEI. As the name implies, @ResponseWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the response message sent in a remote invocation. It is also used to specify the element names, and namespaces, used by the runtime when marshalling and unmarshalling the response messages.

The following table describes the properties of the @ResponseWrapper annotation.

Tip Only the className property is required.

The @WebFault annotation

The @WebFault annotation is defined by the javax.xml.ws.WebFault interface. It is placed on exceptions that are thrown by your SEI. The @WebFault annotation is used to map the Java exception to a wsdl:fault element. This information is used to marshall the exceptions into a representation that can be processed by both the service and its consumers.

The following table describes the properties of the @WebFault annotation.

Important The name property is required. FixMe: faultName is defined as beanName by the Sun Java EE 5 SDK at http://java.sun.com/javaee/5/docs/api/javax/xml/ws/WebFault.html.

The @Oneway annotation

The @Oneway annotation is defined by the javax.jws.Oneway interface. It is placed on the methods in the SEI that will not require a response from the service. The @Oneway annotation tells the run time that it can optimize the execution of the method by not waiting for a response and not reserving any resources to process a response.

Example

Example7 shows an SEI whose methods are annotated.

package org.apache.cxf;

import javax.jws.*;
import javax.xml.ws.*;

@WebService(name="quoteReporter")
public interface QuoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.iona.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.iona.com/types",
                   className="org.eric.demo.Quote")
  public Quote getQuote(String ticker);
}

Defining Parameter Properties with Annotations

The method parameters in the SEI coresspond to the wsdl:message elements and their wsdl:part elements. JAX-WS provides annotations that allow you to describe the wsdl:part elements that are generated for the method parameters.

The @WebParam annotation

The @WebParam annotation is defined by the javax.jws.WebParam interface. It is placed on the parameters on the methods defined in the SEI. The @WebParam annotation allows you to specify the direction of the parameter, if the parameter will be placed in the SOAP header, and other properties of the generated wsdl:part.

The following table describes the properties of the @WebParam annotation.

The @WebResult annotation

The @WebResult annotation is defined by the javax.jws.WebResult interface. It is placed on the methods defined in the SEI. The @WebResult annotation allows you to specify the properties of the generated wsdl:part that is generated for the method's return value.

The following table describes the properties of the @WebResult annotation.

Example

Example8 shows an SEI that is fully annotated.

package org.apache.cxf;

import javax.jws.*;
import javax.xml.ws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;
import javax.jws.WebParam.*;

@WebService(name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface QuoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.iona.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.iona.com/types",
                   className="org.eric.demo.Quote")
  @WebResult(targetNamespace="http://demo.iona.com/types",
             name="updatedQuote")
  public Quote getQuote(
                        @WebParam(targetNamespace="http://demo.iona.com/types",
                                  name="stockTicker",
                                  mode=Mode.IN)
                        String ticker
  );
}

Generating WSDL

Once you have annotated your code, you can generate a WSDL contract for your service using the java2wsdl command.

Example

Example9 shows the WSDL contract generated for the SEI shown in Example8.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://demo.eric.org/"
                  xmlns:tns="http://demo.eric.org/"
		  xmlns:ns1=""
		  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
		  xmlns:ns2="http://demo.eric.org/types"
		  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
		  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:types>
    <xsd:schema>
      <xs:complexType name="quote">
        <xs:sequence>
          <xs:element name="ID" type="xs:string" minOccurs="0"/>
          <xs:element name="time" type="xs:string" minOccurs="0"/>
          <xs:element name="val" type="xs:float"/>
        </xs:sequence>
      </xs:complexType>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="getStockQuote">
    <wsdl:part name="stockTicker" type="xsd:string">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="getStockQuoteResponse">
    <wsdl:part name="updatedQuote" type="tns:quote">
    </wsdl:part>
  </wsdl:message>
  <wsdl:portType name="quoteReporter">
    <wsdl:operation name="getStockQuote">
      <wsdl:input name="getQuote" message="tns:getStockQuote">
    </wsdl:input>
      <wsdl:output name="getQuoteResponse" message="tns:getStockQuoteResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="quoteReporterBinding" type="tns:quoteReporter">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="getStockQuote">
      <soap:operation style="rpc"/>
      <wsdl:input name="getQuote">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="getQuoteResponse">
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="quoteReporterService">
    <wsdl:port name="quoteReporterPort" binding="tns:quoteReporterBinding">
      <soap:address location="http://localhost:9000/quoteReporterService"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>