KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > webflow > execution > FlowSession


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.springframework.webflow.execution;
17
18 import org.springframework.webflow.core.collection.MutableAttributeMap;
19 import org.springframework.webflow.definition.FlowDefinition;
20 import org.springframework.webflow.definition.StateDefinition;
21
22 /**
23  * A single, local instantiation of a {@link FlowDefinition flow definition}
24  * launched within an overall flow execution.
25  * <p>
26  * This object maintains all instance state including session status within
27  * exactly one governing FlowExecution, as well as the current flow state. This
28  * object also acts as the local "flow scope" data model. Data in
29  * {@link #getScope() flow scope} lives for the life of this object and is
30  * cleaned up automatically when this object is destroyed. Destruction happens
31  * when this session enters an end state.
32  * <p>
33  * A flow session will go through several status changes during its lifecycle.
34  * Initially it will be {@link FlowSessionStatus#CREATED} when a new execution
35  * is started.
36  * <p>
37  * After passing through the {@link FlowSessionStatus#STARTING} status, the flow
38  * session is activated (about to be manipulated) and its status becomes
39  * {@link FlowSessionStatus#ACTIVE}. In the case of a new execution session
40  * activation happens immediately after creation to put the "root flow" at the
41  * top of the stack and transition it to its start state.
42  * <p>
43  * When control returns to the client for user think time the status is updated
44  * to {@link FlowSessionStatus#PAUSED}. The flow is no longer actively
45  * processing then, as it is stored off to a repository waiting on the user to
46  * resume.
47  * <p>
48  * If a flow session is pushed down in the stack because a subflow is spawned,
49  * its status becomes {@link FlowSessionStatus#SUSPENDED} until the subflow
50  * returns (ends) and is popped off the stack. The resuming flow session then
51  * becomes active once again.
52  * <p>
53  * When a flow session is terminated because an EndState is reached its status
54  * becomes {@link FlowSessionStatus#ENDED}, which ends its life. When this
55  * happens the session is popped off the stack and discarded, and any allocated
56  * resources in "flow scope" are automatically cleaned up.
57  * <p>
58  * Note that a flow <i>session</i> is in no way linked to an HTTP session. It
59  * just uses the familiar "session" naming convention to denote a stateful
60  * object.
61  *
62  * @see FlowDefinition
63  * @see FlowExecution
64  * @see FlowSessionStatus
65  *
66  * @author Keith Donald
67  * @author Erwin Vervaet
68  */
69 public interface FlowSession {
70
71     /**
72      * Returns the flow definition backing this session.
73      */
74     public FlowDefinition getDefinition();
75
76     /**
77      * Returns the current state of this flow session. This value changes as the
78      * flow executes.
79      */
80     public StateDefinition getState();
81
82     /**
83      * Returns the current status of this flow session. This value changes as
84      * the flow executes.
85      */
86     public FlowSessionStatus getStatus();
87
88     /**
89      * Return this session's local attributes; the basis for "flow scope" (flow
90      * session scope).
91      * @return the flow scope attributes
92      */
93     public MutableAttributeMap getScope();
94
95     /**
96      * Returns the local "flash map". Attributes in this map are cleared out
97      * on the next event signaled in the flow execution, so they survive a refresh.
98      * @return the flash map
99      */
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 }
Popular Tags