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.engine;
017:
018: import org.springframework.webflow.core.collection.MutableAttributeMap;
019: import org.springframework.webflow.execution.Event;
020: import org.springframework.webflow.execution.FlowExecutionContext;
021: import org.springframework.webflow.execution.FlowExecutionException;
022: import org.springframework.webflow.execution.FlowSession;
023: import org.springframework.webflow.execution.RequestContext;
024: import org.springframework.webflow.execution.ViewSelection;
025:
026: /**
027: * Mutable control interface used to manipulate an ongoing flow execution in the
028: * context of one client request. Primarily used internally by the various flow
029: * artifacts when they are invoked.
030: * <p>
031: * This interface acts as a facade for core definition constructs such as the
032: * central <code>Flow</code> and <code>State</code> classes, abstracting
033: * away details about the runtime execution machine defined in the
034: * {@link org.springframework.webflow.engine.impl execution engine implementation}
035: * package.
036: * <p>
037: * Note this type is not the same as the {@link FlowExecutionContext}. Objects
038: * of this type are <i>request specific</i>: they provide a control interface
039: * for manipulating exactly one flow execution locally from exactly one request.
040: * A <code>FlowExecutionContext</code> provides information about a single
041: * flow execution (conversation), and it's scope is not local to a specific
042: * request (or thread).
043: *
044: * @see org.springframework.webflow.engine.Flow
045: * @see org.springframework.webflow.engine.State
046: * @see org.springframework.webflow.execution.FlowExecution
047: * @see FlowExecutionContext
048: *
049: * @author Keith Donald
050: * @author Erwin Vervaet
051: */
052: public interface RequestControlContext extends RequestContext {
053:
054: /**
055: * Record the last event signaled in the executing flow. This method will be
056: * called as part of signaling an event in a flow to indicate the
057: * 'lastEvent' that was signaled.
058: * @param lastEvent the last event signaled
059: * @see Flow#onEvent(RequestControlContext)
060: */
061: public void setLastEvent(Event lastEvent);
062:
063: /**
064: * Record the last transition that executed in the executing flow. This
065: * method will be called as part of executing a transition from one state to
066: * another.
067: * @param lastTransition the last transition that executed
068: * @see Transition#execute(State, RequestControlContext)
069: */
070: public void setLastTransition(Transition lastTransition);
071:
072: /**
073: * Record the current state that has entered in the executing flow. This
074: * method will be called as part of entering a new state by the State type
075: * itself.
076: * @param state the current state
077: * @see State#enter(RequestControlContext)
078: */
079: public void setCurrentState(State state);
080:
081: /**
082: * Spawn a new flow session and activate it in the currently executing flow.
083: * Also transitions the spawned flow to its start state. This method should
084: * be called by clients that wish to spawn new flows, such as subflow
085: * states.
086: * <p>
087: * This will start a new flow session in the current flow execution, which
088: * is already active.
089: * @param flow the flow to start, its <code>start()</code> method will be
090: * called
091: * @param input initial contents of the newly created flow session (may be
092: * <code>null</code>, e.g. empty)
093: * @return the selected starting view, which returns control to the client
094: * and requests that a view be rendered with model data
095: * @throws FlowExecutionException if an exception was thrown within a state
096: * of the flow during execution of this start operation
097: * @see Flow#start(RequestControlContext, MutableAttributeMap)
098: */
099: public ViewSelection start(Flow flow, MutableAttributeMap input)
100: throws FlowExecutionException;
101:
102: /**
103: * Signals the occurence of an event in the current state of this flow
104: * execution request context. This method should be called by clients that
105: * report internal event occurences, such as action states. The
106: * <code>onEvent()</code> method of the flow involved in the flow
107: * execution will be called.
108: * @param event the event that occured
109: * @return the next selected view, which returns control to the client and
110: * requests that a view be rendered with model data
111: * @throws FlowExecutionException if an exception was thrown within a state
112: * of the flow during execution of this signalEvent operation
113: * @see Flow#onEvent(RequestControlContext)
114: */
115: public ViewSelection signalEvent(Event event)
116: throws FlowExecutionException;
117:
118: /**
119: * End the active flow session of the current flow execution. This method
120: * should be called by clients that terminate flows, such as end states. The
121: * <code>end()</code> method of the flow involved in the flow execution
122: * will be called.
123: * @param output output produced by the session that is eligible for mapping
124: * by a resuming parent flow
125: * @return the ended session
126: * @throws IllegalStateException when the flow execution is not active
127: * @see Flow#end(RequestControlContext, MutableAttributeMap)
128: */
129: public FlowSession endActiveFlowSession(MutableAttributeMap output)
130: throws IllegalStateException;
131:
132: /**
133: * Execute this transition out of the current source state. Allows for
134: * privileged execution of an arbitrary transition.
135: * @param transition the transition
136: * @return a new view selection
137: * @see Transition#execute(State, RequestControlContext)
138: */
139: public ViewSelection execute(Transition transition);
140:
141: }
|