001: /*
002: * Copyright 2004-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.springframework.webflow.execution;
017:
018: import org.springframework.webflow.core.collection.AttributeMap;
019: import org.springframework.webflow.core.collection.MutableAttributeMap;
020: import org.springframework.webflow.definition.FlowDefinition;
021: import org.springframework.webflow.definition.StateDefinition;
022: import org.springframework.webflow.engine.FlowExecutionExceptionHandler;
023:
024: /**
025: * Interface to be implemented by objects that wish to listen and respond to the
026: * lifecycle of {@link FlowExecution flow executions}.
027: * <p>
028: * An 'observer' that is very aspect like, allowing you to insert 'cross
029: * cutting' behavior at well-defined points within one or more well-defined flow
030: * execution lifecycles.
031: * <p>
032: * For example, one custom listener may apply security checks at the flow
033: * execution level, preventing a flow from starting or a state from entering if
034: * the curent user does not have the necessary permissions. Another listener may
035: * track flow execution navigation history to support bread crumbs. Another may
036: * perform auditing, or setup and tear down connections to a transactional
037: * resource.
038: * <p>
039: * Note that flow execution listeners are registered with a flow execution when
040: * that execution is created by a {@link FlowExecutionFactory factory} or
041: * restored by a
042: * {@link org.springframework.webflow.execution.repository.FlowExecutionRepository}.
043: * Typically a listener will not be registered with a flow execution <i>at
044: * runtime</i>, when the flow execution is already active.
045: *
046: * @see FlowDefinition
047: * @see StateDefinition
048: * @see FlowExecution
049: * @see RequestContext
050: * @see Event
051: * @see ViewSelection
052: *
053: * @author Keith Donald
054: * @author Erwin Vervaet
055: */
056: public interface FlowExecutionListener {
057:
058: /**
059: * Called when any client request is submitted to manipulate this flow
060: * execution. This call happens before request processing.
061: * @param context the source of the event
062: */
063: public void requestSubmitted(RequestContext context);
064:
065: /**
066: * Called when a client request has completed processing.
067: * @param context the source of the event
068: */
069: public void requestProcessed(RequestContext context);
070:
071: /**
072: * Called to indicate a new flow definition session is about to be created
073: * and started. Called before the session is created. An exception may be
074: * thrown from this method to veto the start operation. Any type of runtime
075: * exception can be used for this purpose.
076: * @param context the source of the event
077: * @param definition the flow for which a new session is starting
078: * @param input a mutable input map - attributes placed in this map are
079: * eligible for input mapping by the flow definition at startup
080: */
081: public void sessionStarting(RequestContext context,
082: FlowDefinition definition, MutableAttributeMap input);
083:
084: /**
085: * Called after a new flow session has been created but before it starts.
086: * Useful for setting arbitrary attributes in the session before the flow
087: * starts.
088: * @param context the source of the event
089: * @param session the session that was created
090: * @since 1.0.2
091: */
092: public void sessionCreated(RequestContext context,
093: FlowSession session);
094:
095: /**
096: * Called after a new flow session has started. At this point the flow's
097: * start state has been entered and any other startup behaviors have been
098: * executed.
099: * @param context the source of the event
100: * @param session the session that was started
101: */
102: public void sessionStarted(RequestContext context,
103: FlowSession session);
104:
105: /**
106: * Called when an event is signaled in the current state, but prior to any
107: * state transition.
108: * @param context the source of the event
109: * @param event the event that occured
110: */
111: public void eventSignaled(RequestContext context, Event event);
112:
113: /**
114: * Called when a state transitions, after the transition is matched but
115: * before the transition occurs.
116: * @param context the source of the event
117: * @param state the proposed state to transition to
118: * @throws EnterStateVetoException when entering the state is not allowed
119: */
120: public void stateEntering(RequestContext context,
121: StateDefinition state) throws EnterStateVetoException;
122:
123: /**
124: * Called when a state transitions, after the transition occured.
125: * @param context the source of the event
126: * @param previousState <i>from</i> state of the transition
127: * @param state <i>to</i> state of the transition
128: */
129: public void stateEntered(RequestContext context,
130: StateDefinition previousState, StateDefinition state);
131:
132: /**
133: * Called when a flow execution is paused, for instance when it is waiting
134: * for user input (after event processing).
135: * @param context the source of the event
136: * @param selectedView the view that will display
137: */
138: public void paused(RequestContext context,
139: ViewSelection selectedView);
140:
141: /**
142: * Called after a flow execution is successfully reactivated after pause
143: * (but before event processing).
144: * @param context the source of the event
145: */
146: public void resumed(RequestContext context);
147:
148: /**
149: * Called when the active flow execution session has been asked to end but
150: * before it has ended.
151: * @param context the source of the event
152: * @param session the current active session that is ending
153: * @param output the flow output produced by the ending session, this map
154: * may be modified by this listener to affect the output returned
155: */
156: public void sessionEnding(RequestContext context,
157: FlowSession session, MutableAttributeMap output);
158:
159: /**
160: * Called when a flow execution session ends. If the ended session was the
161: * root session of the flow execution, the entire flow execution also ends.
162: * @param context the source of the event
163: * @param session ending flow session
164: * @param output final, unmodifiable output returned by the ended session
165: */
166: public void sessionEnded(RequestContext context,
167: FlowSession session, AttributeMap output);
168:
169: /**
170: * Called when an exception is thrown during a flow execution, before the
171: * exception is handled by any registered
172: * {@link FlowExecutionExceptionHandler handler}.
173: * @param context the source of the exception
174: * @param exception the exception that occurred
175: */
176: public void exceptionThrown(RequestContext context,
177: FlowExecutionException exception);
178:
179: }
|