KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > webflow > execution > repository > FlowExecutionRepository


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.repository;
17
18 import org.springframework.webflow.execution.FlowExecution;
19
20 /**
21  * Central subsystem interface responsible for the saving and restoring of flow
22  * executions, where each flow execution represents a state of an active flow
23  * definition.
24  * <p>
25  * Flow execution repositories are responsible for managing the storage, restoration
26  * and removal of flow executions launched by clients of the Spring Web Flow system.
27  * <p>
28  * When placed in a repository a {@link FlowExecution} object representing the
29  * state of a flow at a point in time is indexed under a unique
30  * {@link FlowExecutionKey}.
31  *
32  * @see FlowExecution
33  * @see FlowExecutionKey
34  *
35  * @author Erwin Vervaet
36  * @author Keith Donald
37  */
38 public interface FlowExecutionRepository {
39
40     /**
41      * Generate a unique flow execution key to be used as the persistent
42      * identifier of the flow execution. This method should be called after a
43      * new flow execution is started and remains active; thus needing to be
44      * saved. The FlowExecutionKey is the execution's persistent identity.
45      * @param flowExecution the flow execution
46      * @return the flow execution key
47      * @throws FlowExecutionRepositoryException a problem occured generating the
48      * key
49      */
50     public FlowExecutionKey generateKey(FlowExecution flowExecution) throws FlowExecutionRepositoryException;
51
52     /**
53      * Obtain the "next" flow execution key to be used as the flow
54      * execution's persistent identity. This method should be called after a
55      * existing flow execution has resumed and remains active; thus needing to
56      * be updated. This repository may choose to return the previous key or
57      * generate a new key.
58      * @param flowExecution the flow execution
59      * @param previousKey the <i>current</i> key associated with the flow exection
60      * @throws FlowExecutionRepositoryException a problem occured generating the
61      * key
62      */
63     public FlowExecutionKey getNextKey(FlowExecution flowExecution, FlowExecutionKey previousKey)
64             throws FlowExecutionRepositoryException;
65
66     /**
67      * Return the lock for the flow execution, allowing for the lock to be
68      * acquired or released.
69      * <p>
70      * Caution: care should be made not to allow for a deadlock situation. If
71      * you acquire a lock make sure you release it when you are done.
72      * <p>
73      * The general pattern for safely doing work against a locked conversation
74      * follows:
75      * <pre>
76      * FlowExecutionLock lock = repository.getLock(key);
77      * lock.lock();
78      * try {
79      * FlowExecution execution = repository.getFlowExecution(key);
80      * // do work
81      * }
82      * finally {
83      * lock.unlock();
84      * }
85      * </pre>
86      * @param key the identifier of the flow execution to lock
87      * @return the lock
88      * @throws FlowExecutionRepositoryException a problem occured accessing the
89      * lock object
90      */
91     public FlowExecutionLock getLock(FlowExecutionKey key) throws FlowExecutionRepositoryException;
92
93     /**
94      * Return the <code>FlowExecution</code> indexed by the provided key. The
95      * returned flow execution represents the restored state of an executing
96      * flow from a point in time. This should be called to resume a persistent
97      * flow execution.
98      * @param key the flow execution key
99      * @return the flow execution, fully hydrated and ready to signal an event
100      * against
101      * @throws FlowExecutionRepositoryException if no flow execution was indexed
102      * with the key provided
103      */
104     public FlowExecution getFlowExecution(FlowExecutionKey key) throws FlowExecutionRepositoryException;
105
106     /**
107      * Place the <code>FlowExecution</code> in this repository under the
108      * provided key. This should be called to save or update the persistent
109      * state of an active (but paused) flow execution.
110      * @param key the flow execution key
111      * @param flowExecution the flow execution
112      * @throws FlowExecutionRepositoryException the flow execution could not be
113      * stored
114      */
115     public void putFlowExecution(FlowExecutionKey key, FlowExecution flowExecution)
116             throws FlowExecutionRepositoryException;
117
118     /**
119      * Remove the flow execution from the repository. This should be called when
120      * the flow execution ends (is no longer active).
121      * @param key the flow execution key
122      * @throws FlowExecutionRepositoryException the flow execution could not be
123      * removed.
124      */
125     public void removeFlowExecution(FlowExecutionKey key) throws FlowExecutionRepositoryException;
126
127     /**
128      * Parse the string-encoded flow execution key into its object form.
129      * Essentially, the reverse of {@link FlowExecutionKey#toString()}.
130      * @param encodedKey the string encoded key
131      * @return the parsed flow execution key, the persistent identifier for
132      * exactly one flow execution
133      */
134     public FlowExecutionKey parseFlowExecutionKey(String JavaDoc encodedKey) throws FlowExecutionRepositoryException;
135
136 }
Popular Tags