KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > webflow > engine > RequestControlContext


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.engine;
17
18 import org.springframework.webflow.core.collection.MutableAttributeMap;
19 import org.springframework.webflow.execution.Event;
20 import org.springframework.webflow.execution.FlowExecutionContext;
21 import org.springframework.webflow.execution.FlowExecutionException;
22 import org.springframework.webflow.execution.FlowSession;
23 import org.springframework.webflow.execution.RequestContext;
24 import org.springframework.webflow.execution.ViewSelection;
25
26 /**
27  * Mutable control interface used to manipulate an ongoing flow execution in the
28  * context of one client request. Primarily used internally by the various flow
29  * artifacts when they are invoked.
30  * <p>
31  * This interface acts as a facade for core definition constructs such as the
32  * central <code>Flow</code> and <code>State</code> classes, abstracting
33  * away details about the runtime execution machine defined in the
34  * {@link org.springframework.webflow.engine.impl execution engine implementation}
35  * package.
36  * <p>
37  * Note this type is not the same as the {@link FlowExecutionContext}. Objects
38  * of this type are <i>request specific</i>: they provide a control interface
39  * for manipulating exactly one flow execution locally from exactly one request.
40  * A <code>FlowExecutionContext</code> provides information about a single
41  * flow execution (conversation), and it's scope is not local to a specific
42  * request (or thread).
43  *
44  * @see org.springframework.webflow.engine.Flow
45  * @see org.springframework.webflow.engine.State
46  * @see org.springframework.webflow.execution.FlowExecution
47  * @see FlowExecutionContext
48  *
49  * @author Keith Donald
50  * @author Erwin Vervaet
51  */
52 public interface RequestControlContext extends RequestContext {
53
54     /**
55      * Record the last event signaled in the executing flow. This method will be
56      * called as part of signaling an event in a flow to indicate the
57      * 'lastEvent' that was signaled.
58      * @param lastEvent the last event signaled
59      * @see Flow#onEvent(RequestControlContext)
60      */
61     public void setLastEvent(Event lastEvent);
62
63     /**
64      * Record the last transition that executed in the executing flow. This
65      * method will be called as part of executing a transition from one state to
66      * another.
67      * @param lastTransition the last transition that executed
68      * @see Transition#execute(State, RequestControlContext)
69      */
70     public void setLastTransition(Transition lastTransition);
71
72     /**
73      * Record the current state that has entered in the executing flow. This
74      * method will be called as part of entering a new state by the State type
75      * itself.
76      * @param state the current state
77      * @see State#enter(RequestControlContext)
78      */
79     public void setCurrentState(State state);
80
81     /**
82      * Spawn a new flow session and activate it in the currently executing flow.
83      * Also transitions the spawned flow to its start state. This method should
84      * be called by clients that wish to spawn new flows, such as subflow
85      * states.
86      * <p>
87      * This will start a new flow session in the current flow execution, which
88      * is already active.
89      * @param flow the flow to start, its <code>start()</code> method will be
90      * called
91      * @param input initial contents of the newly created flow session (may be
92      * <code>null</code>, e.g. empty)
93      * @return the selected starting view, which returns control to the client
94      * and requests that a view be rendered with model data
95      * @throws FlowExecutionException if an exception was thrown within a state
96      * of the flow during execution of this start operation
97      * @see Flow#start(RequestControlContext, MutableAttributeMap)
98      */
99     public ViewSelection start(Flow flow, MutableAttributeMap input) throws FlowExecutionException;
100
101     /**
102      * Signals the occurence of an event in the current state of this flow
103      * execution request context. This method should be called by clients that
104      * report internal event occurences, such as action states. The
105      * <code>onEvent()</code> method of the flow involved in the flow
106      * execution will be called.
107      * @param event the event that occured
108      * @return the next selected view, which returns control to the client and
109      * requests that a view be rendered with model data
110      * @throws FlowExecutionException if an exception was thrown within a state
111      * of the flow during execution of this signalEvent operation
112      * @see Flow#onEvent(RequestControlContext)
113      */
114     public ViewSelection signalEvent(Event event) throws FlowExecutionException;
115
116     /**
117      * End the active flow session of the current flow execution. This method
118      * should be called by clients that terminate flows, such as end states. The
119      * <code>end()</code> method of the flow involved in the flow execution
120      * will be called.
121      * @param output output produced by the session that is eligible for mapping
122      * by a resuming parent flow
123      * @return the ended session
124      * @throws IllegalStateException when the flow execution is not active
125      * @see Flow#end(RequestControlContext, MutableAttributeMap)
126      */
127     public FlowSession endActiveFlowSession(MutableAttributeMap output) throws IllegalStateException JavaDoc;
128
129     /**
130      * Execute this transition out of the current source state. Allows for
131      * privileged execution of an arbitrary transition.
132      * @param transition the transition
133      * @return a new view selection
134      * @see Transition#execute(State, RequestControlContext)
135      */
136     public ViewSelection execute(Transition transition);
137
138 }
Popular Tags