Author: tandraschko
Date: Mon Jul 14 09:52:10 2014
New Revision: 1610369
URL: http://svn.apache.org/r1610369
Log:
#DELTASPIKE-642 Better structure for Core documentation
Modified:
deltaspike/site/trunk/content/core.mdtext
Modified: deltaspike/site/trunk/content/core.mdtext
URL:
http://svn.apache.org/viewvc/deltaspike/site/trunk/content/core.mdtext?rev=1610369&r1=1610368&r2=1610369&view=diff
==============================================================================
--- deltaspike/site/trunk/content/core.mdtext (original)
+++ deltaspike/site/trunk/content/core.mdtext Mon Jul 14 09:52:10 2014
@@ -496,8 +496,7 @@ most cases, you register an exception ha
method. Alternatively, you can handle an exception programmatically, just as
you would observe an event in CDI.
-### Exception Handling - Usage
---------------------------
+### Usage
#### Eventing into the exception handling framework
@@ -536,7 +535,6 @@ The event is fired with a new instance o
with the exception to be handled.
### Exception handlers
-------------------
As an application developer (i.e., an end user of DeltaSpike's exception
handling), you'll be focused on writing exception handlers. An exception
@@ -568,7 +566,7 @@ Exception handlers are considered equal
class, have the same qualifiers, the same ordinal and the same value for
`isBeforeHandler()`.
-#### Exception handler annotations
+#### Annotations
Exception handlers are contained within exception handler beans, which are CDI
beans annotated with `@ExceptionHandler`. Exception handlers are methods
@@ -691,8 +689,43 @@ exceptions. Should a handler throw an un
the stack and all handling done via DeltaSpike will cease. Any exception that
was being handled will be lost.
+#### Ordinal
+
+When DeltaSpike finds more than one handler for the same exception type, it
+orders the handlers by ordinal. Handlers with higher ordinal are executed
+before handlers with a lower ordinal. If DeltaSpike detects two handlers for
+the same type with the same ordinal, the order is non-deterministic.
+
+Let's define two handlers with different ordinals:
+
+ :::java
+ void handleIOExceptionFirst(@Handles(ordinal = 100)
ExceptionEvent<IOException> evt)
+ {
+ System.out.println("Invoked first");
+ }
+
+ void handleIOExceptionSecond(@Handles ExceptionEvent<IOException> evt)
+ {
+ System.out.println(âInvoked secondâ);
+ }
+
+The first method is invoked first since it has a higher ordinal (100) than the
+second method, which has the default ordinal (0).
+
+To summarize, here's how DeltaSpike determines the order of handlers to invoke
+(until a handler marks exception as handled):
+
+1. Unwrap exception stack
+2. Begin processing root cause
+3. Invoke any callback methods annotated with @BeforeHandles for the
+ closest type to the exception
+4. Find handler for the closest type to the exception
+5. If multiple handlers for same type, invoke handlers with higher
+ ordinal first
+6. Continue above steps for each exception in stack
+
+
### Exception Chain Processing
---------------------------
When an exception is thrown, chances are it's nested (wrapped) inside other
exceptions. (If you've ever examined a server log, you'll appreciate this
@@ -738,44 +771,7 @@ If there's a handler for `PersistenceExc
handlers for `EJBException` from being invoked, which is a good thing since
what useful information can really be obtained from `EJBException`?
-### Handler ordinal
----------------
-
-When DeltaSpike finds more than one handler for the same exception type, it
-orders the handlers by ordinal. Handlers with higher ordinal are executed
-before handlers with a lower ordinal. If DeltaSpike detects two handlers for
-the same type with the same ordinal, the order is non-deterministic.
-
-Let's define two handlers with different ordinals:
-
- :::java
- void handleIOExceptionFirst(@Handles(ordinal = 100)
ExceptionEvent<IOException> evt)
- {
- System.out.println("Invoked first");
- }
-
- void handleIOExceptionSecond(@Handles ExceptionEvent<IOException> evt)
- {
- System.out.println(âInvoked secondâ);
- }
-
-The first method is invoked first since it has a higher ordinal (100) than the
-second method, which has the default ordinal (0).
-
-To summarize, here's how DeltaSpike determines the order of handlers to invoke
-(until a handler marks exception as handled):
-
-1. Unwrap exception stack
-2. Begin processing root cause
-3. Invoke any callback methods annotated with @BeforeHandles for the
- closest type to the exception
-4. Find handler for the closest type to the exception
-5. If multiple handlers for same type, invoke handlers with higher
- ordinal first
-6. Continue above steps for each exception in stack
-
### APIs for exception information and flow control
------------------------------------------------
There are two APIs provided by DeltaSpike that should be familiar to
application developers:
