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.core.collection.MutableAttributeMap;
019: import org.springframework.webflow.definition.FlowDefinition;
020: import org.springframework.webflow.definition.StateDefinition;
021:
022: /**
023: * A single, local instantiation of a {@link FlowDefinition flow definition}
024: * launched within an overall flow execution.
025: * <p>
026: * This object maintains all instance state including session status within
027: * exactly one governing FlowExecution, as well as the current flow state. This
028: * object also acts as the local "flow scope" data model. Data in
029: * {@link #getScope() flow scope} lives for the life of this object and is
030: * cleaned up automatically when this object is destroyed. Destruction happens
031: * when this session enters an end state.
032: * <p>
033: * A flow session will go through several status changes during its lifecycle.
034: * Initially it will be {@link FlowSessionStatus#CREATED} when a new execution
035: * is started.
036: * <p>
037: * After passing through the {@link FlowSessionStatus#STARTING} status, the flow
038: * session is activated (about to be manipulated) and its status becomes
039: * {@link FlowSessionStatus#ACTIVE}. In the case of a new execution session
040: * activation happens immediately after creation to put the "root flow" at the
041: * top of the stack and transition it to its start state.
042: * <p>
043: * When control returns to the client for user think time the status is updated
044: * to {@link FlowSessionStatus#PAUSED}. The flow is no longer actively
045: * processing then, as it is stored off to a repository waiting on the user to
046: * resume.
047: * <p>
048: * If a flow session is pushed down in the stack because a subflow is spawned,
049: * its status becomes {@link FlowSessionStatus#SUSPENDED} until the subflow
050: * returns (ends) and is popped off the stack. The resuming flow session then
051: * becomes active once again.
052: * <p>
053: * When a flow session is terminated because an EndState is reached its status
054: * becomes {@link FlowSessionStatus#ENDED}, which ends its life. When this
055: * happens the session is popped off the stack and discarded, and any allocated
056: * resources in "flow scope" are automatically cleaned up.
057: * <p>
058: * Note that a flow <i>session</i> is in no way linked to an HTTP session. It
059: * just uses the familiar "session" naming convention to denote a stateful
060: * object.
061: *
062: * @see FlowDefinition
063: * @see FlowExecution
064: * @see FlowSessionStatus
065: *
066: * @author Keith Donald
067: * @author Erwin Vervaet
068: */
069: public interface FlowSession {
070:
071: /**
072: * Returns the flow definition backing this session.
073: */
074: public FlowDefinition getDefinition();
075:
076: /**
077: * Returns the current state of this flow session. This value changes as the
078: * flow executes.
079: */
080: public StateDefinition getState();
081:
082: /**
083: * Returns the current status of this flow session. This value changes as
084: * the flow executes.
085: */
086: public FlowSessionStatus getStatus();
087:
088: /**
089: * Return this session's local attributes; the basis for "flow scope" (flow
090: * session scope).
091: * @return the flow scope attributes
092: */
093: public MutableAttributeMap getScope();
094:
095: /**
096: * Returns the local "flash map". Attributes in this map are cleared out
097: * on the next event signaled in the flow execution, so they survive a refresh.
098: * @return the flash map
099: */
100: public MutableAttributeMap getFlashMap();
101:
102: /**
103: * Returns the parent flow session in the current flow execution, or
104: * <code>null</code> if there is no parent flow session.
105: */
106: public FlowSession getParent();
107:
108: /**
109: * Returns whether this flow session is the root flow session in the ongoing
110: * flow execution. The root flow session does not have a parent flow
111: * session.
112: */
113: public boolean isRoot();
114:
115: }
|