01: /*
02: * Copyright 2004-2007 the original author or authors.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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.conversation;
17:
18: /**
19: * A service for managing conversations. This interface is the entry point into
20: * the conversation subsystem.
21: *
22: * @author Keith Donald
23: * @author Erwin Vervaet
24: */
25: public interface ConversationManager {
26:
27: /**
28: * Begin a new conversation.
29: * @param conversationParameters descriptive conversation parameters
30: * @return a service interface allowing access to the conversation context
31: * @throws ConversationException an exception occured
32: */
33: public Conversation beginConversation(
34: ConversationParameters conversationParameters)
35: throws ConversationException;
36:
37: /**
38: * Get the conversation with the provided id.
39: * <p>
40: * Implementors should take care to manage conversation identity correctly.
41: * Although it is not strictly required to return the same (==) Conversation
42: * object every time this method is called with a particular conversation
43: * id in a single execution thread, callers will expect to recieve an object
44: * that allows them to manipulate the identified conversation. In other words,
45: * the following is legal ConversationManager client code:
46: * <pre>
47: * ConversationManager manager = ...;
48: * ConversationId id = ...;
49: * Conversation conv = manager.getConversation(id);
50: * conv.lock();
51: * try {
52: * Conversation localReference = manager.getConversation(id);
53: * // no need to lock since conversation 'id' is already locked
54: * // even though possibly conv != localReference
55: * localReference.putAttribute("foo", "bar");
56: * Object foo = conv.getAttribute("foo");
57: * }
58: * finally {
59: * conv.unlock();
60: * }
61: * </pre>
62: * @param id the conversation id
63: * @return the conversation
64: * @throws NoSuchConversationException the id provided was invalid
65: */
66: public Conversation getConversation(ConversationId id)
67: throws ConversationException;
68:
69: /**
70: * Parse the string-encoded conversationId into its object form.
71: * Essentially, the reverse of {@link ConversationId#toString()}.
72: * @param encodedId the encoded id
73: * @return the parsed conversation id
74: * @throws ConversationException an exception occured parsing the id
75: */
76: public ConversationId parseConversationId(String encodedId)
77: throws ConversationException;
78: }
|