| <html> |
| <head> |
| <meta http-equiv="content-type" content=""> |
| <title>:: Exception Handling using WSDL Faults ::</title> |
| </head> |
| |
| <body> |
| <h1>Exception Handling using WSDL Faults</h1> |
| |
| <p>This sample demonstrates how to specify a WSDL fault in order to allow |
| your service to communicate exception pathways to your clients.</p> |
| |
| <p>Running of this sample assumes that you are running this within the |
| extracted release folder.</p> |
| |
| <h2>Constructing the Service and Client</h2> |
| |
| <p>The first step is to generate the service skeleton and other interface |
| classes from the WSDL.</p> |
| |
| <p>Look at <em><a href="../bank.wsdl">bank.wsdl</a></em>. It defines the |
| interface for our service. Of particular interest are the |
| <strong>AccountNotExistFault</strong> and |
| <strong>InsufficientFundFault</strong> types defined in the wsdl:types |
| element.</p> |
| |
| <p>Using a command prompt, got to the folder of this example and type |
| <strong>ant generate.service</strong> or just <strong> ant</strong>. This |
| will:</p> |
| <ul> |
| <li>Generate the source for all the service classes in |
| <em>build/service/src/example</em></li> |
| <li>Generate <em>services.xml</em> and a more complete |
| <em>BankService.wsdl</em> into the <em>build/service/resources</em> |
| folder.</li> |
| <li>Generate a <em>build/service/build.xml</em></li> |
| <li>Copies the pre-populated service skeleton class to the generated |
| code</li> |
| <li>Compile the Java classes for the service</li> |
| <li>Create the service archive and copy it to Axis2 repository |
| (<em>repository/services/</em>) as sample-faulthandling.aar.</li> |
| </ul> |
| |
| <p>Open up <em>service/src/example/BankServiceSkeleton.java</em> and you will |
| see the following code fragment inside <strong>#withdraw</strong> method. |
| When <strong>generate.service</strong> has been executed, Axis2 generates a skeleton class |
| (<em>build/service/src/example/BankServiceSkeleton.java</em>) which has an empty method. |
| We replace it, the genedrated skeleton with a pre-populated skeleton class |
| (<em>service/src/example/BankServiceSkeleton.java</em>) which has the |
| following code inside it.</p> |
| <pre> final String account = param0.getAccount(); |
| if (account.equals("13")) { |
| final AccountNotExistFault fault = new AccountNotExistFault(); |
| fault.setAccount(account); |
| AccountNotExistFaultMessageException messageException = new |
| AccountNotExistFaultMessageException("Account does |
| not exist!"); |
| messageException.setFaultMessage(fault); |
| throw messageException; |
| } |
| |
| final int amount = param0.getAmount(); |
| if (amount > 1000) { |
| final InsufficientFundFault fault = new InsufficientFundFault(); |
| fault.setAccount(account); |
| fault.setBalance(1000); |
| fault.setRequestedFund(amount); |
| InsufficientFundFaultMessageException messageException = new |
| InsufficientFundFaultMessageException("Insufficient |
| funds"); |
| messageException.setFaultMessage(fault); |
| throw messageException; |
| } |
| |
| final WithdrawResponse response = new WithdrawResponse(); |
| response.setBalance(1000 - amount); |
| return response; |
| </pre> |
| |
| <p>Note that the source generated for the client will include the 2 faults |
| and the local Exceptions through which they will be transmitted. Also note |
| that the Exceptions are generated within the <em>BankStub</em> class.</p> |
| |
| <h2>Deploying the Service</h2> |
| |
| <p>The above step must have already copied your BankService.aar file in to |
| <em>repository/services/</em> folder. Then go to <em>bin</em> folder and run |
| either of axis2server.bat or axis2server.sh, depending on your platform in |
| order to startup Axis2 server.</p> |
| |
| <p>With the default configuration, if you go to <a |
| href="http://localhost:8080/axis2/"> http://localhost:8080/axis2/</a> you |
| should see <em>BankService</em> was deployed.</p> |
| |
| <h2>Running the Client</h2> |
| |
| <p>Invoke the <em>client/src/example/BankClient</em>.java class. You may use |
| the command scripts to do so. You need to supply 3 parameters to the command- |
| url, account and amount.</p> |
| <ul> |
| <li><strong>ant run.client |
| -Durl=http://localhost:8080/axis2/services/BankService -Daccount=13 |
| -Damt=400</strong><br> |
| Throws AccountNotExistFaultMessageException. You will see "Account#13 |
| does not exist"</li> |
| <li><strong>ant run.client |
| -Durl=http://localhost:8080/axis2/services/BankService -Daccount=88 |
| -Damt=1200</strong><br> |
| Throws InsufficientFundsFaultMessageException. You will see "Account#88 |
| has balance of 1000. It cannot support withdrawal of 1200"<br> |
| </li> |
| <li><strong>ant run.client |
| -Durl=http://localhost:8080/axis2/services/BankService -Daccount=88 |
| -Damt=400</strong><br> |
| Succeeds with a balance of 600. You will see "Balance = 600"</li> |
| </ul> |
| When you call ant run.client with parameters, before running |
| <em>client/src/example/BankClient.java</em> class, it does the following as |
| well: |
| <ul> |
| <li>Generate the stubs (for the client) from the WSDL</li> |
| <li>Compile the client classes</li> |
| <li>Create a Jar of the client classes and copy it to |
| <em>build/client/BankService-test-client.jar</em></li> |
| </ul> |
| </body> |
| </html> |