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, 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. You can also selectively annotate individual methods with the @WebMethod annotation to control their exposure as web services operations.

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 basic web service, annotate the implementation class with the @WebService annotation.
  • To define your web services using an explicit SEI, explicitly reference a Java interface class using the endpointInterface attribute of the @WebService annotation.
  • Provide a reference to a WSDL file in the wsdlLocation attribute of the @WebService annotation. By specifying a pre-defined WSDL file, performance is improved. Also, discrepancies between the WSDL file and the annotations are reported to you by the runtime environment.
    Avoid trouble: According to the JAX-WS 2.2 specification, if SOAP 1.2 is declared as the binding type and the wsdlLocation attribute is empty string, which is the default, the container cannot generate the WSDL automatically. So if you use ?wsdl to request the WSDL file, the following exception message is displayed:
    CWWKW0037E: The WSDL that is compliant with the JAX-WS 2.2 specification cannot be generated.
    If you want to display the WSDL file, you must manually generate the WSDL file, put it in the application and specify the wsdlLocation attribute with the correct location.
  • 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.
  • Providing a reference in the @WebService annotation to an explicit SEI or to an existing WSDL file helps to remove possible ambiguities when exposing methods.
  • If you do not use an explicit 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 that are not static or final.
    • If you want more granular control to expose only certain methods, use the @WebMethod annotation on selected methods. 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 @WebMethod(exclude=true) annotation.
Behavior change for exposing methods that are not annotated:

The behavior of JAX-WS has changed regarding exposing methods as web services operations. This complies with recent clarifications to JAX-WS specifications.

Applications without an explicit SEI or WSDL that are migrated from prior versions might have additional operations exposed as the following shows. You can set a property so the JAX-WS runtime environment uses the legacy behavior. You might need this when migrating applications without a WSDL or an SEI so that additional methods are not exposed.

@WebService
public class Foo {
	@WebMethod
	public void a() {}	// exposed now, exposed before
	public void b() {}	// exposed now, not exposed before
}
Using the new interpretation, public methods in an implementation class and its superclasses are only exposed under the following conditions:
  • The containing class has an @WebService annotation.
  • The method does not have an @WebMethod(exclude=true) annotation.
Using the legacy interpretation, a method in an implementation class and its superclasses are only exposed under the following conditions:
  • The containing class has an @WebService annotation.
  • The method has no @WebMethod annotations AND no other methods have @WebMethod annotations.
  • The method has an @WebMethod or @WebMethod(exclude=false) annotation.

To specify that the JAX-WS runtime environment use the legacy @WebMethod behavior, configure the jaxws.runtime.legacyWebMethod=true property. You can configure this property as a Java Virtual Machine (JVM) system property or as a property in the META-INF/MANIFEST.MF file of a web application archive (WAR) file. By default, this property is set to false and the application server uses the new behavior.

You might encounter a WSWS7054E error message if all of the following conditions are true:
  • Your web service application consists of unannotated methods.
  • The methods are not meant to be mapped to a web service operation.
  • Your application does not reference an SEI nor package a WSDL file.
The error message contains information that is similar to the following text: 
javax.xml.ws.WebServiceException: WSWS7054E:
 The Web Services Description Language (WSDL) file could not be generated for the XXXX Web service implementation
 class because of the following error: javax.xml.ws.WebServiceException: Unable to create JAXBContext
The JAX-WS tooling complies with the JAX-WS specification with respect to @WebMethod mapping principles. This change might affect applications that have been dependent on previously non-compliant default behavior. If your applications package and reference WSDL or an SEI and have ALL methods correctly annotated with the @WebMethod exclude flag in the SEI implementation, then this change does not affect you. However, if you are affected, add explicit annotations to your methods to ensure that they are excluded in WSDL generation. For example: @WebMethod(exclude=true) Also, you can package a WSDL with your application to eliminate the need for the run time to generate a WSDL on your behalf.
Behavior change for exposing static and final methods:

Static or final methods in a service without an explicit SEI are no longer exposed as web services operations. To expose them, package the WSDL with the application and set jaxws.runtime.legacyWebMethod=true.

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 in applications without 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 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 or higher 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.

Be sure to regenerate your client side artifacts any time you receive an updated WSDL file.

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.
  • Set the jaxws.runtime.legacyWebMethod property to false to ensure that all operations in the WSDL are dispatched.

What to do next

Develop Java artifacts for JAX-WS applications from JavaBeans.