KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > webflow > execution > RequestContext


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.AttributeMap;
20 import org.springframework.webflow.core.collection.MutableAttributeMap;
21 import org.springframework.webflow.core.collection.ParameterMap;
22 import org.springframework.webflow.definition.FlowDefinition;
23 import org.springframework.webflow.definition.StateDefinition;
24 import org.springframework.webflow.definition.TransitionDefinition;
25
26 /**
27  * A context for a single request to manipulate a flow execution. Allows Web
28  * Flow users to access contextual information about the executing request, as
29  * well as the governing
30  * {@link #getFlowExecutionContext() active flow execution}.
31  * <p>
32  * The term <i>request</i> is used to describe a single call (thread) into the
33  * flow system by an external actor to manipulate exactly one flow execution.
34  * <p>
35  * A new instance of this object is typically created when one of the core
36  * operations supported by a flow execution is invoked, either
37  * <code>start</code> to launch the flow execution, <code>signalEvent</code>
38  * to resume the flow execution, or <code>refresh</code> to reconstitute the
39  * flow execution's last view selection for purposes of reissuing a user
40  * response.
41  * <p>
42  * Once created this context object is passed around throughout flow execution
43  * request processing where it may be accessed and reasoned upon by SWF-internal
44  * artifacts such as states, user-implemented action code, and state transition
45  * criteria.
46  * <p>
47  * When a call into a flow execution returns this object goes out of scope and
48  * is disposed of automatically. Thus a request context is an internal artifact
49  * used within a FlowExecution: this object is not exposed to external client
50  * code, e.g. a view implementation (JSP).
51  * <p>
52  * The {@link #getRequestScope() requestScope} property may be used as a store
53  * for arbitrary data that should exist for the life of this object.
54  * Request-scoped data, along with all data in {@link #getFlashScope() flash scope},
55  * {@link #getFlowScope() flow scope} and
56  * {@link #getConversationScope() conversation scope} is available for exposing
57  * to view templates via a {@link #getModel() model} property.
58  * <p>
59  * The web flow system will ensure that a RequestContext object is local to the
60  * current thread. It can be safely manipulated without needing to worry about
61  * concurrent access.
62  * <p>
63  * Note: this request context is in no way linked to an HTTP or Portlet request.
64  * It uses the familiar "request" naming convention to indicate a single call to
65  * manipulate a runtime execution of a flow definition.
66  *
67  * @author Keith Donald
68  * @author Erwin Vervaet
69  */
70 public interface RequestContext {
71
72     /**
73      * Returns the definition of the flow that is currently executing.
74      * @return the flow definition for the active session
75      * @throws IllegalStateException if the flow execution has not been started
76      * at all, or if the execution has ended and is no longer actively executing
77      */
78     public FlowDefinition getActiveFlow() throws IllegalStateException JavaDoc;
79
80     /**
81      * Returns the current state of the executing flow. May return
82      * <code>null</code> if this flow execution is in the process of starting
83      * and has not yet entered its start state.
84      * @return the current state, or <code>null</code> if in the process of
85      * starting
86      * @throws IllegalStateException if this flow execution has not been started
87      * at all, or if this execution has ended and is no longer actively
88      * executing
89      */
90     public StateDefinition getCurrentState() throws IllegalStateException JavaDoc;
91
92     /**
93      * Returns a mutable accessor for accessing and/or setting attributes in
94      * request scope. <b>Request scoped attributes exist for the duration of
95      * this request only.</b>
96      * @return the request scope
97      */
98     public MutableAttributeMap getRequestScope();
99
100     /**
101      * Returns a mutable accessor for accessing and/or setting attributes in
102      * flash scope. <b>Flash scoped attributes exist untill the next event
103      * is signaled in the flow execution.</b>
104      * @return the flash scope
105      */
106     public MutableAttributeMap getFlashScope();
107
108     /**
109      * Returns a mutable accessor for accessing and/or setting attributes in
110      * flow scope. <b>Flow scoped attributes exist for the life of the active
111      * flow session.</b>
112      * @return the flow scope
113      * @see FlowSession
114      */
115     public MutableAttributeMap getFlowScope();
116
117     /**
118      * Returns a mutable accessor for accessing and/or setting attributes in
119      * conversation scope. <b>Conversation scoped attributes exist for the life
120      * of the executing flow and are shared across all flow sessions.</b>
121      * @return the conversation scope
122      * @see FlowExecutionContext
123      */
124     public MutableAttributeMap getConversationScope();
125
126     /**
127      * Returns the immutable input parameters associated with this request into
128      * Spring Web Flow. The map returned is immutable and cannot be changed.
129      * <p>
130      * This is typically a convenient shortcut for accessing the
131      * {@link ExternalContext#getRequestParameterMap()} directly.
132      * @see #getExternalContext()
133      */
134     public ParameterMap getRequestParameters();
135
136     /**
137      * Returns the external client context that originated (or triggered) this
138      * request.
139      * <p>
140      * Acting as a facade, the returned context object provides a single point
141      * of access to the calling client's environment. It provides normalized
142      * access to attributes of the client environment without tying you to
143      * specific constructs within that environment.
144      * <p>
145      * In addition, this context may be downcastable to a specific context type
146      * for a specific client environment, such as a
147      * {@link org.springframework.webflow.context.servlet.ServletExternalContext}
148      * for servlets or a
149      * {@link org.springframework.webflow.context.portlet.PortletExternalContext}
150      * for portlets. Such downcasting will give you full access to a native
151      * HttpServletRequest, for example. With that said, for portability reasons
152      * you should avoid coupling your flow artifacts to a specific deployment
153      * environment when possible.
154      * @return the originating external context, the one that triggered the
155      * current execution request
156      */
157     public ExternalContext getExternalContext();
158
159     /**
160      * Returns contextual information about the flow execution itself.
161      * Information in this context typically spans more than one request.
162      * @return the flow execution context
163      */
164     public FlowExecutionContext getFlowExecutionContext();
165
166     /**
167      * Returns the last event signaled during this request. The event may or may
168      * not have caused a state transition to happen.
169      * @return the last signaled event
170      */
171     public Event getLastEvent();
172
173     /**
174      * Returns the last state transition that executed in this request.
175      * @return the last transition, or <code>null</code> if no transition has
176      * occured yet
177      */
178     public TransitionDefinition getLastTransition();
179
180     /**
181      * Returns a context map for accessing arbitrary attributes about the state
182      * of the current request. These attributes may be used to influence flow
183      * execution behavior.
184      * @return the current attributes of this request, or empty if not set
185      */
186     public AttributeMap getAttributes();
187
188     /**
189      * Set the contextual attributes describing the state of this request.
190      * Overwrites any pre-existing collection.
191      * @param attributes the attributes
192      */
193     public void setAttributes(AttributeMap attributes);
194
195     /**
196      * Returns the data model capturing the state of this context, suitable for
197      * exposing to clients (mostly web views). Typically the model will contain
198      * the union of the data available in request, flash, session and conversation
199      * scope.
200      * @return the model that can be exposed to a client view for rendering
201      * purposes
202      */
203     public AttributeMap getModel();
204
205 }
Popular Tags