9-16 Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
9.6 Creating the Handler Chain Configuration File
If you decide to use the HandlerChain annotation in your JWS file to associate a handler chain with a Web service, you must create an external configuration file that
specifies the list of handlers in the handler chain, the order in which they execute, the initialization parameters, and so on.
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. Finally, if you
include handlers in your handler chain that use a non-SOAP transport, then you are required to use the HandlerChain annotation rather than the
SOAPMessageHandler
annotation. The configuration file uses XML to list one or more handler chains, as shown in the
following simple example: jwshc:handler-config xmlns:jwshc=http:www.bea.comxmlnsjws
xmlns:soap1=http:HandlerInfo.orgServer1 xmlns:soap2=http:HandlerInfo.orgServer2
xmlns=http:java.sun.comxmlnsj2ee jwshc:handler-chain
jwshc:handler-chain-nameSimpleChainjwshc:handler-chain-name jwshc:handler
handler-namehandler1handler-name handler-classexamples.webservices.soap_handlers.global_
handler.ServerHandler1handler-class jwshc:handler
jwshc:handler handler-namehandler2handler-name
handler-classexamples.webservices.soap_handlers.global_ handler.ServerHandler2handler-class
jwshc:handler jwshc:handler-chain
jwshc:handler-config
In the example, the handler chain called SimpleChain contains two handlers: handler1
and handler2, 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, soap-role, and soap-header child elements of the
handler element to specify the handler initialization parameters, SOAP roles
implemented by the handler, and SOAP headers processed by the handler, respectively.
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
.
9.7 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
Creating and Using SOAP Message Handlers 9-17
With JAX-RPC 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 either the HandlerChain or SOAPMessageHandlers
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.
■
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 or
SOAPMessageHandlers annotations 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.
9.8 Creating and Using Client-Side SOAP Message Handlers