v1.5.1RC3/modules/samples/faulthandling/docs/FaultHandlingSampleGuide.html - axis-axis2-java-core - Git at Google

 <!--
   ~ Licensed to the Apache Software Foundation (ASF) under one
   ~ or more contributor license agreements. See the NOTICE file
   ~ distributed with this work for additional information
   ~ regarding copyright ownership. The ASF licenses this file
   ~ to you under the Apache License, Version 2.0 (the
   ~ "License"); you may not use this file except in compliance
   ~ with the License. You may obtain a copy of the License at
   ~
   ~ http://www.apache.org/licenses/LICENSE-2.0
   ~
   ~ Unless required by applicable law or agreed to in writing,
   ~ software distributed under the License is distributed on an
   ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   ~ KIND, either express or implied. See the License for the
   ~ specific language governing permissions and limitations
   ~ under the License.
   -->

 <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 &gt; 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>
	<!--
	~ Licensed to the Apache Software Foundation (ASF) under one
	~ or more contributor license agreements. See the NOTICE file
	~ distributed with this work for additional information
	~ regarding copyright ownership. The ASF licenses this file
	~ to you under the Apache License, Version 2.0 (the
	~ "License"); you may not use this file except in compliance
	~ with the License. You may obtain a copy of the License at
	~
	~ http://www.apache.org/licenses/LICENSE-2.0
	~
	~ Unless required by applicable law or agreed to in writing,
	~ software distributed under the License is distributed on an
	~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	~ KIND, either express or implied. See the License for the
	~ specific language governing permissions and limitations
	~ under the License.
	-->

	<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>