Developing Web services for WebSphere using JAX-WS

Annotations

Bruce Tiffany
Advisory Software Engineer, Web Services for WebSphere Functional Test
IBM

Dustin Amrhein
Staff Software Engineer, Web Services for WebSphere Application Server Development
IBM

Jeff Barrett
Advisory Software Engineer, Web Services for WebSphere Application Server
Development
IBM

November, 2007

© Copyright International Business Machines Corporation 2007. All rights reserved.

This article describes how you can use Java™ annotations in your source code to develop
and deploy a Web service endpoint for the WebSphere® Application Server V6.1 Web
Services Feature Pack.

Developing Web services for WebSphere using JAX-WS Annotations ............................ 1

Introduction......................................................................................................................... 2
Using basic annotations and command line tools ............................................................... 2
Limitations of a start-from-Java approach...................................................................... 2
The @WebService annotation ........................................................................................ 3
The @WebMethod annotation........................................................................................ 4
The @Oneway annotation .............................................................................................. 6
The @WebFault annotation ............................................................................................ 7
The @RequestWrapper and @ResponseWrapper annotations....................................... 8
The @WebServiceProvider annotation .......................................................................... 8
The @ServiceMode annotation ...................................................................................... 9
Deploy a Web service ......................................................................................................... 9
Develop and deploy a client.............................................................................................. 11
Understanding Web service inheritance, handlers and more............................................ 12
Using JAX-WS Web service inheritance...................................................................... 12
The @HandlerChain annotation ................................................................................... 15
The @WebParam annotation ........................................................................................ 15
The @WebResult annotation ........................................................................................ 16
 The @SoapBinding annotation..................................................................................... 16
The @BindingType annotation..................................................................................... 18
Summary ........................................................................................................................... 20
Resources .......................................................................................................................... 20
About the authors.............................................................................................................. 20

Introduction
The WebSphere Application Server V6.1 Feature Pack for Web Services allows
developers to create and deploy Web services with the Java API for XML Web Services
(JAX-WS) programming model. JAX-WS simplifies the creation of Web services from
existing Java source code.

In this article, you’ll learn how to use Java annotations to develop and deploy a Web
service endpoint, how the annotations affect the resulting WSDL, and how to develop
and deploy simple applications with command line tools.

Using basic annotations and command line tools

The following sections demonstrate the “start-from-Java” method of describing a Web
service endpoint using annotations. They discuss the limitations of this approach, explain
the major annotations and their corresponding WSDL elements, and demonstrate how to
build, package and deploy a JAX-WS Web service endpoint.

Limitations of a start-from-Java approach

XML, Java, and other Web services standards differ in how they represent and exchange
data. Java data types are converted to and from XML during the exchange between the
server and the client. This conversion can produce method signatures that differ between
the client and the server, although both represent the same data. In some cases, you need
to customize the Java classes so that they convert properly; annotations can help with
that. When writing services starting from Java, keep these things in mind:

• Some Java data types don’t map symmetrically to XML and back. Selecting
different types or closely examining Java Architecture for XML Binding (JAXB)
2.0 (used by Java API for XML Web Services (JAX-WS) for XML-to-Java
mapping) may help. When you develop services starting from WSDL, you can
customize the schema more flexibility in JAXB type mapping.

• Data, not code, is exchanged between the client and service. Your design should
emphasize data exchange, not behavior exchange. Subtleties of polymorphism
and inheritance can be challenging to preserve over the wire.
 • Methods that depend on overloading or case sensitivity are more likely to need
customization.

The @WebService annotation

First let’s look at a very simple “Hello World” Web service.

package example1;
import javax.jws.WebService;
@WebService
public class HelloWorld{
public String sayHello(String input){
return("Hello, " + input);
}
}

In this example, the @WebService annotation declares the class as a Web service. There
is no interface. The run-time produces the WSDL and related schema files. The
deployment tools generate other necessary classes. The only thing you need to supply is
the implementation class and some deployment information.

The deployment process is decsribed later in this article. The service and client for this
example are included in the sample code provided for download with this article.

While the run-time generates a WSDL 1.1 file, you may want to supply the WSDL file
with the service. For Web service implementations that use complex schema types there
may be a tangible performance benefit when supplying the WSDL document. If you
supply a WSDL file, the run-time checks that the implementation class operations,
parameters, and bindings match those in the WSDL.

You can use the JAX-WS wsgen tool with the –wsdl flag to create a WSDL file. Edit the
WSDL file to add your own customizations, then package the WSDL with your
application.

You may want to reference an endpoint interface to standardize an implementation class,

or as a way to limit the methods that are exposed as part of your Web service. You can do
this with an annotation parameter, rather than the Java implements keyword.

To include WSDL and use an interface in the example above, you’d need to change the
annotation to something like:

@WebService(wsdlLocation=”WEB-INF/wsdl/HelloWorldService.wsdl”,
endpointInterface=”simple.HelloWorldIf”)

If you use an endpoint interface, it too must have an @WebService annotation. This is
shown in Example 2 in the downloadable samples.
There are four additional parameters on the @WebService annotation:
• The name attribute is the name of the service.
• The serviceName attribute maps to the <wsdl:service> element.
• The portName attribute maps to the <wsdl:port> element.
• The targetNamespace element maps to the target namespace of the WSDL
document.

For example, the following annotation:

@WebService(name=”HelloWorld”, serviceName=”HelloWorldService”,
portName=”HelloWorldPort”, targetNamespace=”http://com.myexample”)

maps to WSDL as follows:

<wsdl:definitions targetNamepsace=”http://com.myexample”>
…
<wsdl:service name=”HelloWorld”>
<wsdl:port name=”HelloWorldPort”>
…
</wsdl:port>
</wsdl:service>
</wsdl:definitions>

Since services deploy to http://hostname:port:/context_root/serviceName by default,

changing the serviceName attribute can change the deployment URL if it’s not
otherwise specified in the web.xml deployment descriptor file. The default value for
serviceName is the name of the class or interface appended with Service.

The @WebMethod annotation

You can use the @Webmethod annotation to customize method names or keep methods
from being exposed as part of the service.

• If you used an endpoint interface, you cannot use this annotation in the
implementation class.
• If there is no endpoint interface, and the annotation is not present in the class, all
public methods are exposed.
• If the annotation is used only to exclude methods from the service, only the
annotated methods are affected.
• If the annotation is present anywhere in the class in any other form, only the
annotated methods are exposed and all un-annotated methods are excluded.

You may want to use this annotation to customize method names to adhere to a supplied
WSDL contract, prevent methods from being exposed by the implementation, and
provide an action attribute for the method, which is useful when the service exposes a
SOAP binding.
If your implementation contains a public method that should not be accessible through
the service, you can block it with the exclude parameter:
@WebMethod(exclude=”true”).

For example, the service for the class below exposes operations a, b and c.
package simple;
import javax.jws.WebService;
@WebService
public class HelloWorld3{
public String a(String input){ return("Hello, " + input); }
public String b(String input){ return("Hello, " + input); }
public String c(String input){ return("Hello, " + input); }

The service for the class below exposes operations b and c.

package simple;
import javax.jws.WebService;
@WebService
public class HelloWorld3{
@WebMethod(exclude=”true”)
public String a(String input){ return("Hello, " + input); }
public String b(String input){ return("Hello, " + input); }
public String c(String input){ return("Hello, " + input); }

The service for theclass below exposes only operation a.

package simple;
import javax.jws.WebService;
import javax.jws.WebMethod;
@WebService
public class HelloWorld4{
@WebMethod
public String a(String input){ return("Hello, " + input); }
public String b(String input){ return("Hello, " + input); }
public String c(String input){ return("Hello, " + input); }
}

You can customize the name of the operation in the WSDL as shown below:
@WebMethod(operationName=addInt)
public int add(int a, int b)

@WebMethod()
public int add(int a, float b)

The annotation shown above changes the WSDL operation name from add to addInt.
This can be useful in resolving problems due to WSDL limitations with respect to
operation overloading or case-sensitive names.

The resulting WSDL fragment looks like this:

<wsdl:portType name=”myPortType”>
<wsdl:operation name=“addInt”>
…
</wsdl:operation>
<wsdl:operation name=”add”>
…
</wsdl:operation>
</wsdl:portType>

Finally, you can customize the WSDL soap action attribute with the action
parameter; for example: @WebMethod(action=”doSomething”). Actions are placed in
the request message header, as shown below. The use of actions is often application-
specific.

<binding>
<soap:binding />
<operation name=”add”>
<soap:operation action=”doSomething”>
…
</soap:operation>
…
</operation>
…
</binding>

The @Oneway annotation

The @Oneway annotation marks a method that returns immediately before processing is
complete. It’s useful for implementing “fire and forget” operations where no result
information is needed by the caller. @Oneway methods must have a void return type.

The caller gets an exception if the JAX-WS server run-time doesn’t acknowledge the
caller’s inbound request. Once acknowledgement is received, the call returns, and the
operation runs asynchronously. A subsequent failure is not detectable by the caller.

JAX-WS also provides ways to implement asynchronous calls that do return data, but
those are not discussed in this article.

The code snippet below shows a simple class that invokes a time-consuming operation
using @Oneway to avoid waiting for completion.

package simple;
import javax.jws.WebService;
import javax.jws.Oneway
@WebService
public class Sample5{
@Oneway
public void recordSale(String sku, int quantity){ // lengthy
operation here. }
}

Example 3 in the downloadable samples shows the use of the @WebMethod and @Oneway
annotations.

The @WebFault annotation

When a method throws an exception, that exception is mapped to a JAXB bean that is
conveyed to the client, and supplies the fault element information defined in WSDL.

This annotation is not usually required when starting from Java, but you can use it to
customize the namespace or element name of the fault element in the WSDL if
needed.

The following example annotation:

@WebFault(name=”baduserid”, targetNamespace=”urn://com.sample.faults”,
faultBean=”com.sample.faults.BadUserFault”)
public class InvalidUserIdException extends Exception{
….
}

appears in WSDL as:

<message name="InvalidUserIdException">
<part name="fault" element="ns1:baduserid"
xmlns:ns1="urn://com.sample.faults"/>
</message>
and changes the name of the fault bean class to com.sample.faults.BadUserFault.

Because of the way Java exceptions are mapped into fault data, exception names and
methods usually differ between the service and the client. When an exception is
converted to a fault and sent to the client, a bean is created containing some of the fields
from the service-side exception. The bean is then wrapped in another exception class for
the client-side. Here are some of the differences:

Service-side Java Client-side Java

Throws a checked FooException
FooException.getStackTrace returns
server side trace
getCause returns cause
Getters are called directly, such as
FooException.getSomething()
Throws an unchecked Exception
Receives an exception, which may have a
different derived name
“derived_name”.getStackTrace returns client side
trace
getCause returns null
Getters are called via
“derived_name”.getFaultInfo().getSomething()
receives one of
javax.xml.ws.WebServiceException,
javax.xml.ws.ProtocolException,
 javax.xml.ws.soap.SOAPFaultException,
javax.xml.ws.http.HTTPException

If you need to pass more information back to the client than just the exception message,
you can add additional bean getter and setter methods to the server-side exception,
and the getters can be used at the client.

See Example 4 in the downloads for an example.

The @RequestWrapper and @ResponseWrapper annotations

These annotations are not usually required when starting from Java.

JAX-WS wraps requests, responses, and faults in JAXB beans. You can use these
annotations to customize the name, target namespace, and class name of the generated
JAXB beans and to resolve conflicts if needed. You can resolve conflicts by providing
custom values for the name, target namespace, or class name of the generated JAXB
beans.

As in the earlier example of compensating for an overloaded method, you can change the
bean className, as well as the operationName so the service works correctly.

// use annotations to make this method appear as addInt in WSDL and to

// client.
@WebMethod(operationName=addInt)
@RequestWrapper(className=”sample.addInt”)
@ResponseWrapper(className=”sample.addIntResponse”)
public int add(int a, int b)

@WebMethod()
public int add(int a, float b)

The @WebServiceProvider annotation

Like the @WebService annotation, the @WebServiceProvider annotation is meant to
designate a class as implementing a Web service. However, unlike classes annotated with
@WebService, this class must implement the javax.xml.ws.Provider interface. The
Provider interface provides a means for service implementations that want to work at
the XML message level by removing the abstraction of the Service Endpoint Interface
(SEI). A service implementation with this annotation must implement a strongly typed
Provider interface. This means that the type of Provider interface must be known at
compile time. So for Provider<T>, the type T parameter must be bound to a concrete
class such as Provider<Source> or Provider<SOAPMessage>; it cannot be left unbound
such as, Provider<T> or Provider. The @WebService and @WebServiceProvider
annotations are not allowed on the same class. The example below illustrates an
implementation of the Provider interface, specifically a Provider implementation of the
SOAPMessage type.

@WebServiceProvider
public class HelloProvider implements Provider<SOAPMessage>{
public SOAPMessage invoke(SOAPMessage requestMessage) {…}
}

The @WebServiceProvider annotation has the same parameters (with the same
correspondence to WSDL) as the @WebService annotation, with the exception of the
endpointInterface and name parameters.

WSDL is not generated for provider-based services.

The @ServiceMode annotation

This @ServiceMode annotation is useful for Web services that are implementations of
the javax.xml.ws.Provider interface (that is, annotated with @WebServiceProvider).
This annotation has one parameter with two possible values MESSAGE or PAYLOAD.
@ServiceMode.PAYLOAD indicates that only the message payload (that is, the SOAP
body) will be supplied to the invoke method of the Provider instance.
@ServiceMode.MESSAGE indicates that the entire message protocol (that is, the SOAP
envelope) will be supplied to the invoke method of the Provider instance.

Example 6 in the downloadable samples demonstrates use of the @ServiceMode

annotation.

Deploy a Web service

You can use either Rational Application Developer or the WebSphere Application Server
Toolkit to develop and deploy Web services in a graphical environment. However, for
the purposes of this article and to show more detail, we’ll use the command line in the
following examples. To deploy a Web service, do the following:

1. Compile your implementation classes by issuing the following command:

javac -cp your_classpath -d WEB-INF/classes HelloWorld.java

Your classpath needs to include the following files in WebSphere’s

AppServer\plugins directory:
com.ibm.wsfp.main_6.1.0.jar, org.apache.axis2_6.1.0.jar, and
com.ibm.jaxws.tools_6.1.0.jar.

2. Run \AppServer\bin\wsgen to produce the JAXB classes needed by the service as

shown below:
wsgen -cp your_classpath -d WEB-INF/classes simple.HelloWorld
3. Add the following generic WEB-INF/web.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<web-app id="id"
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://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<display-name>simpleapp</display-name>
</web-app>

This file causes the service to be deployed with defaults inferred from the annotations. In
this convenient form, the same file can be used for any service. For more information on
the customization supported, see Customizing URL patterns in the web.xml file for JAX-
WS applications in the WebSphere Application Server Information Center.

4. Create a WAR file (or an EAR file, if you prefer), as follows:

jar -cf example1.war WEB-INF

5. Deploy the WAR file and start the application through the Application Server
administrative console as you would any other WAR file:
• Select Applications =>Install new application.
• Enter the path to your WAR file.
• Enter a context root (the value used was example1.
• Click Next on each page, then click Finish, then Save.
• Select the checkbox to the left of the application and click Start.

6. Run the service at http://your_server/your_context_root/url_pattern, as shown in

Figure 1:

Figure 1. Run the service

Note that the WSDL file was generated during deployment. You can retrieve it by
appending ?wsdl to the URL.
Develop and deploy a client
1. Run \AppServer\bin\wsimport against the wsdl file to produce the necessary
generated classes, as shown:
C:\tmp\simple\client>wsimport -s .
http://localhost:9080/simple/HelloWorldService/?wsdl

2. Write a client as follows:

package simple;
import javax.jws.*;
public class HelloWorldClient{
public static void main(String [] args){
HelloWorld myPort =
new HelloWorldService().getHelloWorldPort();
System.out.println("invoking service");
String result = myPort.sayHello("hi server");
System.out.println("service returned: " + result); }
}

3. Compile and package it as follows:

javac –d client –cp %clp%;.. HelloWorldClient*java

jar –cf example1client.jar *

4. Run the client. The classpath needs to include

\AppServer\runtimes\com.ibm.jaxws.thinclient_6.1.0.jar.

C:\tmp\simple\client>java -cp
client_classpath samples.example1.HelloWorldClient

invoking service
service returned: Hello, hi server

Note that in the example above, the URL of the WSDL file is fixed in the client-side
classes that were generated by the wsimport tool. With a minor change, you can supply
the URL as an argument to the client, as shown below:

…
// replace line 5 in prior example
System.out.println("using supplied wsdl url: "+ args[0]);
try{
url =new URL(args[0]);
} catch( Exception e){
e.printStackTrace();
}
QName qn = new QName("http://example1.samples/", "HelloWorldService");
myPort = new HelloWorldService(url, qn ).getHelloWorldPort();
…
You can use this same general deployment process for all the samples in this article.

Understanding Web service inheritance, handlers and

more
The following sections provide information beyond the basic description and deployment
considerations for JAX-WS Web service endpoints. First, we discuss inheritance
considerations for annotated endpoints. Next, we’ll show you how to configure handler
chains with the @HandlerChain annotation. Finally, we’ll take a quick look at additional
annotations you can use when describing an endpoint.

Using JAX-WS Web service inheritance

Any object-oriented application will almost undoubtedly take advantage of the useful
feature of Java inheritance. There are special considerations when attempting to use Java
inheritance in Web service endpoints. Let's take a look at the different ways to use Java
inheritance in JAX-WS Web service endpoints in WebSphere Application Server with
the Web Services Feature Pack. First, consider the case of a simple annotated bean that
extends a class:

package simple;
import javax.jws.WebService;
@WebService
public class HelloWorld extends HelloUser {

public void sayHello() { return "Hello!"; } // exposed

}

package simple;
public class HelloUser {

public void sayHelloUser(String userName)

{ return "Hello: " + userName; } // hidden
}

In this example it seems obvious that the Web service endpoint represented by the
HelloWorld class would expose two methods: sayHello and sayHelloUser. However,
this is not the case. The Web service endpoint actually exposes a single method:
sayHello. In order for a JAX-WS Web service implementation class to inherit methods
from its super class, the super class must also be annotated with the @WebService
method. In the example below, the HelloWorld Web service exposes the sayHello and
sayHelloUser methods.

package simple;
import javax.jws.WebService;
@WebService
public class HelloWorld extends HelloUser {

public void sayHello() { return "Hello!"; } // exposed

package simple;
import javax.jws.WebService;
@WebService
public class HelloUser {

public void sayHelloUser(String userName)

{ return "Hello: " + userName; } // exposed

JSR-181 also provides users with a mechanism to prevent an inherited method from
being exposed as a Web service operation on the child class implementation. Consider
the following implementation and super class:

package simple;
import javax.jws.WebService;
@WebService
public class HelloWorld extends HelloUser {

public void sayHello() { return "Hello!"; } // exposed

package simple;
import javax.jws.WebService;
@WebService
public class HelloUser {

public void sayHelloUser(String userName)

{ return "Hello: " + userName; } // exposed

public void sayHelloToAll() { return "Hello All!"; } // exposed

}

In this example, the Web service implementation class HelloWorld exposes three
operations available to clients: sayHello, sayHelloUser, and sayHelloToAll. If you
don’t want to expose the sayHelloToAll method as part of the HelloWorld
implementation, you can use the @WebMethod annotation as follows:

@WebMethod(exclude="true")
public void sayHelloToAll() { return "Hello All!"; } // hidden

This prevents the sayHelloToAll method from being exposed as part of the HelloWorld
Web service endpoint. Another way to prevent the s sayHelloToAll method from being
exposed is to annotate the HelloUser class as follows:

package simple;
import javax.jws.WebService;
@WebService
public class HelloUser {

@WebMethod
public void sayHelloUser(String userName)
{ return "Hello: " + userName; } // exposed

public void sayHelloToAll() { return "Hello All!"; } // exposed

In this example, since the sayHelloUser method is annotated with @WebMethod, it is the
only method exposed by the HelloUser class, thus it is the only method from the
HelloUser class that is exposed by the HelloWorld child class.

Web service inheritance is slightly different in the case where the implementation class
uses a Service Endpoint Interface (SEI). Take the following example:

package simple;
import javax.jws.WebService;
@WebService(endpointInterface="simple.HelloUserSEI")
public class HelloWorld extends HelloUser {

public void sayHello() { return "Hello!"; } // exposed via SEI

package simple;
import javax.jws.WebService;
@WebService
public class HelloUser {

public void sayHelloUser(String userName)

{ return "Hello: " + userName; } // hidden

public void sayHelloToAll() { return "Hello All!"; } // hidden

package simple;
import javax.jws.WebService;
@WebService
public interface HelloUserSEI {
public void sayHello(); // exposed
}

In the case above, it might seem like the HelloUser Web service would expose three
methods: sayHello, sayHelloUser, and sayHelloToAll. However, the SEI is used to
define the contract of the HelloWorld Web service, and as such, only the sayHello
method is actually exposed.
The @HandlerChain annotation
JAX-WS supports the use of handlers that can be invoked before and after a service runs.
You can use the @HandlerChain annotation on a service endpoint to point to a
configuration file, which in turn defines the handler classes and the sequence in which to
run them. You can also use handlers with JAX-WS clients. In addition to using
annotations, you can also do configuration with binding customizations and JAX-WS
APIs (only on the client), as described in Chapters 8 and 9 of the JSR-224 specification.

The only valid annotation parameter for JAX-WS is the path to the handler configuration
file. Below is a simple echo service with attached handlers defined in handlers.xml:
package samples.example5;
import javax.jws.HandlerChain;
import javax.jws.WebService;

@WebService
@HandlerChain(file="handlers.xml")
public class HandlersDemo {
public String echo(String input) {
return("server replies: "+input);
}
}

The file handlers.xml is packaged with the application and its location as specified in the
file parameter is relative to the class file carrying the HandlerChain annotation:
<?xml version="1.0" encoding="UTF-8"?>
<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
<jws:handler-chain name="SimpleChain">
<jws:handler>
<jws:handler-class>
samples.example5.RubberStampHandler
</jws:handler-class>
</jws:handler>
</jws:handler-chain>
</jws:handler-chains>

The configuration file above declares a handler class RubberStampHandler that will run
before and after each call to each service method in the class.
Example 5 in the downloadable samples demonstrates this use of a handler.

The @WebParam annotation

You can use the @WebParam annotation to customize the mappings of the Web method
parameters. In addition to customizing the naming of the parameter, you can use this
annotation to modify the mapping of a particular method parameter as either input only,
output only, or both input and output. You can also use it to indicate that a particular
parameter flows in the SOAP message header rather than the SOAP message body.
The default values for this annotation are somewhat affected by the settings of the
@SoapBinding annotation, described later. The @SoapBinding annotation settings for the
message use and parameter style can affect the name-related parameters of this
annotation. See JSR 181 for more information. Other default values are independent of
the @SoapBinding annotation. The default for input or output mode is IN for non-
Holder<T> types or INOUT for Holder<T> types, and by default the value of the
parameter is sent in the SOAP body rather then the SOAP header.

Input parameters, which are those marked as IN or INOUT, are included in the input
message. Output parameters, which are those marked as OUT or INOUT, are included in
the output message. Note that output parameters use JAX-WS Holder<T> types
(javax.xml.ws.Holder<T>) in order to return values. Also note that output parameters
that are primitives are mapped to the associated “boxed” class for use with Holder<T>.
For example, an output parameter of type int is mapped to Holder<Integer>.

The @WebResult annotation

You can use the @WebResult annotation to customize the mapping of the return value of
a Web method. In addition to customizing the naming of the result, you can also use this
annotation to indicate that the return value flows in the SOAP message header rather than
the SOAP message body.

The default values for this annotation are affected by the settings of the @SoapBinding
annotation, described in the next section. The @SoapBinding annotation settings for the
message use and parameter style affect the name-related attributes on this annotation. See
JSR 181 for more information. Other default values are independent of the
@SoapBinding annotation. By default the return value is sent in the SOAP body rather
than the SOAP header.

The @SoapBinding annotation

The @SoapBinding annotation defines the binding to the SOAP message protocol. You
can use it to define the SOAP message style, use, or parameter style. The SOAP message
style can be either DOCUMENT or RPC, the SOAP message use can be either LITERAL or
ENCODED, and the SOAP message parameter style can be either BARE or WRAPPED. The
SOAP message use of ENCODED is not supported by the Web Services Feature Pack.

The default values are a message style of DOCUMENT, a message use of LITERAL, and a
message parameter style of WRAPPED.

For a detailed discussion of SOAP message style, use and parameter style, including
examples of WSDL and SOAP messages illustrating the various combinations, see the
developerWorks article Which style of WSDL should I use?
Below is a brief and extremely simplified overview of the SOAP message semantics
related to message style and message parameter style values. Note that the following
overview, except as noted for DOCUMENT/BARE, does not consider header parameters or
return values. For more information on header parameters and for the various parameter
types of IN, OUT, and INOUT see the @WebParam annotation. For more information on
header return values, see the @WebResult annotation.

style=RPC, use=LITERAL ParameterStyle=WRAPPED

• Both the input and output messages contain a single element in the SOAP body.
That element has the same name as the operation name and may contain one or
more other elements.

• The element in an input message has the same name as the operation. This is
called the operation element. That element can contain child elements that
correspond to the IN and INOUT parameters for the operation.

• The element in an output message has the same name as the operation appended
with “Response”. That element can contain a child element corresponding to a
return value (if any) as the first element, followed by elements for the INOUT and
OUT parameters.

• Note that the parameter parameterStyle does not affect RPC. RPC uses the
default value of WRAPPED. The input and output messages contain a single
element based on the operation name and that element may contain one or more
child elements for parameters and the return value.

style=DOCUMENT, use=LITERAL ParameterStyle=WRAPPED

• Both the input and output messages contain a single element in the SOAP body.
The element is named based on the operation name and can contain one or more
other elements.

• The element in an input message has the same name as the operation. That
operation element can contain child elements that correspond to the IN and INOUT
parameters for the operation.

• The element in an output message has the same name as the operation appended
with “Response”. That element can contain a child element corresponding to the
the return value (if any) as the first element, followed by elements the INOUT and
OUT parameters.

style=DOCUMENT, use=LITERAL, ParameterStyle=BARE

• The input and output message do not contain an operation element. Instead the
SOAP body contains zero or more elements representing the parameters of the
operation. The lack of an operation element is why this is called BARE.
 • The element in an input message has the same name as the single non-header
input parameter, which can be of type IN or INOUT.

• The element in an output message has the same name as the operation appended
with “Response” for a return value. If the operation is a void and has no return
value, the message will have the same name as the single non-header output
parameter, which can be of type OUT or INOUT.

You can specify the @SoapBinding annotation on a Type or a Method. However, it is

valid on a Method only if the message style is DOCUMENT. If the annotation is not specified
on a Method, then that method inherits the values from the Type-level annotation

The @SoapBinding annotation is only valid for binding types of SOAP 1.1 or SOAP 1.2,
either with or without MTOM enabled. See the @BindingType annotation for
information on the type of the binding.

The @BindingType annotation

This JSR-224 annotation specifies the binding of a JAX-WS endpoint implementation.
The endpoint implementation can be bound to either SOAP 1.1 over HTTP (with or
without MTOM enabled), SOAP 1.2 over HTTP (without or without MTOM enabled), or
XML over HTTP. Note that this annotation is valid only on endpoint implementations
(that is, service providers). Since service requesters can’t use this annotation, they must
specify the binding and whether MTOM is enabled in a different manner, described
briefly below.

The default value if this annotation is a binding of SOAP 1.1 over HTTP without MTOM
enabled. Valid values for bindings and the enablement of MTOM are defined as constants
as follows:

• SOAP 1.1 over HTTP without MTOM enabled (default):

javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING

• SOAP 1.1 over HTTP with MTOM enabled:

javax.xml.ws.soap.SOAPBinding. SOAP11HTTP_MTOM_BINDING

• SOAP 1.2 over HTTP without MTOM enabled:

javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING

• SOAP 1.2 over HTTP with MTOM enabled:

javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING

• XML over HTTP: javax.xml.ws.http.HTTPBinding.HTTP_BINDING

Note that if WSDL is not provided with the endpoint, it will be generated only for
endpoints bound to SOAP 1.1; WSDL will not be generated for endpoints bound to
SOAP 1.2 or XML. That means that if an endpoint is deployed without WSDL, it must be
bound to SOAP 1.1 in order to be able to generate WSDL in response to a ?WSDL request.
Endpoints that are deployed with WSDL are not restricted to the SOAP 1.1 binding in
order to respond to a ?WSDL request, because the WSDL was provided with the endpoint
and does not need to be generated.

As noted above, the @BindingType annotation can be used only on endpoint

implementation classes (that is, service providers); it can’t be used on the service
requester. The method for changing the binding of a service requester depends on the
type of port used by the service requester; the method for enabling MTOM is the same
regardless of the type of port used. Note that the default binding type for a service
requester is the same as for a service provider: SOAP 1.1 over HTTP without MTOM
enabled.

1. To change the binding from the default SOAP 1.1 over HTTP to either SOAP 1.2
over HTTP or XML over HTTP do the following:

• For dynamic ports, which are ports that are added using
Service.addPort(QName portName, String bindingId, String
endpointAddress), the binding is specified as the second parameter when the
port is added. Note that the values used to set the binding are the same constants
described above as valid values for the @BindingType annotation.

• For non-dynamic ports, the WSDL must be provided and the binding extensibility
element in the WSDL must indicate the type of binding, either the SOAP 1.2 or
HTTP (that is, XML over HTTP), via its namespace. Values for WSDL binding
extensibility namespace are as follows: (Note that these values are different from
the values used on the @BindingType annotation and for the Service.addPort
method described above.)
• SOAP 1.1 (default): http://schemas.xmlsoap.org/wsdl/soap/
• SOAP 1.2: http://schemas.xmlsoap.org/wsdl/soap12/
• HTTP (which indicates a binding type of XML over HTTP):
http://schemas.xmlsoap.org/wsdl/http/

For example, to indicate a SOAP 1.2 binding in the WSDL:

<definitions
targetNamespace="http://jaxws.axis2.apache.org/proxy/soap12"
...
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/">
...
<binding name="EchoBinding" type="tns:Echo">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>

2. To enable MTOM on the service requester, the Binding instance is obtained from
the Proxy or the Dispatch, then MTOM is enabled on that instance via
 binding.setMTOMEnabled(true). For examples of enabling MTOM on both the
endpoint and the service requester, see the section Enabling MTOM for JAX-WS
Web services in the WebSphere Application Server Information Center.

Summary
In this article, you’ve learned how you can use annotations to construct and customize
Web services starting from Java using the WebSphere Application Server V6.1 Feature
Pack for Web Services. Using this approach to Web service development allows you
focus on the Java code and reduces or eliminates the need to customize deployment
descriptors and WSDL files.

Resources

• JSR 224: Java API for XML-Based Web Services (JAX-WS) 2.0: Get the
specification.

• JSR 181: Web Services Metadata for the java Platform: Get the specification.

• JSR 222: Java Architecture for XML Binding (JAXB) 2.0: Get the specification.

• SOAP Message Transmission Optimization Mechanism (MTOM): Read the

recommendation.

• Web Services Description Language (WSDL) 1.1: Read the specification.

• javax.xml.ws: API documentation.

• javax.jws: API documentation.

• javax.jws.soap: API documentation.

• IBM WebSphere Application Server V6.1 Feature Pack for Web Services:
Download the Feature Pack and documentation.

• Application Server Toolkit Update for Web Services Feature Pack: Download the
Web Services Feature Pack update to the Application Server toolkit.

About the authors

Bruce Tiffany is an Advisory Software Engineer with IBM in Austin, Texas. He is a
Functional Verification Tester of the WebSphere Application Server Web Services
component. You can reach Bruce at btiffany@us.ibm.com.

Jeff Barrett is an Advisory Software Engineer at IBM in Austin, Texas. He is a

developer for the WebSphere Application Server Web Services component. You can
reach Jeff at barrettj@us.ibm.com.

Dustin Amrhein is a Staff Software Engineer with IBM in Austin, Texas. He is a

developer for the WebSphere Application Server Web Services component. You can
reach Dustin at damrhei@us.ibm.com.