From fbd715da69d62605cb4d35e72f79cf6a441549fa Mon Sep 17 00:00:00 2001
From: Erwin Vervaet <erwin.vervaet@ervacon.com>
Date: Thu, 29 Mar 2007 11:29:45 +0000
Subject: [PATCH] Improved JavaDoc to clarify the API contract of the
 ConversationManager.

---
 .../conversation/ConversationManager.java     | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

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.
+	 * <p>
+	 * 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:
+	 * <pre>
+	 * 	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();
+	 * 	}
+	 * </pre>
 	 * @param id the conversation id
 	 * @return the conversation
 	 * @throws NoSuchConversationException the id provided was invalid