Developing deployment descriptors for a JAX-WS client

Deployment descriptors are standard text files, formatted using XML and packaged in a Web services application. You 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.

Before you begin

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

About this task

You 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 that is used by a Java EE component in Web, Enterprise JavaBeans™ (EJB) or application client containers. A service-ref entry has a JNDI name that is used to lookup the service. Specifying the service-ref entry enables the client applications to locate the service using a JNDI lookup and you 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 binding a JAX-WS service into JNDI, use the javax.xml.ws.Service subclass that is generated by the wsimport tool as the service-interface value. This is the class that contains the @WebServiceClient annotation. When binding a JAX-WS port into the namespace, 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.

Procedure

  1. Define the service-ref entry in the your application-client.xml, web.xml, or ejb-jar.xml deployment descriptors.
    For example, suppose a Web 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 your Web services client application to customize your application. The following code fragments are examples of how your 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;

Results

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

What to do next

Complete the client implementation by writing your client application code that is used to invoke the Web service.




In this information ...


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 10:04:34 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-mp&topic=twbs_jaxwsclientdd
File name: twbs_jaxwsclientdd.html