svn commit: r583065 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/frameworkAdapter/FrameworkAdapter.java

[sk...@apache.org]

Author: skitching
Date: Tue Oct  9 00:52:23 2007
New Revision: 583065

URL: http://svn.apache.org/viewvc?rev=583065&view=rev
Log:
Add a prepare method to initialise the instance after setters have been called, and invoke the
prepare method from setCurrentInstance if it has not already been done.

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/frameworkAdapter/FrameworkAdapter.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/frameworkAdapter/FrameworkAdapter.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/frameworkAdapter/FrameworkAdapter.java?rev=583065&r1=583064&r2=583065&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/frameworkAdapter/FrameworkAdapter.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/frameworkAdapter/FrameworkAdapter.java Tue Oct  9 00:52:23 2007
@@ -22,52 +22,128 @@
  */
 package org.apache.myfaces.orchestra.frameworkAdapter;
 
-import org.apache.myfaces.orchestra.conversation.ConversationMessager;
-
 import java.io.IOException;
 
+import org.apache.myfaces.orchestra.conversation.ConversationMessager;
+
 /**
  * An interface that provides access to all the data necessary for Orchestra to work while isolating Orchestra
- * from the actual MVC system being used. This allows Orchestra to support multiple presentation
- * frameworks, such as JSF and plain JSP.
+ * from the actual UI presentation framework being used.
+ * <p>
+ * A different concrete subclass of this type is then provided for each UI framework that Orchestra supports
+ * (and additional subtypes can be defined by users if required). This allows Orchestra to support multiple
+ * presentation frameworks, such as JSF and plain JSP. Method getCurrentInstance is used by Orchestra code
+ * to locate the appropriate adapter instance when needed.
  * <p>
- * Orchestra locates a concrete implementation of this class by using the FrameworkAdapter class, which supports
- * configuration of the actual underlying object returned.
+ * The method setCurrentInstance must be called at the start of each request in order to set the
+ * appropriate adapter instance for whatever UI framework will be handing that request.
  */
 public abstract class FrameworkAdapter
 {
-	private ConversationMessager conversationMessager;
-
 	private final static ThreadLocal instance = new ThreadLocal();
 
+	private ConversationMessager conversationMessager;
+	private boolean prepared = false;
+
 	/**
 	 * Expected to be called only by a servlet filter at the start and end of each request.
+	 * <p>
+	 * The prepare method of the provided frameworkAdapter is called if it has not already
+	 * been done. This ensures that the object is valid before the request begins. An
+	 * unchecked exception may therefore be thrown if the instance is misconfigured.
 	 */
 	public static void setCurrentInstance(FrameworkAdapter frameworkAdapter)
 	{
+		if (frameworkAdapter == null)
+		{
+			instance.remove();
+			return;
+		}
+			
+		synchronized(frameworkAdapter)
+		{
+			if (!frameworkAdapter.prepared)
+			{
+				frameworkAdapter.prepare();
+			}
+		}
+
 		instance.set(frameworkAdapter);
 	}
 
+	/**
+	 * Return an object that implements the non-static methods of this abstract
+	 * class in a manner appropriate for whatever UI framework is handling the
+	 * current request.
+	 */
 	public static FrameworkAdapter getCurrentInstance()
 	{
 		return (FrameworkAdapter) instance.get();
 	}
 
-	public ConversationMessager getConversationMessager()
+	/**
+	 * Constructor.
+	 * <p>
+	 * This constructor deliberately takes no parameters, as this class may be extended
+	 * in future releases, adding new framework-specific properties if more are needed.
+	 * Changing the constructor would not be elegant, so instead this class uses 
+	 * "setter" methods to set the properties of this object, and the prepare() method
+	 * to ensure object integrity.
+	 */
+	public FrameworkAdapter()
+	{
+	}
+
+	/**
+	 * Ensure this object is valid, and perform any once-only initialisation required. 
+	 * <p>
+	 * This method must be called before any call to any method on this class
+	 * other than setters. Multiple calls to this method are safe; all except the first
+	 * one will be ignored. The setCurrentInstance method calls this method
+	 * automatically.
+	 * <p>
+	 * This method may be overridden by subclasses to perform once-only initialisation.
+	 * If this is done, call super.prepare at the end of the subclass implementation.
+	 * <p>
+	 * This method can throw unchecked exceptions if there is a problem with the
+	 * configuration of this object.
+	 */
+	public void prepare()
 	{
 		if (conversationMessager == null)
 		{
+			// Not set via an explicit call to the setter, and not set
+			// from a child class implementation of this method, so
+			// try to do it here.
 			conversationMessager = createConversationMessager();
 		}
 
-		return conversationMessager;
+		prepared = true;
 	}
 
+	/**
+	 * If this method is not overridden by a subclass, then method setConversationMessager
+	 * must be used to explicitly provide an instance.
+	 */
 	protected ConversationMessager createConversationMessager()
 	{
 		throw new IllegalStateException("conversation messager configuration missing"); // NON-NLS
 	}
 
+	/**
+	 * Return an object that can report internal application problems to the user associated
+	 * with the current request.
+	 */
+	public ConversationMessager getConversationMessager()
+	{
+		return conversationMessager;
+	}
+
+	/**
+	 * Set the object that can report internal application problems to the user associated
+	 * with a request. This method is only ever expected to be called once, during
+	 * configuration of a FrameworkAdapter instance.
+	 */
 	public void setConversationMessager(ConversationMessager conversationMessager)
 	{
 		this.conversationMessager = conversationMessager;