aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timothyjw...@apache.org
Subject svn commit: r1744294 - in /aries/site/trunk/content/modules/tx-control: exceptionManagement.mdtext index.mdtext
Date Tue, 17 May 2016 17:20:46 GMT
Author: timothyjward
Date: Tue May 17 17:20:46 2016
New Revision: 1744294

URL: http://svn.apache.org/viewvc?rev=1744294&view=rev
Log:
Add an Exception Management page

Added:
    aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext   (with props)
Modified:
    aries/site/trunk/content/modules/tx-control/index.mdtext

Added: aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext
URL: http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext?rev=1744294&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext Tue May 17 17:20:46
2016
@@ -0,0 +1,90 @@
+Title: Exception Management
+Notice:    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.
+
+#Exception Management
+
+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.
+
+##Throwing Exceptions from scoped work
+
+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>.
+
+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.
+
+    // An SQLException may be raised by the query, 
+    // but we don't need to catch it
+    txControl.required(() -> connection.createStatement()
+        .executeQuery("Insert into TEST_TABLE values ( 'Hello World!' )"));
+
+
+##Catching Exceptions thrown from scoped work
+
+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.
+
+Sometimes, however, we have to work within an existing API that *does* use an Exception as
a type of 
+return value. In that case it is important to know what happened to the Exception.
+
+### The <code>ScopedWorkException</code>
+
+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 *always* declare

+<code>throws Exception</code> on their methods or to add try/catch blocks around
every call.
+
+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 *unchecked exception*
+and so can be ignored by your component if it does not require special handling (the typical
case).
+
+### Unwrapping the <code>ScopedWorkException</code>
+
+As mentioned above, sometimes it is necessary for an API to throw a particular type of Exception
as a return value.
+
+This model can be supported by unwrapping the ScopedWorkException.
+
+    try {
+        txControl.required(() -> connection.createStatement()
+            .executeQuery("Insert into TEST_TABLE values ( 'Hello World!' )"));
+    } catch (ScopedWorkException swe) {
+        // This line throws the cause of the ScopedWorkException as
+        // an SQLException or as a RuntimeException if appropriate
+        throw swe.as(SQLException.class);
+    }
+
+This mechanism also supports multiple Exception types:
+
+    try {
+        txControl.required(() -> connection.createStatement()
+            .executeQuery("Insert into TEST_TABLE values ( 'Hello World!' )"));
+    } catch (ScopedWorkException swe) {
+        // This line throws the cause of the ScopedWorkException
+        // as one of the two SQLException types or as a
+        // RuntimeException if appropriate
+        throw swe.asOneOf(SQLRecoverableException.class, SQLTransientException.class);
+    }
+
+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.
\ No newline at end of file

Propchange: aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: aries/site/trunk/content/modules/tx-control/index.mdtext
URL: http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/index.mdtext?rev=1744294&r1=1744293&r2=1744294&view=diff
==============================================================================
--- aries/site/trunk/content/modules/tx-control/index.mdtext (original)
+++ aries/site/trunk/content/modules/tx-control/index.mdtext Tue May 17 17:20:46 2016
@@ -55,6 +55,7 @@ These modules provide portable JPA resou
 * [Making use of the Last Resource Gambit][9]
 * [Custom Resource Providers][10]
 * [Advanced Scope control][11]
+* [Exception Management][12]
 
 
   [1]: quickstart.html
@@ -67,4 +68,5 @@ These modules provide portable JPA resou
   [8]: coordinator.html
   [9]: lastResourceGambit.html
   [10]: advancedResourceProviders.html
-  [11]: advancedScopes.html
\ No newline at end of file
+  [11]: advancedScopes.html
+  [12]: exceptionManagement.html
\ No newline at end of file



Mime
View raw message