Contents

• Overview
• Quick Start
• Step By Step

This example shows how to develop a Web Service that uses Handlers in the JAX-RPC API. Handlers are classes that act as pre-processors and post-processors of SOAP Messages. A Handler is assembled into a chain of handlers known as a Handler Chain.

This example illustrates the use of Handlers in a Handler Chain with a simple Bank Service demo. The Web Service is implemented by the BankBean class. The service interface - BankBeanInterface - which is implemented by BankBean, exposes 5 methods to the Web Service. These methods are: deposit, withdraw, createAccount, getBalance, and getAccountID. The web service has 3 handlers:

• NewAccountHandler - This handler examines the SOAP Message to ensure that a bank account is created with an initial balance greater than $0. If there is an attempt to create an account with an invalid balance, the handler will throw a fault, and no account will be created.
• AccountWithdrawalHandler - This handler examines the SOAP Message to ensure that an account holder always withdraws less than the maximum amount of funds allowed. If an attempt is made to withdraw more than the maximum amount, this handler will throw a fault and no funds will be withdrawn.
• AccountTransactionHandler - This handler simply logs all transactions.

Ensure that you have installed the required software and set up your environment. You must have OC4J running. If it is not running on localhost, port 8888, you'll have to modify the ANT script (build.xml) to use the correct host and port to your server.

Once you have the server configured and running, just type ant from the handlerchain directory. The service artifacts and implementation class will be compiled and placed into a WAR which is then placed into an EAR. The EAR will be deployed to OC4J. Next the stubs and client will be compiled. Finally the service will be invoked by the client and you should see the output both in the server's message output and on the stdout of the client.

1. Generate the service artifacts:

   In this step you will generate the service artifacts which include interfaces and Tie classes. Examine the service-config.xml file. The class BankBean is the implementation class and BankBeanInterface is the Service Endpoint Interface (SEI). They will need to be specified in the java-port element since this will be a bottom-up generation. Notice that the handlers are also specified in this element.

   To generate the service artifacts type: ant gen-service. The source code for the service-artifacts will be placed in the build/src/service directory using the package name oracle.demo.handlerchain.service.

2. Deploy the Service

   The service is now ready to be deployed. Examine the oracleBank.ear in the dist directory. It should contain a WAR file named oracleBank-web.war. This WAR file contains all the service artifacts, implementation classes, as well as the web deployment descriptor (web.xml) and the jaxrpc deployment descriptor (jaxrpc-ri-runtime.xml). To deploy this ear to a running instance of oc4j type: ant deploy-demo. After this task is complete you can check your application by typing in the following url: http://localhost:8888/oracleBank/oracleBank into a web browser. You will be able to invoke all the methods from this page. You can view the wsdl for this service by pointing your browser to http://localhost:8888/oracleBank/oracleBank?WSDL.

3. Generate the stubs (client artifacts)

   In this step you will generate the stubs for the service. A client application uses a stub to invoke operations on a remote service. Examine the file client-config.xml. This is the configuration file that the WebServices Assembler (WSA) tool uses to generate the stubs. To generate the stubs type: ant gen-stubs. The source for the stubs will be placed in build/src/client.

4. Run the demo

   You are now ready to run the client. Examine the file BankAccountClient.java in src/client/oracle/demo/handlerchain/ . Notice that this class uses the stubs to set an endpoint address and to invoke methods on the remote service. To run the client type: ant run-demo. You should see some sample output on the client screen.