Creating and Using SOAP Message Handlers 15-13
Because this file is external to the JWS file, you can configure multiple Web services to use this single configuration file to standardize the handler configuration file for all
Web services in your enterprise. Additionally, you can change the configuration of the handler chains without needing to recompile all your Web services.
The configuration file uses XML to list one or more handler chains, as shown in the following simple example:
?xml version=1.0 encoding=UTF-8? handler-chains xmlns=http:java.sun.comxmlnsjavaee
handler-chain handler
handler-classexamples.webservices.handler.Handler1handler-class handler
handler-chain handler-chain
handler handler-classexamples.webservices.handler.Handler2handler-class
handler handler-chain
handler-chains
In the example, the handler chain contains two handlers implemented with the class names specified with the handler-class element. The two handlers execute in
forward order before the relevant Web service operation executes, and in reverse order after the operation executes.
Use the init-param and soap-rolechild elements of the handler element to specify the handler initialization parameters and SOAP roles implemented by the
handler, respectively.
You can include logical and SOAP handlers in the same handler chain. At runtime, the handler chain is re-ordered so that all logical handlers are executed before SOAP
handlers for an outbound message, and vice versa for an inbound message.
For the XML Schema that defines the external configuration file, additional information about creating it, and additional examples, see the Web services Metadata
for the Java Platform specification at http:www.jcp.orgenjsrdetail?id=181
.
15.8 Compiling and Rebuilding the Web Service
It is assumed in this section that you have a working build.xml Ant file that compiles and builds your Web service, and you want to update the build file to
include handler chain. See Developing WebLogic Web Services in Getting Started With JAX-WS Web Services for Oracle WebLogic Server for information on creating this
build.xml file.
Follow these guidelines to update your development environment to include message handler compilation and building:
■
After you have updated the JWS file with the HandlerChain annotation, you must rerun the jwsc Ant task to recompile the JWS file and generate a new Web
service. This is true anytime you make a change to an annotation in the JWS file.
If you used the HandlerChain annotation in your JWS file, reran the jwsc Ant task to regenerate the Web service, and subsequently changed only the external
configuration file, you do not need to rerun jwsc for the second change to take affect.
15-14 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server
■
The jwsc Ant task compiles SOAP message handler Java files into handler classes and then packages them into the generated application if all the following
conditions are true:
– The handler classes are referenced in the HandlerChain annotation of the
JWS file.
– The Java files are located in the directory specified by the sourcepath
attribute.
– The classes are not currently in your CLASSPATH.
If you want to compile the handler classes yourself, rather than let jwsc compile them automatically, ensure that the compiled classes are in your CLASSPATH
before you run the jwsc Ant task.
■
You deploy and invoke a Web service that has a handler chain associated with it in the same way you deploy and invoke one that has no handler chain. The only
difference is that when you invoke any operation of the Web service, the WebLogic Web services runtime executes the handlers in the handler chain both before and
after the operation invoke.
15.9 Configuring the Client-side SOAP Message Handlers
