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.context.ExternalContext;
019: import org.springframework.webflow.core.collection.MutableAttributeMap;
020: import org.springframework.webflow.definition.FlowDefinition;
021:
022: /**
023: * A top-level instance of a flow definition that carries out definition
024: * execution on behalf of a single client. Typically used to support the
025: * orchestration of a web conversation.
026: * <p>
027: * This is the central facade interface for manipulating one runtime execution
028: * of a flow definition. Implementations of this interface are the finite state
029: * machine that is the heart of Spring Web Flow.
030: * <p>
031: * Typically, when a client wants to launch a flow execution at production time,
032: * she passes the id of the governing {@link FlowDefinition flow definition} to
033: * a coordinating
034: * {@link org.springframework.webflow.executor.FlowExecutor#launch(String, ExternalContext) flow executor}.
035: * This coordinator then typically uses a
036: * {@link FlowExecutionFactory flow execution factory} to create an object
037: * implementing this interface, initializing it with the requested flow
038: * definition which becomes the execution's "root" or top-level flow.
039: * <p>
040: * After execution creation, the
041: * {@link #start(MutableAttributeMap, ExternalContext) start} operation is
042: * called, which causes this execution to activate a new
043: * {@link FlowSession session} for its root flow definition. That session is
044: * then said to become the <i>active flow</i>. An execution
045: * {@link RequestContext request context} is created, the Flow's
046: * {@link FlowDefinition#getStartState() start state} is entered, and the
047: * request is processed.
048: * <p>
049: * In a distributed environment such as HTTP, after a call into this object has
050: * completed and control returns to the caller, this execution object (if still
051: * active) is typically saved out to a repository before the server request
052: * ends. For example it might be saved out to the HttpSession, a Database, or a
053: * client-side hidden form field for later restoration and manipulation. This
054: * execution persistence is the responsibility of the
055: * {@link org.springframework.webflow.execution.repository.FlowExecutionRepository flow execution repository}
056: * subsystem.
057: * <p>
058: * Subsequent requests from the client to manipuate this flow execution trigger
059: * restoration of this object, followed by an invocation of the
060: * {@link #signalEvent(String, ExternalContext) signal event} operation. The
061: * signalEvent operation resumes this execution by indicating what action the
062: * user took from within the current state; for example, the user may have
063: * pressed the "submit" button, or pressed "cancel". After the user
064: * event is processed, control again goes back to the caller and if this
065: * execution is still active, it is again saved out to the repository.
066: * <p>
067: * This process continues until a client event causes this flow execution to end
068: * (by the root flow reaching an end state). At that time this object is no
069: * longer active, and is removed from the repository and discarded.
070: * <p>
071: * Flow executions can have their lifecycle observed by {@link FlowExecutionListener listeners}.
072: *
073: * @see FlowDefinition
074: * @see FlowSession
075: * @see RequestContext
076: * @see FlowExecutionListener
077: * @see org.springframework.webflow.execution.repository.FlowExecutionRepository
078: * @see org.springframework.webflow.executor.FlowExecutor
079: *
080: * @author Keith Donald
081: * @author Erwin Vervaet
082: */
083: public interface FlowExecution extends FlowExecutionContext {
084:
085: /**
086: * Start this flow execution, transitioning it to the root flow's start
087: * state and returning the starting view selection needed to issue an
088: * initial user response. Typically called by a flow executor on behalf of a
089: * browser client, but also from test code.
090: * <p>
091: * This will start the entire flow execution <i>from scratch</i>.
092: * @param input input attributes to pass to the flow, which the flow may
093: * choose to map into its scope
094: * @param context the external context in which the starting event occured
095: * @return the starting view selection, a value object to be used to issue a
096: * suitable response to the caller
097: * @throws FlowExecutionException if an exception was thrown within a state
098: * of the flow execution during request processing
099: */
100: public ViewSelection start(MutableAttributeMap input,
101: ExternalContext context) throws FlowExecutionException;
102:
103: /**
104: * Signal an occurrence of the specified user event in the current state of
105: * this executing flow. The event will be processed in full and control will
106: * be returned once event processing is complete.
107: * @param eventId the identifier of the user event that occured
108: * @param context the external context in which the event occured
109: * @return the next view selection to render, used by the calling executor
110: * to issue a suitable response to the client
111: * @throws FlowExecutionException if an exception was thrown within a state
112: * of the resumed flow execution during event processing
113: */
114: public ViewSelection signalEvent(String eventId,
115: ExternalContext context) throws FlowExecutionException;
116:
117: /**
118: * Refresh this flow execution, asking the current view selection to be
119: * reconstituted to support reissuing the last response. This is an idempotent
120: * operation that may be safely called on a paused execution.
121: * @param context the externa context in which the refresh event occured
122: * @return the current view selection for this flow execution
123: * @throws FlowExecutionException if an exception was thrown within a state
124: * of the resumed flow execution during event processing
125: */
126: public ViewSelection refresh(ExternalContext context)
127: throws FlowExecutionException;
128: }
|