org.springframework.webflow.execution.FlowExecution Maven / Gradle / Ivy
/*
* Copyright 2002-2006 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.webflow.context.ExternalContext;
import org.springframework.webflow.core.collection.MutableAttributeMap;
import org.springframework.webflow.definition.FlowDefinition;
/**
* A top-level instance of a flow definition that carries out definition
* execution on behalf of a single client. Typically used to support the
* orchestration of a web conversation.
*
* This is the central facade interface for manipulating one runtime execution
* of a flow definition. Implementations of this interface are the finite state
* machine that is the heart of Spring Web Flow.
*
* Typically, when a client wants to launch a flow execution at production time,
* she passes the id of the governing {@link FlowDefinition flow definition} to
* a coordinating
* {@link org.springframework.webflow.executor.FlowExecutor#launch(String, ExternalContext) flow executor}.
* This coordinator then typically uses a
* {@link FlowExecutionFactory flow execution factory} to create an object
* implementing this interface, initializing it with the requested flow
* definition which becomes the execution's "root" or top-level flow.
*
* After execution creation, the
* {@link #start(MutableAttributeMap, ExternalContext) start} operation is
* called, which causes this execution to activate a new
* {@link FlowSession session} for its root flow definition. That session is
* then said to become the active flow. An execution
* {@link RequestContext request context} is created, the Flow's
* {@link FlowDefinition#getStartState() start state} is entered, and the
* request is processed.
*
* In a distributed environment such as HTTP, after a call into this object has
* completed and control returns to the caller, this execution object (if still
* active) is typically saved out to a repository before the server request
* ends. For example it might be saved out to the HttpSession, a Database, or a
* client-side hidden form field for later restoration and manipulation. This
* execution persistence is the responsibility of the
* {@link org.springframework.webflow.execution.repository.FlowExecutionRepository flow execution repository}
* subsystem.
*
* Subsequent requests from the client to manipuate this flow execution trigger
* restoration of this object, followed by an invocation of the
* {@link #signalEvent(String, ExternalContext) signal event} operation. The
* signalEvent operation resumes this execution by indicating what action the
* user took from within the current state; for example, the user may have
* pressed the "submit" button, or pressed "cancel". After the user
* event is processed, control again goes back to the caller and if this
* execution is still active, it is again saved out to the repository.
*
* This process continues until a client event causes this flow execution to end
* (by the root flow reaching an end state). At that time this object is no
* longer active, and is removed from the repository and discarded.
*
* Flow executions can have their lifecycle observed by {@link FlowExecutionListener listeners}.
*
* @see FlowDefinition
* @see FlowSession
* @see RequestContext
* @see FlowExecutionListener
* @see org.springframework.webflow.execution.repository.FlowExecutionRepository
* @see org.springframework.webflow.executor.FlowExecutor
*
* @author Keith Donald
* @author Erwin Vervaet
*/
public interface FlowExecution extends FlowExecutionContext {
/**
* Start this flow execution, transitioning it to the root flow's start
* state and returning the starting view selection needed to issue an
* initial user response. Typically called by a flow executor on behalf of a
* browser client, but also from test code.
*
* This will start the entire flow execution from scratch.
* @param input input attributes to pass to the flow, which the flow may
* choose to map into its scope
* @param context the external context in which the starting event occured
* @return the starting view selection, a value object to be used to issue a
* suitable response to the caller
* @throws FlowExecutionException if an exception was thrown within a state
* of the flow execution during request processing
*/
public ViewSelection start(MutableAttributeMap input, ExternalContext context) throws FlowExecutionException;
/**
* Signal an occurrence of the specified user event in the current state of
* this executing flow. The event will be processed in full and control will
* be returned once event processing is complete.
* @param eventId the identifier of the user event that occured
* @param context the external context in which the event occured
* @return the next view selection to render, used by the calling executor
* to issue a suitable response to the client
* @throws FlowExecutionException if an exception was thrown within a state
* of the resumed flow execution during event processing
*/
public ViewSelection signalEvent(String eventId, ExternalContext context) throws FlowExecutionException;
/**
* Refresh this flow execution, asking the current view selection to be
* reconstituted to support reissuing the last response. This is an idempotent
* operation that may be safely called on a paused execution.
* @param context the externa context in which the refresh event occured
* @return the current view selection for this flow execution
* @throws FlowExecutionException if an exception was thrown within a state
* of the resumed flow execution during event processing
*/
public ViewSelection refresh(ExternalContext context) throws FlowExecutionException;
}