aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r988470 - in /websites/staging/aries/trunk/content: ./ modules/tx-control/exceptionManagement.html modules/tx-control/index.html
Date Tue, 17 May 2016 17:20:54 GMT
Author: buildbot
Date: Tue May 17 17:20:54 2016
New Revision: 988470

Log:
Staging update by buildbot for aries

Added:
    websites/staging/aries/trunk/content/modules/tx-control/exceptionManagement.html
Modified:
    websites/staging/aries/trunk/content/   (props changed)
    websites/staging/aries/trunk/content/modules/tx-control/index.html

Propchange: websites/staging/aries/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue May 17 17:20:54 2016
@@ -1 +1 @@
-1743006
+1744294

Added: websites/staging/aries/trunk/content/modules/tx-control/exceptionManagement.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/tx-control/exceptionManagement.html (added)
+++ websites/staging/aries/trunk/content/modules/tx-control/exceptionManagement.html Tue May
17 17:20:54 2016
@@ -0,0 +1,372 @@
+<!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/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>
+                    <!-- 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> 

Modified: websites/staging/aries/trunk/content/modules/tx-control/index.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/tx-control/index.html (original)
+++ websites/staging/aries/trunk/content/modules/tx-control/index.html Tue May 17 17:20:54
2016
@@ -309,6 +309,7 @@ transactional resource access</p>
 <li><a href="lastResourceGambit.html">Making use of the Last Resource Gambit</a></li>
 <li><a href="advancedResourceProviders.html">Custom Resource Providers</a></li>
 <li><a href="advancedScopes.html">Advanced Scope control</a></li>
+<li><a href="exceptionManagement.html">Exception Management</a></li>
 </ul></div>
             <!-- Content -->
           </td>



Mime
View raw message