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
