FlowExecution


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.springframework.webflow.execution;
17  
18  import org.springframework.webflow.context.ExternalContext;
19  import org.springframework.webflow.core.collection.MutableAttributeMap;
20  import org.springframework.webflow.definition.FlowDefinition;
21  
22  /**
23   * A top-level instance of a flow definition that carries out definition
24   * execution on behalf of a single client. Typically used to support the
25   * orchestration of a web conversation.
26   * <p>
27   * This is the central facade interface for manipulating one runtime execution
28   * of a flow definition. Implementations of this interface are the finite state
29   * machine that is the heart of Spring Web Flow.
30   * <p>
31   * Typically, when a client wants to launch a flow execution at production time,
32   * she passes the id of the governing {@link FlowDefinition flow definition} to
33   * a coordinating
34   * {@link org.springframework.webflow.executor.FlowExecutor#launch(String, ExternalContext) flow executor}.
35   * This coordinator then typically uses a
36   * {@link FlowExecutionFactory flow execution factory} to create an object
37   * implementing this interface, initializing it with the requested flow
38   * definition which becomes the execution's "root" or top-level flow.
39   * <p>
40   * After execution creation, the
41   * {@link #start(MutableAttributeMap, ExternalContext) start} operation is
42   * called, which causes this execution to activate a new
43   * {@link FlowSession session} for its root flow definition. That session is
44   * then said to become the <i>active flow</i>. An execution
45   * {@link RequestContext request context} is created, the Flow's
46   * {@link FlowDefinition#getStartState() start state} is entered, and the
47   * request is processed.
48   * <p>
49   * In a distributed environment such as HTTP, after a call into this object has
50   * completed and control returns to the caller, this execution object (if still
51   * active) is typically saved out to a repository before the server request
52   * ends. For example it might be saved out to the HttpSession, a Database, or a
53   * client-side hidden form field for later restoration and manipulation. This
54   * execution persistence is the responsibility of the
55   * {@link org.springframework.webflow.execution.repository.FlowExecutionRepository flow execution repository}
56   * subsystem.
57   * <p>
58   * Subsequent requests from the client to manipuate this flow execution trigger
59   * restoration of this object, followed by an invocation of the
60   * {@link #signalEvent(String, ExternalContext) signal event} operation. The
61   * signalEvent operation resumes this execution by indicating what action the
62   * user took from within the current state; for example, the user may have
63   * pressed the "submit" button, or pressed "cancel". After the user
64   * event is processed, control again goes back to the caller and if this
65   * execution is still active, it is again saved out to the repository.
66   * <p>
67   * This process continues until a client event causes this flow execution to end
68   * (by the root flow reaching an end state). At that time this object is no
69   * longer active, and is removed from the repository and discarded.
70   * <p>
71   * Flow executions can have their lifecycle observed by {@link FlowExecutionListener listeners}.
72   * 
73   * @see FlowDefinition
74   * @see FlowSession
75   * @see RequestContext
76   * @see FlowExecutionListener
77   * @see org.springframework.webflow.execution.repository.FlowExecutionRepository
78   * @see org.springframework.webflow.executor.FlowExecutor
79   * 
80   * @author Keith Donald
81   * @author Erwin Vervaet
82   */
83  public interface FlowExecution extends FlowExecutionContext {
84  
85      /**
86       * Start this flow execution, transitioning it to the root flow's start
87       * state and returning the starting view selection needed to issue an
88       * initial user response. Typically called by a flow executor on behalf of a
89       * browser client, but also from test code.
90       * <p>
91       * This will start the entire flow execution <i>from scratch</i>.
92       * @param input input attributes to pass to the flow, which the flow may
93       * choose to map into its scope
94       * @param context the external context in which the starting event occured
95       * @return the starting view selection, a value object to be used to issue a
96       * suitable response to the caller
97       * @throws FlowExecutionException if an exception was thrown within a state
98       * of the flow execution during request processing
99       */
100     public ViewSelection start(MutableAttributeMap input, ExternalContext context) throws FlowExecutionException;
101 
102     /**
103      * Signal an occurrence of the specified user event in the current state of
104      * this executing flow. The event will be processed in full and control will
105      * be returned once event processing is complete.
106      * @param eventId the identifier of the user event that occured
107      * @param context the external context in which the event occured
108      * @return the next view selection to render, used by the calling executor
109      * to issue a suitable response to the client
110      * @throws FlowExecutionException if an exception was thrown within a state
111      * of the resumed flow execution during event processing
112      */
113     public ViewSelection signalEvent(String   eventId, ExternalContext context) throws FlowExecutionException;
114 
115     /**
116      * Refresh this flow execution, asking the current view selection to be
117      * reconstituted to support reissuing the last response. This is an idempotent
118      * operation that may be safely called on a paused execution.
119      * @param context the externa context in which the refresh event occured
120      * @return the current view selection for this flow execution
121      * @throws FlowExecutionException if an exception was thrown within a state
122      * of the resumed flow execution during event processing
123      */
124     public ViewSelection refresh(ExternalContext context) throws FlowExecutionException;
125 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags