Compiling and Rebuilding the Web Service

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