diff --git a/spring-webflow/changelog.txt b/spring-webflow/changelog.txt index 892610a0..159879c6 100644 --- a/spring-webflow/changelog.txt +++ b/spring-webflow/changelog.txt @@ -76,6 +76,7 @@ Package org.springframework.webflow.test Package reference-manual * Improved readability of reference manual in several sections (SWF-349). +* Added documentation on flow execution exception handling options (SWF-357). Changes in version 1.0.3 (19.04.2007) ------------------------------------- diff --git a/spring-webflow/docs/reference/src/flow-definition.xml b/spring-webflow/docs/reference/src/flow-definition.xml index 4e0745e2..e1ff75d7 100644 --- a/spring-webflow/docs/reference/src/flow-definition.xml +++ b/spring-webflow/docs/reference/src/flow-definition.xml @@ -598,8 +598,7 @@ In this mock example, state1 defines one transition and also inherits the two others defined within the global-transitions element. - Any other states defined within this flow would also inherit those global - transitions. + Any other states defined within this flow would also inherit those global transitions. This example is shown graphically below: @@ -618,16 +617,17 @@ - Transition executing state exception handlers + Transition executing exception handlers The <transition/> element contains an exclusive on-exception attribute used to specify an exception-based criteria for transition execution. This allows you to - transition the flow to another state on the occurrence of an exception. + transition the flow to another state on the occurrence of an exception. Transition executing exception handlers + may be attached at the state and flow levels. - - Exception handling - XML example + + State exception handling - XML example - The following example shows a transition that is applied as a state exception handler: + The following example illustrates a state-level transition executing exception handler: <?xml version="1.0" encoding="UTF-8"?> @@ -651,11 +651,125 @@ In this example, state1 defines one transition and an exception handler which executes a transition to state3 if a MyBusinessException - is thrown within the state. The handled exception will be put into flash scope using the - key "stateException". That way it is available for processing in the flow or display in a view. + is thrown within the state. The handled exception will be put into flash scope under the + key stateException, where it will be automatically exposed to the next view (typically an error view). + + Flow exception handling - XML example + + The following example illustrates a flow-level transition executing exception handler: + + + <?xml version="1.0" encoding="UTF-8"?> + <flow xmlns="http://www.springframework.org/schema/webflow" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/webflow + http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"> + + <start-state idref="state1"/> + + <xxx-state id="state1"> + <transition on="event1" to="state2"/> + </xxx-state> + + <xxx-state id="state2"/> + + <global-transitions> + <transition on-exception="example.MyBusinessException" to="state3"/> + </global-transitions> + + ... + + </flow> + + + In this example, the exception handler is defined as a global transition. This reads "any time + a MyBusinessException occurs during flow execution, transition the flow + to state3". + + + Exception handlers attached at the state level take precedence over those defined at the flow level. + This is illustrated by the following example: + + + <?xml version="1.0" encoding="UTF-8"?> + <flow xmlns="http://www.springframework.org/schema/webflow" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/webflow + http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"> + + <start-state idref="state1"/> + + <xxx-state id="state1"> + <transition on="event1" to="state2"/> + <transition on-exception="example.MyBusinessException" to="state4"/> + </xxx-state> + + <xxx-state id="state2"/> + + <global-transitions> + <transition on-exception="example.MyBusinessException" to="state3"/> + </global-transitions> + + ... + + </flow> + + + In this example, if MyBusinessException is thrown in state1 the + flow will transition to state4. For any other state, the flow will transition to state3. + + + + Custom exception handlers + + Custom, user-defined exception handlers may be attached at the flow and state levels by using the + exception-handler element. This element delegates to Spring to locate + the custom exception handler instance with the specified bean name. + + + An example of attaching a custom exception handler is shown below: + + + <?xml version="1.0" encoding="UTF-8"?> + <flow xmlns="http://www.springframework.org/schema/webflow" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/webflow + http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"> + + <start-state idref="state1"/> + + <xxx-state id="state1"> + <transition on="event1" to="state2"/> + <exception-handler bean="myCustomStateExceptionHandler"/> + </xxx-state> + + <xxx-state id="state2"/> + + <global-transitions> + <exception-handler bean="myCustomFlowExceptionHandler"/> + </global-transitions> + + <import resource="flow-beans.xml"/> + + </flow> + + + flow-beans.xml + + <bean id="myCustomStateExceptionHandler" class="example.CustomFlowExecutionExceptionHandler"/> + <bean id="myCustomFlowExceptionHandler" class="example.AnotherCustomFlowExecutionExceptionHandler"/> + + + + Custom exception handlers must implement the org.springframework.webflow.engine.FlowExecutionExceptionHandler interface. + + Concrete state types