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
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 that contains 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.
Procedure
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.
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 your client application code that is used to invoke the web service.