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.AttributeMap;
020: import org.springframework.webflow.core.collection.MutableAttributeMap;
021: import org.springframework.webflow.core.collection.ParameterMap;
022: import org.springframework.webflow.definition.FlowDefinition;
023: import org.springframework.webflow.definition.StateDefinition;
024: import org.springframework.webflow.definition.TransitionDefinition;
025:
026: /**
027: * A context for a single request to manipulate a flow execution. Allows Web
028: * Flow users to access contextual information about the executing request, as
029: * well as the governing
030: * {@link #getFlowExecutionContext() active flow execution}.
031: * <p>
032: * The term <i>request</i> is used to describe a single call (thread) into the
033: * flow system by an external actor to manipulate exactly one flow execution.
034: * <p>
035: * A new instance of this object is typically created when one of the core
036: * operations supported by a flow execution is invoked, either
037: * <code>start</code> to launch the flow execution, <code>signalEvent</code>
038: * to resume the flow execution, or <code>refresh</code> to reconstitute the
039: * flow execution's last view selection for purposes of reissuing a user
040: * response.
041: * <p>
042: * Once created this context object is passed around throughout flow execution
043: * request processing where it may be accessed and reasoned upon by SWF-internal
044: * artifacts such as states, user-implemented action code, and state transition
045: * criteria.
046: * <p>
047: * When a call into a flow execution returns this object goes out of scope and
048: * is disposed of automatically. Thus a request context is an internal artifact
049: * used within a FlowExecution: this object is not exposed to external client
050: * code, e.g. a view implementation (JSP).
051: * <p>
052: * The {@link #getRequestScope() requestScope} property may be used as a store
053: * for arbitrary data that should exist for the life of this object.
054: * Request-scoped data, along with all data in {@link #getFlashScope() flash scope},
055: * {@link #getFlowScope() flow scope} and
056: * {@link #getConversationScope() conversation scope} is available for exposing
057: * to view templates via a {@link #getModel() model} property.
058: * <p>
059: * The web flow system will ensure that a RequestContext object is local to the
060: * current thread. It can be safely manipulated without needing to worry about
061: * concurrent access.
062: * <p>
063: * Note: this request context is in no way linked to an HTTP or Portlet request.
064: * It uses the familiar "request" naming convention to indicate a single call to
065: * manipulate a runtime execution of a flow definition.
066: *
067: * @author Keith Donald
068: * @author Erwin Vervaet
069: */
070: public interface RequestContext {
071:
072: /**
073: * Returns the definition of the flow that is currently executing.
074: * @return the flow definition for the active session
075: * @throws IllegalStateException if the flow execution has not been started
076: * at all, or if the execution has ended and is no longer actively executing
077: */
078: public FlowDefinition getActiveFlow() throws IllegalStateException;
079:
080: /**
081: * Returns the current state of the executing flow. May return
082: * <code>null</code> if this flow execution is in the process of starting
083: * and has not yet entered its start state.
084: * @return the current state, or <code>null</code> if in the process of
085: * starting
086: * @throws IllegalStateException if this flow execution has not been started
087: * at all, or if this execution has ended and is no longer actively
088: * executing
089: */
090: public StateDefinition getCurrentState()
091: throws IllegalStateException;
092:
093: /**
094: * Returns a mutable accessor for accessing and/or setting attributes in
095: * request scope. <b>Request scoped attributes exist for the duration of
096: * this request only.</b>
097: * @return the request scope
098: */
099: public MutableAttributeMap getRequestScope();
100:
101: /**
102: * Returns a mutable accessor for accessing and/or setting attributes in
103: * flash scope. <b>Flash scoped attributes exist untill the next event
104: * is signaled in the flow execution.</b>
105: * @return the flash scope
106: */
107: public MutableAttributeMap getFlashScope();
108:
109: /**
110: * Returns a mutable accessor for accessing and/or setting attributes in
111: * flow scope. <b>Flow scoped attributes exist for the life of the active
112: * flow session.</b>
113: * @return the flow scope
114: * @see FlowSession
115: */
116: public MutableAttributeMap getFlowScope();
117:
118: /**
119: * Returns a mutable accessor for accessing and/or setting attributes in
120: * conversation scope. <b>Conversation scoped attributes exist for the life
121: * of the executing flow and are shared across all flow sessions.</b>
122: * @return the conversation scope
123: * @see FlowExecutionContext
124: */
125: public MutableAttributeMap getConversationScope();
126:
127: /**
128: * Returns the immutable input parameters associated with this request into
129: * Spring Web Flow. The map returned is immutable and cannot be changed.
130: * <p>
131: * This is typically a convenient shortcut for accessing the
132: * {@link ExternalContext#getRequestParameterMap()} directly.
133: * @see #getExternalContext()
134: */
135: public ParameterMap getRequestParameters();
136:
137: /**
138: * Returns the external client context that originated (or triggered) this
139: * request.
140: * <p>
141: * Acting as a facade, the returned context object provides a single point
142: * of access to the calling client's environment. It provides normalized
143: * access to attributes of the client environment without tying you to
144: * specific constructs within that environment.
145: * <p>
146: * In addition, this context may be downcastable to a specific context type
147: * for a specific client environment, such as a
148: * {@link org.springframework.webflow.context.servlet.ServletExternalContext}
149: * for servlets or a
150: * {@link org.springframework.webflow.context.portlet.PortletExternalContext}
151: * for portlets. Such downcasting will give you full access to a native
152: * HttpServletRequest, for example. With that said, for portability reasons
153: * you should avoid coupling your flow artifacts to a specific deployment
154: * environment when possible.
155: * @return the originating external context, the one that triggered the
156: * current execution request
157: */
158: public ExternalContext getExternalContext();
159:
160: /**
161: * Returns contextual information about the flow execution itself.
162: * Information in this context typically spans more than one request.
163: * @return the flow execution context
164: */
165: public FlowExecutionContext getFlowExecutionContext();
166:
167: /**
168: * Returns the last event signaled during this request. The event may or may
169: * not have caused a state transition to happen.
170: * @return the last signaled event, or null if no event has been signaled yet
171: */
172: public Event getLastEvent();
173:
174: /**
175: * Returns the last state transition that executed in this request.
176: * @return the last transition, or <code>null</code> if no transition has
177: * occured yet
178: */
179: public TransitionDefinition getLastTransition();
180:
181: /**
182: * Returns a context map for accessing arbitrary attributes about the state
183: * of the current request. These attributes may be used to influence flow
184: * execution behavior.
185: * @return the current attributes of this request, or empty if not set
186: */
187: public AttributeMap getAttributes();
188:
189: /**
190: * Set the contextual attributes describing the state of this request.
191: * Overwrites any pre-existing collection.
192: * @param attributes the attributes
193: */
194: public void setAttributes(AttributeMap attributes);
195:
196: /**
197: * Returns the data model capturing the state of this context, suitable for
198: * exposing to clients (mostly web views). Typically the model will contain
199: * the union of the data available in request, flash, session and conversation
200: * scope.
201: * @return the model that can be exposed to a client view for rendering
202: * purposes
203: */
204: public AttributeMap getModel();
205:
206: }
|