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 Receives an exception, which may have a different derived name

FooException.getStackTrace returns server side trace

“derived_name”.getStackTrace returns client side trace

getCause returns cause getCause returns null

Getters are called directly, such as FooException.getSomething()

Getters are called via “derived_name”.getFaultInfo().getSomething()

Throws an unchecked Exception 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 ing echo(String input) { Str 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.