Google Git
Sign in
apache / aries-site-pub / fcb57f6e8cfd65efdd4d4f61e860eb8c5fd9d4ef / . / modules / tx-control / exceptionManagement.html
blob: 6ad70a9a17254388273c6b56b460a3402b39be2c [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";>
<!--
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>
<link rel="shortcut icon" href="http://aries.apache.org/images/favicon.ico"></link>
<link type="text/css" rel="stylesheet" href="http://aries.apache.org/resources/site.css"></link>
</script><script src="http://aries.apache.org/resources/menus.js" language="javascript" type="text/javascript"></script>
<meta name="keywords" content="..."/>
<meta name="description" content="..." />
<title>
Apache Aries - Exception Management
</title>
</head>
<body onload="SetMenu()">
<table width="100%" cellpadding="0" cellspacing="0">
<tr width="100%">
<td id="cell-0-0" colspan="2">&nbsp;</td>
<td id="cell-0-1">&nbsp;</td>
<td id="cell-0-2" colspan="2">&nbsp;</td>
</tr>
<tr width="100%">
<td id="cell-1-0">&nbsp;</td>
<td id="cell-1-1">&nbsp;</td>
<td id="cell-1-2">
<div style="padding: 5px;">
<div id="banner">
<!-- Banner -->
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" class="topbardiv" nowrap="">
<a href="http://aries.apache.org/" title="Apache Aries"> <img border="0" src="http://aries.apache.org/images/Arieslogo_Horizontal.gif"> </a>
</td>
<td align="right" nowrap="">
<a href="http://www.apache.org/" title="The Apache Software Foundation"> <img border="0" src="http://aries.apache.org/images/apache_feather.png"> </a>
</td>
</tr>
</table>
<!-- Banner -->
</div>
</div>
<div id="top-menu">
<table border="0" cellpadding="1" cellspacing="0" width="100%">
<tr>
<td>
<div align="left">
<!-- Breadcrumbs -->
<!-- Breadcrumbs -->
</div>
</td>
<td>
<div align="right">
<!-- Quicklinks -->
<DIV style="padding: 5px 5px 0px 25px;">
<FORM action="http://www.google.com/search" method="get" style="font-size: 10px;">
<A href="http://www.apache.org/licenses/LICENSE-2.0.html" class="external-link" rel="nofollow">License</A>
<INPUT name="ie" type="hidden" value="UTF-8"></INPUT>
<INPUT name="oe" type="hidden" value="UTF-8"></INPUT>
<INPUT maxlength="255" name="q" size="15" type="text" value></INPUT>
<INPUT name="btnG" type="submit" value="Search"></INPUT>
<INPUT name="domains" type="hidden" value="aries.apache.org"></INPUT>
<INPUT name="sitesearch" type="hidden" value="aries.apache.org"></INPUT>
</FORM>
</DIV>
<!-- Quicklinks -->
</div>
</td>
</tr>
</table>
</div>
</td>
<td id="cell-1-3">&nbsp;</td>
<td id="cell-1-4">&nbsp;</td>
</tr>
<tr width="100%">
<td id="cell-2-0" colspan="2">&nbsp;</td>
<td id="cell-2-1">
<table>
<tr height="100%" valign="top">
<td height="100%">
<div id="wrapper-menu-page-right">
<div id="wrapper-menu-page-top">
<div id="wrapper-menu-page-bottom">
<div id="menu-page">
<!-- NavigationBar -->
<style type="text/css">
/* The following code is added by mdx_elementid.py
It was originally lifted from http://subversion.apache.org/style/site.css */
/*
* Hide class="elementid-permalink", except when an enclosing heading
* has the :hover property.
*/
.headerlink, .elementid-permalink {
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<div onclick="SwitchMenu('documentation')" id="documentationTitle" class="menutitle">Documentation</div>
<div id="documentation" class="menuitemgroup">
<div class="menuitem">
<a href="/documentation/integrators-guide.html">Integrators Guide</a>
</div>
<div class="menuitem">
<a href="/documentation/articles.html">Articles</a>
</div>
<div class="menuitem">
<a href="https://svn.apache.org/repos/asf/aries/slides/">Slides</a>
</div>
<div class="menuitem">
<a href="/documentation/tutorials.html">Tutorials</a>
</div>
<div class="menuitem">
<a href="/documentation/tools.html">Tools</a>
</div>
</div>
<div onclick="SwitchMenu('modules')" id="modulesTitle" class="menutitle">Modules</div>
<div id="modules" class="menuitemgroup">
<div class="menuitem">
<a href="/modules/samples.html">Samples</a>
</div>
<div class="menuitem">
<a href="/modules/async-svcs.html">Asynchronous Services</a>
</div>
<div class="menuitem">
<a href="/modules/blueprint.html">Blueprint</a>
</div>
<div class="menuitem">
<a href="/modules/blueprint-maven-plugin.html">Blueprint-maven-plugin</a>
</div>
<div class="menuitem">
<a href="/modules/blueprintannotation.html">Blueprint Annotations</a>
</div>
<div class="menuitem">
<a href="/modules/blueprintnoosgi.html">Blueprint No-OSGi</a>
</div>
<div class="menuitem">
<a href="/modules/blueprintweb.html">Blueprint Web</a>
</div>
<div class="menuitem">
<a href="/modules/containers.html">Containers</a>
</div>
<div class="menuitem">
<a href="/modules/esaanttask.html">ESA Ant Task </a>
</div>
<div class="menuitem">
<a href="/modules/ebamavenpluginproject.html">EBA Maven Plugin </a>
</div>
<div class="menuitem">
<a href="/modules/esamavenpluginproject.html">ESA Maven Plugin </a>
</div>
<div class="menuitem">
<a href="/modules/jmx.html">JMX</a>
</div>
<div class="menuitem">
<a href="/modules/jndiproject.html">JNDI</a>
</div>
<div class="menuitem">
<a href="/modules/jpaproject.html">JPA</a>
</div>
<div class="menuitem">
<a href="/modules/transactioncontrol.html">Transaction Control Service</a>
</div>
<div class="menuitem">
<a href="/modules/transactionsproject.html">Transactions</a>
</div>
<div class="menuitem">
<a href="/modules/rsa.html">Remote Service Admin (RSA)</a>
</div>
<div class="menuitem">
<a href="/modules/spi-fly.html">SPI Fly</a>
</div>
<div class="menuitem">
<a href="/modules/subsystems.html">Subsystems</a>
</div>
<div class="menuitem">
<a href="/modules/applications.html">Applications (obsolete)</a>
</div>
</div>
<div onclick="SwitchMenu('downloads')" id="downloadsTitle" class="menutitle">Downloads</div>
<div id="downloads" class="menuitemgroup">
<div class="menuitem">
<a href="/downloads/currentreleases.html">Current Releases</a>
</div>
<div class="menuitem">
<a href="/downloads/testresults.html">Compliance Tests</a>
</div>
<div class="menuitem">
<a href="/downloads/archived-releases.html">Archived Releases</a>
</div>
</div>
<div onclick="SwitchMenu('community')" id="communityTitle" class="menutitle">Community</div>
<div id="community" class="menuitemgroup">
<div class="menuitem">
<a href="/community/resources.html">Community Resources</a>
</div>
<div class="menuitem">
<a href="/community/gettinginvolved.html">Getting Involved</a>
</div>
<div class="menuitem">
<a href="/community/people.html">Who we are</a>
</div>
<div class="menuitem">
<a href="/community/boardreports.html">Board Reports</a>
</div>
<div class="menuitem">
<a href="/community/logos.html">Logos for Users</a>
</div>
</div>
<div onclick="SwitchMenu('development')" id="developmentTitle" class="menutitle">Development</div>
<div id="development" class="menuitemgroup">
<div class="menuitem">
<a href="/development/buildingaries.html">Building Aries </a>
</div>
<div class="menuitem">
<a href="/development/guidelines.html">Cording Guidelines</a>
</div>
<div class="menuitem">
<a href="/development/architecture.html">Architecture</a>
</div>
<div class="menuitem">
<a href="/development/releasingaries.html">Releasing Aries </a>
</div>
<div class="menuitem">
<a href="/development/compliancetesting.html">OSGi Compliance Tests </a>
</div>
<div class="menuitem">
<a href="/development/maintainingthewebpages.html">Web Site Maintenance </a>
</div>
</div>
<div onclick="SwitchMenu('sponsorship')" id="sponsorshipTitle" class="menutitle">Sponsorship</div>
<div id="sponsorship" class="menuitemgroup">
<div class="menuitem">
<a href="http://www.apache.org/foundation/thanks.html">Thanks</a>
</div>
<div class="menuitem">
<a href="http://www.apache.org/foundation/sponsorship.html">Sponsoring Apache</a>
</div>
</div>
<div class="promotion">
<a href="http://www.apache.org/events/current-event.html">
<img src="http://www.apache.org/events/current-event-125x125.png" width="125" height="125"/>
</a>
</div>
<!-- NavigationBar -->
</div>
</div>
</div>
</div>
</td>
<td height="100%" width="100%">
<!-- Content -->
<div class="wiki-content"><style type="text/css">
/* The following code is added by mdx_elementid.py
It was originally lifted from http://subversion.apache.org/style/site.css */
/*
* Hide class="elementid-permalink", except when an enclosing heading
* has the :hover property.
*/
.headerlink, .elementid-permalink {
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="exception-management">Exception Management<a class="headerlink" href="#exception-management" title="Permanent link">&para;</a></h1>
<p>Managing Exceptions should not be a core part of your business logic. In fact with the Transaction Control
Service is doing its job you shouldn't need to worry about exceptions at all! A key design goal for the
Transaction Control Service is to avoid the need for try/catch/finally blocks as far as possible.</p>
<h2 id="throwing-exceptions-from-scoped-work">Throwing Exceptions from scoped work<a class="headerlink" href="#throwing-exceptions-from-scoped-work" title="Permanent link">&para;</a></h2>
<p>Resources can be tempramental sometimes, and usually have defined exceptions that are thrown in certain
error cases. These can be generic, like <code>SQLException</code> or <code>JMSException</code>,
or specific like <code>EntityNotFoundException</code>.</p>
<p>In any event - exceptions indicate that a problem has occurred. By default an exception thrown from inside a
transactional scope will cause the transaction to roll back. This means that the code can safely ignore any
updates that were made. Furthermore, because a piece of scoped work is defined as a <code>Callable</code>
it is not necessary to catch or wrap an Exception raised in a scope.</p>
<div class="codehilite"><pre><span class="c1">// An SQLException may be raised by the query, </span>
<span class="c1">// but we don&#39;t need to catch it</span>
<span class="n">txControl</span><span class="p">.</span><span class="n">required</span><span class="p">(()</span> <span class="o">-&gt;</span> <span class="n">connection</span><span class="p">.</span><span class="n">createStatement</span><span class="p">()</span>
<span class="p">.</span><span class="n">executeQuery</span><span class="p">(</span><span class="s">&quot;Insert into TEST_TABLE values ( &#39;Hello World!&#39; )&quot;</span><span class="p">));</span>
</pre></div>
<h2 id="catching-exceptions-thrown-from-scoped-work">Catching Exceptions thrown from scoped work<a class="headerlink" href="#catching-exceptions-thrown-from-scoped-work" title="Permanent link">&para;</a></h2>
<p>In general Exceptions should not form part of your client API, so catching an Exception from a piece of scoped
work is rarely necessary. Usually exceptions generated by scoped work are eventually handled by catch all
collectors at the incoming request point (for example a servlet) and do not require special handling.</p>
<p>Sometimes, however, we have to work within an existing API that <em>does</em> use an Exception as a type of
return value. In that case it is important to know what happened to the Exception.</p>
<h3 id="the-scopedworkexception">The <code>ScopedWorkException</code><a class="headerlink" href="#the-scopedworkexception" title="Permanent link">&para;</a></h3>
<p>Scoped work is free to throw checked or unchecked Exceptions, however these Exceptions cannot be directly
thrown on by the TransactionControl implementation. The primary reason for this is that directly rethrowing the
Exception would force users of the Transaction Control Service to either <em>always</em> declare
<code>throws Exception</code> on their methods or to add try/catch blocks around every call.</p>
<p>Exceptions generated as part of Scoped Work are therefore wrapped by the Transaction Control Service in a
<code>ScopedWorkException</code>. <code>ScopedWorkException</code> is an <em>unchecked exception</em>
and so can be ignored by your component if it does not require special handling (the typical case).</p>
<h3 id="unwrapping-the-scopedworkexception">Unwrapping the <code>ScopedWorkException</code><a class="headerlink" href="#unwrapping-the-scopedworkexception" title="Permanent link">&para;</a></h3>
<p>As mentioned above, sometimes it is necessary for an API to throw a particular type of Exception as a return value.</p>
<p>This model can be supported by unwrapping the ScopedWorkException.</p>
<div class="codehilite"><pre><span class="k">try</span> <span class="p">{</span>
<span class="n">txControl</span><span class="p">.</span><span class="n">required</span><span class="p">(()</span> <span class="o">-&gt;</span> <span class="n">connection</span><span class="p">.</span><span class="n">createStatement</span><span class="p">()</span>
<span class="p">.</span><span class="n">executeQuery</span><span class="p">(</span>&quot;<span class="n">Insert</span> <span class="n">into</span> <span class="n">TEST_TABLE</span> <span class="n">values</span> <span class="p">(</span> <span class="s">&#39;Hello World!&#39;</span> <span class="p">)</span>&quot;<span class="p">));</span>
<span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="n">ScopedWorkException</span> <span class="n">swe</span><span class="p">)</span> <span class="p">{</span>
<span class="o">//</span> <span class="n">This</span> <span class="n">line</span> <span class="n">throws</span> <span class="n">the</span> <span class="n">cause</span> <span class="n">of</span> <span class="n">the</span> <span class="n">ScopedWorkException</span> <span class="n">as</span>
<span class="o">//</span> <span class="n">an</span> <span class="n">SQLException</span> <span class="n">or</span> <span class="n">as</span> <span class="n">a</span> <span class="n">RuntimeException</span> <span class="k">if</span> <span class="n">appropriate</span>
<span class="n">throw</span> <span class="n">swe</span><span class="p">.</span><span class="n">as</span><span class="p">(</span><span class="n">SQLException</span><span class="p">.</span><span class="n">class</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
<p>This mechanism also supports multiple Exception types:</p>
<div class="codehilite"><pre><span class="k">try</span> <span class="p">{</span>
<span class="n">txControl</span><span class="p">.</span><span class="n">required</span><span class="p">(()</span> <span class="o">-&gt;</span> <span class="n">connection</span><span class="p">.</span><span class="n">createStatement</span><span class="p">()</span>
<span class="p">.</span><span class="n">executeQuery</span><span class="p">(</span>&quot;<span class="n">Insert</span> <span class="n">into</span> <span class="n">TEST_TABLE</span> <span class="n">values</span> <span class="p">(</span> <span class="s">&#39;Hello World!&#39;</span> <span class="p">)</span>&quot;<span class="p">));</span>
<span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="n">ScopedWorkException</span> <span class="n">swe</span><span class="p">)</span> <span class="p">{</span>
<span class="o">//</span> <span class="n">This</span> <span class="n">line</span> <span class="n">throws</span> <span class="n">the</span> <span class="n">cause</span> <span class="n">of</span> <span class="n">the</span> <span class="n">ScopedWorkException</span>
<span class="o">//</span> <span class="n">as</span> <span class="n">one</span> <span class="n">of</span> <span class="n">the</span> <span class="n">two</span> <span class="n">SQLException</span> <span class="n">types</span> <span class="n">or</span> <span class="n">as</span> <span class="n">a</span>
<span class="o">//</span> <span class="n">RuntimeException</span> <span class="k">if</span> <span class="n">appropriate</span>
<span class="n">throw</span> <span class="n">swe</span><span class="p">.</span><span class="n">asOneOf</span><span class="p">(</span><span class="n">SQLRecoverableException</span><span class="p">.</span><span class="n">class</span><span class="p">,</span> <span class="n">SQLTransientException</span><span class="p">.</span><span class="n">class</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
<p>Note that if you unwrap a <code>ScopedWorkException</code> into a checked exception then you will have
to list that Exception in your <code>throws</code> clause.</p></div>
<!-- Content -->
</td>
</tr>
</table>
</td>
<td id="cell-2-2" colspan="2">&nbsp;</td>
</tr>
<tr width="100%">
<td id="cell-3-0">&nbsp;</td>
<td id="cell-3-1">&nbsp;</td>
<td id="cell-3-2">
<div id="footer">
<!-- Footer -->
<div id="site-footer">
<a href="http://aries.apache.org/privacy-policy.html";>Privacy
Policy</a>
</div>
<!-- Footer -->
</div>
</td>
<td id="cell-3-3">&nbsp;</td>
<td id="cell-3-4">&nbsp;</td>
</tr>
<tr width="100%">
<td id="cell-4-0" colspan="2">&nbsp;</td>
<td id="cell-4-1">&nbsp;</td>
<td id="cell-4-2" colspan="2">&nbsp;</td>
</tr>
</table>
</body>
</html>