org.springframework.webflow.execution.RequestContext Maven / Gradle / Ivy
/*
* Copyright 2004-2012 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.webflow.execution;
import org.springframework.binding.message.MessageContext;
import org.springframework.webflow.context.ExternalContext;
import org.springframework.webflow.core.collection.MutableAttributeMap;
import org.springframework.webflow.core.collection.ParameterMap;
import org.springframework.webflow.definition.FlowDefinition;
import org.springframework.webflow.definition.StateDefinition;
import org.springframework.webflow.definition.TransitionDefinition;
/**
* A context for a single request to manipulate a flow execution. Allows Web Flow users to access contextual information
* about the executing request, as well as the governing {@link #getFlowExecutionContext() active flow execution}.
*
* The term request is used to describe a single call (thread) into the flow system by an external actor to
* manipulate exactly one flow execution.
*
* A new instance of this object is typically created when one of the core operations supported by a flow execution is
* invoked, either start to launch the flow execution, signalEvent to resume the flow
* execution, or refresh to reconstitute the flow execution's last view selection for purposes of reissuing
* a user response.
*
* Once created this context object is passed around throughout flow execution request processing where it may be
* accessed and reasoned upon by SWF-internal artifacts such as states, user-implemented action code, and state
* transition criteria.
*
* When a call into a flow execution returns this object goes out of scope and is disposed of automatically. Thus a
* request context is an internal artifact used within a FlowExecution: this object is not exposed to external client
* code, e.g. a view implementation (JSP).
*
* The {@link #getRequestScope() requestScope} property may be used as a store for arbitrary data that should exist for
* the life of this object.
*
* The web flow system will ensure that a RequestContext object is local to the current thread. It can be safely
* manipulated without needing to worry about concurrent access.
*
* Note: this request context is in no way linked to an HTTP request. It uses the familiar "request" naming
* convention to indicate a single call to manipulate a runtime execution of a flow definition.
*
* @author Keith Donald
* @author Erwin Vervaet
*/
public interface RequestContext {
/**
* Returns the definition of the flow that is currently executing.
* @return the flow definition for the active session
* @throws IllegalStateException if the flow execution is not active
* @see FlowExecutionContext#isActive()
*/
FlowDefinition getActiveFlow() throws IllegalStateException;
/**
* Returns the current state of the executing flow. Returns null if the active flow's start state has
* not yet been entered.
* @return the current state, or null if in the process of starting
* @throws IllegalStateException if this flow execution is not active
* @see FlowExecutionContext#isActive()
*/
StateDefinition getCurrentState() throws IllegalStateException;
/**
* Returns the transition that would execute on the occurrence of the given event.
* @param eventId the id of the user event
* @return the transition that would trigger, or null if no transition matches
* @throws IllegalStateException if this flow execution is not active
* @see FlowExecutionContext#isActive()
*/
TransitionDefinition getMatchingTransition(String eventId) throws IllegalStateException;
/**
* Returns true if the flow is currently active and in a view state. When in a view state {@link #getViewScope()},
* can be safely called.
* @see #getViewScope()
* @return true if in a view state, false if not
*/
boolean inViewState();
/**
* Returns a mutable map for accessing and/or setting attributes in request scope. Request scoped attributes
* exist for the duration of this request only.
* @return the request scope
*/
MutableAttributeMap