Exposing methods in SEI-based JAX-WS Web services

You can use the @WebService and @WebMethod annotations on a service endpoint implementation to specify Java™ methods that you want to expose as Java API for XML-Based Web Services (JAX-WS) Web services.

Before you begin

JAX-WS technology enables the implementation of Web services based on both the standard service endpoint interface and a Provider interface. When developing a JAX-WS Web service starting from existing Java classes, known as the bottom-up approach, you must annotate the class with either the @WebService or @WebServiceProvider annotation to initially define the class as a Web service.

Using the Provider interface is the dynamic approach to defining your JAX-WS services. To use the Provider interface, your class must implement the javax.xml.ws.Provider interface, and contain the @WebServiceProvider annotation. The Provider interface has one method, the invoke method, which uses generics in the Java programming language to control both the input and output types when working with various messages or message payloads.

In contrast, this topic describes how you can use Java annotations to describe your Web services using the service endpoint interface (SEI) approach.

About this task

To initially define a Web service, annotate the Java class with the @WebService annotation. However, you can also selectively annotate the individual methods with @WebMethod annotation to control how these methods are exposed as Web services operations.

Using a combination of @WebService and @WebMethod annotations, you can easily describe your Web service because you control which methods are exposed.

Because of ambiguities across multiple Web services specifications regarding how methods are exposed as operations, use the following guidelines to help ensure consistent behavior regardless of the JAX-WS implementation that you use.

To define a class as an SEI-based Web Service, you must add the @WebService annotation to the implementation class. Providing a reference to an explicit SEI (interface) or a reference to an existing WSDL file in your service endpoint implementation class helps to remove possible ambiguities when exposing methods.

Best practice: Use the following best practices for defining Web services:
  • To define a basic Web service, annotate the Java class with the @WebService annotation.
  • To define your Web services using an explicit SEI, add the @WebService annotation to a Java implementation class and explicitly reference a Java interface using the @WebService.endpointInterface attribute.
  • To define your Web services using an implicit SEI, add the @WebService annotation to a Java implementation class and do not define the @WebService.endpointInterface attribute.
  • Provide a reference to a WSDL file in the @WebService.wsdlLocation attribute. By specifying a pre-defined WSDL file, performance is improved. Additionally, any discrepancies between the WSDL file and the annotations are reported to you by the runtime environment.
  • When you use an explicit SEI, all public methods in the SEI and inherited classes are always exposed. You only need to add @WebMethod annotations if you want to further customize the methods that are already exposed.
  • If you define an implicit SEI, follow these rules to ensure that your methods are exposed consistently:
    • Add an @WebService annotation to your implementation class and all its superclasses that contain methods that you want to expose. Adding an @WebService annotation to a class exposes all public methods in that class.
    • If you want more granular control and expose only certain methods from a class that is annotated with the @WebService annotation, you can use the @WebMethod annotation on selected individual methods. The @WebMethod.exclude attribute is one of the criteria that is used to determine whether a method is exposed as an operation. The default value for this attribute is false. To ensure that a method is exposed, annotate it with the @WebMethod annotation. If you want to make sure that a method is not exposed, annotate it with the @WebService(exclude=true) annotation.
bprac
[Solaris] [HP-UX] [Fix Pack 7 or later]
Behavior change for exposing methods

Beginning with Sun and HP JDK Version 1.6 containing JAX-WS tooling Version 2.1.6, the behavior of the JAX-WS runtime environment and tooling has changed how it interprets the JAX-WS specification regarding exposing methods as Web services operations. When the Web service does not specify a pre-existing WSDL file, the JAX-WS tooling behavior that generates a WSDL file has changed. This change does not affect Web services that reference a WSDL file. The change in semantics might affect Web services that do not reference a WSDL file or a SEI, and they rely on the JAX-WS runtime environment to create a WSDL file. Also, if you apply the best practices described previously in this document, the interpretation change does not affect your applications regardless of whether a WSDL file or SEI is referenced.

Using the new interpretation, a method in an implicit SEI and its superclasses are only exposed under the following conditions:
  • The method has an @WebMethod or @WebMethod(exclude=false) annotation.
  • The method has no @WebMethod annotations, but the containing class has an @WebService annotation.
In contrast, using the legacy interpretation, a method in an implicit SEI and its superclasses are only exposed under the following conditions:
  • The method has an @WebMethod or @WebMethod(exclude=false) annotation and the containing class has an @WebService annotation.
  • The method has no @WebMethod annotations, but the containing class has a @WebService annotation and no other methods have @WebMethod or @WebMethod(exclude=false) annotations on it.

To prevent any security or migration exposures to existing WebSphere® Application Server applications, the JAX-WS runtime environment uses the legacy behavior so that new operations are not automatically exposed. For application server environments using both Version 7.0.0.7 and JAX-WS tooling Version 1.6, a new property is supported by the JAX-WS runtime environment. This new property specifies whether to use the legacy behavior, or the new behavior. By default, the JAX-WS runtime environment uses the legacy behavior for the @WebMethod annotation.

To specify that the JAX-WS runtime environment to use the legacy @WebMethod annotation behavior, configure the jaxws.runtime.legacyWebMethod=true property. You can configure this property as a Java Virtual Machine (JVM) system property. By default, this property is set to true and the application server uses the legacy behavior for the @WebMethod annotation.

To specify that the JAX-WS runtime environment to use the new @WebMethod annotation behavior, configure the jaxws.runtime.legacyWebMethod=false property. You can configure this property as a Java Virtual Machine (JVM) system property.

Procedure

  1. Identify the methods that you want to expose as Web services operations.
  2. Review the rules for exposing methods as operations on classes annotated with the @WebService annotation.
  3. Use the best practices for applying the @WebMethod and @WebService annotations to implicit SEIs to appropriately expose methods as operations within your Web services.

Results

You have used the @WebMethod annotation to specify which methods to expose as Web services operations.

Avoid trouble:

If you have upgraded your application server environment to include Sun or HP JDK 1.6 and you are experiencing problems, review the following troubleshooting information.

Client errors indicate a mismatch between the WSDL file and portType when using a JAX-WS tooling version 2.1.6 environment
You might receive a client-side error message like the following message:
javax.xml.ws.WebServiceException: The Endpoint validation failed to validate due to the following errors:
:: Invalid Endpoint Interface ::
:: The number of operations in the WSDL portType does not match the number of methods in the SEI or Web service
 implementation class.  wsdl operations = [...] dispatch operations = [....]

To correct this problem, you must regenerate client artifacts to match the WSDL file.

Best practice: Be sure to regenerate your client side artifacts any time you receive an updated WSDL file. bprac
Clients that perform a ?WSDL operation on Web services have non-dispatchable operations
After performing a ?WSDL operation, you might receive a WSDL file that contains more operations than the JAX-WS runtime environment can dispatch. If the client tries to invoke any of the non-dispatchable operations, the client receives an error like the following message:
The endpoint reference (EPR) for the Operation not found is http://localhost:9086/example/BeanImpl2Service and the WSA Action = <WSA_action_from_server>. If this EPR was previously reachable, contact the server administrator.
Clients must only access the operations that the Web service intends to expose. You can correct this problem in one of the following ways:
  • Modify the @WebMethod annotations in the Web services application so that the resulting WSDL file exposes the correct set of operations.
  • [Solaris] [HP-UX] [Fix Pack 7 or later] Configure the application server to set the jaxws.runtime.legacyWebMethod property to true to ensure that the application server uses the legacy behavior for the @WebMethod annotation.
gotcha

Example [Solaris] [HP-UX] [Fix Pack 7 or later]

The following example illustrates the difference in behavior for the @WebMethod annotation based on the value of the jaxws.runtime.legacyWebMethod property for this sample service endpoint implementation file.

================================= 
public class Base {
@WebMethod(exclude=false)
public void superMethod1(String s) {...}
public String superMethod2(String s) {...}
================================= 
@WebService(targetNamespace="foo")
public class BeanImpl extends Base {
@WebMethod(exclude=false)
public void method1(String s) {...}
public String method2(String s) {...}
=================================
If the org.apache.axis2.jaxws.runtime.legacyWebMethod property is set to true, the following methods are exposed using the generated WSDL file or the @WebMethod behavior:
method1(String s) {...}
If the org.apache.axis2.jaxws.runtime.legacyWebMethod property is set to false, the following methods are exposed using the generated WSDL file or the @WebMethod behavior:
method1(String s) {...}
method2(String s)  {...}
superMethod1(String s)  {...}

What to do next

Develop Java artifacts for JAX-WS applications from JavaBeans™.




In this information ...


Related reference

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic    

Terms of Use | Feedback

Last updated: Oct 21, 2010 7:37:48 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v701sca&product=was-nd-mp&topic=twbs_devjaxws_exposewebmethod
File name: twbs_devjaxws_exposewebmethod.html