Developing deployment descriptors for a JAX-WS client

Deployment descriptors are standard text files, formatted using XML and packaged in a web services application. We can optionally use the Web Services for Java Platform, Enterprise Edition (Java EE) specification (JSR 109) service reference deployment descriptor to augment or override application metadata specified in annotations within Java API for XML-Based Web Services (JAX-WS) web services client.

We must first generate the web services client artifacts from a Web Services Description Language (WSDL) file using the wsimport command.

We can add service-ref entries within the application-client.xml, web.xml, or ejb-jar.xml Java EE deployment descriptors. A service-ref entry represents a reference to a web service used by a Java EE component in Web, EJB or application client containers. A service-ref entry has a JNDI name used to lookup the service. Specifying the service-ref entry enables the client applications to locate the service using a JNDI lookup and we can also use these service references for resource injection.

For each service-ref entry found in one of the deployment descriptors, the corresponding service object is bound into the JNDI namespace and the port information is included, if specified. The JAX-WS client can now perform a JNDI lookup to retrieve either a JAX-WS service or port instance.

When defining a service-ref that represents a JAX-WS service, use the javax.xml.ws.Service subclass that is generated by the wsimport tool as the service-interface value. This is the class containing the @WebServiceClient annotation. When defining a service-ref that represents a JAX-WS port, the service-interface value is still the javax.xml.ws.Service subclass generated by the wsimport tool, and the service-ref-type value specifies the service endpoint interface (SEI) class used by the port. The SEI class is also generated by wsimport, and it is annotated with the @WebService annotation.

Tasks

1. Define the service-ref entry in the application-client.xml, web.xml, or ejb-jar.xml deployment descriptors.

   For example, suppose a web application archive (WAR) file contains a WEB-INF/web.xml deployment descriptor that includes the following service-ref entries:

   <service-ref>
     <service-ref-name>service/ExampleService</service-ref-name>
     <service-interface>com.ibm.sample.ExampleService</service-interface>
   </service-ref>
   
   <service-ref>
     <service-ref-name>service/ExamplePort</service-ref-name>
     <service-interface>com.ibm.sample.ExampleService</service-interface>
     <service-ref-type>com.ibm.sample.ExamplePort</service-ref-type>
   </service-ref>
   
   <service-ref>
     <service-ref-name>service/ExamplePortInjected</service-ref-name>
     <service-interface>com.ibm.sample.ExampleService</service-interface>
     <service-ref-type>com.ibm.sample.ExamplePort</service-ref-type>
   
     <injection-target>
       <injection-target-class>com.ibm.sample.J2EEClient</injection-target-class>
       <injection-target-name>injectedPort</injection-target-name>
     </injection-target>
   </service-ref>
   

   In this example, com.ibm.sample.ExampleService is a generated JAX-WS service class and this class must be a subclass of javax.xml.ws.Service. Additionally, the ExampleService.getPort() method returns an instance of com.ibm.sample.ExamplePort.

2. Use the deployment descriptors within the web services client application to customize the application. The following code fragments are examples of how the client application can use the service-ref entries within the WAR module:

   import javax.xml.ws.Service;
   import com.ibm.sample.ExampleService;
   import com.ibm.sample.ExamplePort;
   
   // Create an InitialContext object for doing JNDI lookups.
   InitialContext ic = new InitialContext();
   
   // Client obtains an instance of the generic service class using JNDI.
   Service genericService =
   (Service) ic.lookup("java:comp/env/service/ExampleService");
   
   // Client obtains an instance of the generated service class using JNDI.
   ExampleService exampleService =
   (ExampleService) ic.lookup("java:comp/env/service/ExampleService");
   
   // Client obtains an instance of the port using JNDI.
   ExamplePort ExamplePort =
   (ExamplePort) ic.lookup("java:comp/env/service/ExamplePort");
   
   // The container injects an instance of ExamplePort based on the client deployment descriptor
   private ExamplePort injectedPort;
   

We can now use the service references that were defined in the deployment descriptor within the client application. Additionally, we can use deployment descriptors to augment or override information specified by @WebServiceRef or @Resource annotations.

The <lookup-name> deployment descriptor element is new in Java EE 6, and is used to indirectly refer to an already-defined service reference. When the <lookup-name> element is used, only the <service-ref-name> element may also be specified, and no other child elements of <service-ref> may be defined.

The following example shows a service-ref entry within a WEB-INF/web.xml file which defines a reference to a JAX-WS service, as well as a service-ref entry within the same web.xml file which defines an indirect reference to the first service-ref:

<service-ref>
  <service-ref-name>service/ExampleService</service-ref-name>
  <service-interface>com.ibm.sample.ExampleService</service-interface>
  <service-ref-type>com.ibm.sample.ExampleServicePortType</service-ref-type>
  <wsdl-file>WEB-INF/wsdl/ExampleService.wsdl</wsdl-file>
</service-ref>

<service-ref>
  <service-ref-name>service/ExampleService2</service-ref>
  <lookup-name>java:comp/env/service/ExampleService</lookup-name>
</service-ref>

Assuming the previous service-refs are defined in the WEB-INF/web.xml file, the client application could perform a JNDI lookup using the name java:comp/env/service/ExampleService2, and the result would be a reference to the ExampleService service defined in the WSDL document WEB-INF/wsdl/ExampleService.wsdl, as defined in the first service-ref.

What to do next

Complete the client implementation by writing the client application code used to invoke the web service.

Related:

JAX-WS

JAX-WS client programming model

Implement static JAX-WS web services clients

Web services specifications and APIs