aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
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

Add an Exception Management page

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

Added: aries/site/trunk/content/modules/tx-control/exceptionManagement.mdtext
--- 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
@@ -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
+           .
+           .
+           Unless required by applicable law or agreed to in writing,
+           software distributed under the License is distributed on an
+           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
+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
+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
+### 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;
+    }
+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
--- 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

View raw message