Enforcing adherence to WSDL bindings in JAX-WS web services

Java API for XML-Based Web Services (JAX-WS) v2.1 introduced the concept of features as a way to programmatically control specific functions and behaviors. The RespectBindingFeature is one of the supported standard features. Use the RespectBindingFeature to control whether a JAX-WS implementation is required to respect the contents of a Web Services Description Language (WSDL) binding associated with an endpoint.

While WSDL documents are often used during the development process, the actual enforcement of the use of the WSDL document specifications, when they are provided, at run time has not been well defined in versions of the JAX-WS specification previous to v2.1. The JAX-WS Version 2.1 specification added the feature, RespectBindingFeature, to clarify the impact of the wsdl:binding in a JAX-WS runtime environment.

Enable the feature, RespectBindingFeature, causes the JAX-WS runtime environment to inspect the wsdl:binding for an endpoint at run time to ensure that the binding of service endpoint interface (SEI) parameters and return values is respected. Additionally, this feature ensures that all required wsdl:binding extensions are either understood and used by the runtime environment, or the extensions have been explicitly disabled by the application. Your JAX-WS application can disable a specific wsdl:binding extension that has a defined WebServiceFeature interface using the appropriate annotation associated with that feature, using an API that accepts the javax.xml.ws.WebServiceFeature interface, or configuring the deployment descriptors.

When the RespectBindingFeature feature is not enabled, which is the default, the runtime environment can choose whether any part of the wsdl:binding is enforced.

Tasks

1. Develop Java artifacts for our JAX-WS application that includes a Web Services Description Language (WSDL) file that represents the web services application.

   1. If we are starting with a WSDL file, develop Java artifacts from a WSDL file using the wsimport command to generate the required JAX-WS portable artifacts.

   2. If we are starting with JavaBeans components, develop Java artifacts for JAX-WS applications and generate a WSDL file using the wsgen command.

2. To enable RespectBindingFeature on your endpoint implementation class, use one of the following methods:

   • Use the @RespectBinding annotation on the endpoint.

     To enable RespectBinding on an endpoint, use the @RespectBinding (javax.xml.ws.RespectBinding) annotation on the endpoint. The @RespectBinding annotation has only one parameter, enabled. Optional. The enabled parameter has a Boolean value and indicates if RespectBindingFeature is enabled for the JAX-WS endpoint.

     The following example snippet illustrates adding the @RespectBinding annotation for the JAX-WS MyServiceImpl endpoint:

     @RespectBinding(enabled=true))
     @WebService
     public class MyServiceImpl {
     ...
     }
     

   • Use the <respect-binding> deployment descriptor element.

     Use the <respect-binding> element within the <port-component> element in the webservices.xml deployment descriptor as an alternative to using the @RespectBinding annotation on the service endpoint implementation class; for example:

     <port-component>
          <port-component-name>MyPort1</port-component-name>
          <respect-binding>
              <enabled>true</enabled>
          </respect-binding>
          <service-impl-bean>
              <servlet-link>MyPort1ImplBean</servlet-link>
          </service-impl-bean>
     </port-component>
     

3. To enable RespectBindingFeature on the client, use one of the following methods:
   • Enable RespectBindingFeature on a dispatch client; for example:

     RespectBindingFeature respectBinding = new RespectBindingFeature();
     Service svc = Service.create(serviceName);
     svc.addPort(portName, SOAPBinding.SOAP11_HTTP_BINDING, endpointUrl);
     Dispatch<Source> dsp = svc.createDispatch(portName, Source.class, Service.Mode.PAYLOAD, respectBinding);
     

   • Enable RespectBindingFeature on a dynamic proxy client; for example:

     // Create a dynamic proxy with RespectBinding enabled.
       Service svc = Service.create(serviceName);
       RespectBindingFeature respectBinding = new RespectBindingFeature();
       RespectBindingSample proxy = svc.getPort(portName, RespectBindingSample.class, respectBinding);
     

   • Enable RespectBindingFeature on the client using the @RespectBinding annotation; for example:

     public class MyClientApplication {
     
                    // Enable RespectBinding for a port-component-ref resource injection.
                        @RespectBinding(enabled=true)
                        @WebServiceRef(MyService.class)
                        private MyPortType myPort;
                    ...
     }
     

   • Enable RespectBindingFeature on the client using deployment descriptor elements within a port-component-ref element; for example:

     <service-ref>
         <service-ref-name>service/MyPortComponentRef</service-ref-name>
         <service-interface>com.example.MyService</service-ref-interface>
         <port-component-ref>
             <service-endpoint-interface>com.example.MyPortType</service-endpoint-interface>
             <respect-binding>
                 <enabled>true</enabled>
             </respect-binding>
         </port-component-ref>
     </service-ref>
     

By implementing the feature, RespectBindingFeature, you have specified to enforce adherence of the contents of a WSDL binding associated with an endpoint for our JAX-WS application.

Implement web services applications with JAX-WS

Implement web services applications from existing WSDL files with JAX-WS

JAX-WS annotations

Web services specifications and APIs