diff --git a/spring-webflow/src/main/java/org/springframework/webflow/conversation/ConversationManager.java b/spring-webflow/src/main/java/org/springframework/webflow/conversation/ConversationManager.java index c3695aca..cfbe28c4 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/conversation/ConversationManager.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/conversation/ConversationManager.java @@ -20,6 +20,7 @@ package org.springframework.webflow.conversation; * the conversation subsystem. * * @author Keith Donald + * @author Erwin Vervaet */ public interface ConversationManager { @@ -33,6 +34,29 @@ public interface ConversationManager { /** * Get the conversation with the provided id. + *
+ * Implementors should take care to manage conversation identity correctly. + * Although it is not strictly required to return the same (==) Conversation + * object every time this method is called with a particular conversation + * id in a single execution thread, callers will expect to recieve an object + * that allows them to manipulate the identified conversation. In other words, + * the following is legal ConversationManager client code: + *
+ * ConversationManager manager = ...;
+ * ConversationId id = ...;
+ * Conversation conv = manager.getConversation(id);
+ * conv.lock();
+ * try {
+ * Conversation localReference = manager.getConversation(id);
+ * // no need to lock since conversation 'id' is already locked
+ * // even though possibly conv != localReference
+ * localReference.putAttribute("foo", "bar");
+ * Object foo = conv.getAttribute("foo");
+ * }
+ * finally {
+ * conv.unlock();
+ * }
+ *
* @param id the conversation id
* @return the conversation
* @throws NoSuchConversationException the id provided was invalid