svn commit: r588213 - /myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/dynaForm/component/dynaForm/DynaForm.java

[sk...@apache.org]

Author: skitching
Date: Thu Oct 25 05:24:25 2007
New Revision: 588213

URL: http://svn.apache.org/viewvc?rev=588213&view=rev
Log:
Add documentation only.

Modified:
    myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/dynaForm/component/dynaForm/DynaForm.java

Modified: myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/dynaForm/component/dynaForm/DynaForm.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/dynaForm/component/dynaForm/DynaForm.java?rev=588213&r1=588212&r2=588213&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/dynaForm/component/dynaForm/DynaForm.java (original)
+++ myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/dynaForm/component/dynaForm/DynaForm.java Thu Oct 25 05:24:25 2007
@@ -45,8 +45,21 @@
 import java.util.Map;
 
 /**
- * the dynaForm component<br />
- * handles whats needed to dynamically create JSF component trees
+ * A DynaForm component dynamically creates child jsf component objects to render
+ * all the persistent fields of an arbitrary java object.
+ * <p>
+ * The standard "value" property must be an EL expression that returns the object
+ * whose properties are to be displayed or edited.
+ * <p>
+ * For documentation on the configurable properties of this component, see:
+ * <ul>
+ * <li>uri: {@link #setUri(String)}
+ * <li>valueBindingPrefix: {@link #setValueBindingPrefix(String)}
+ * <li>displayOnly: {@link #setDisplayOnly(String)}
+ * <li>bundle: {@link #setBundle(String)}
+ * <li>exclusiveFields: {@link #setUri(String)}
+ * <li>idAsDisplayOnly: {@link #setIdAsDisplayOnly(String)}
+ * </ul>
  */
 public class DynaForm extends UIComponentBase
 {
@@ -154,9 +167,20 @@
 	}
 
 	/**
-	 * how to reach the model<br />
-	 * e.g. ejb:fqn.to.model.Entity means use EJB3 to work with the given entity<br />
-	 * beside the model itself the uri scheme also configures what to do with this entity
+	 * Specifies how to obtain the metadata for the value object.
+	 * <p>
+	 * This is a string of form "inspector:classname". The inspector part ndicates
+	 * which of the configured Extractor implementations should be used to obtain the
+	 * metadata for this class. The classname is of course the concrete class of the
+	 * specified object.
+	 * <p>
+	 * For example, "ejb:fqn.to.model.Entity" means use the EJB3-based extractor 
+	 * implementation to obtain metadata about the given entity
+	 * <p>
+	 * TODO: why can't value.getClass() be used for the classname part of the uri?
+	 * Maybe because the value EL expression can map to a null property when creating
+	 * a new instance?
+	 * <p>
 	 *
 	 * @see org.apache.myfaces.orchestra.dynaForm.uri.UriResolver
 	 */
@@ -179,9 +203,24 @@
 	}
 
 	/**
-	 * The value binding prefix which will be used to create the real value binding.
-	 * If this is missing and the layout component has a "var" attribute its
-	 * value will be used.
+	 * Specify how to get and set the model value for each persistent property
+	 * of the value object.
+	 * <p>
+	 * When the JSF components that correspond to the individual persistent
+	 * properties of the value object are created, they need EL expressions to
+	 * tell them how to access the corresponding model value.
+	 * <p>
+	 * The EL expression used for each created component is of form
+	 * <code>#{valueBindingPrefix.propname}</code>.
+	 * <p>
+	 * Of course valueBindingPrefix will normally refer to the same object
+	 * that the "value" property refers to. In fact, there probably isn't any
+	 * other sane value for this property.
+	 * <p>
+	 * TODO: Can we get rid of this attribute? Either call
+	 * <code>getValueBinding().getExpressionString()</code> or create a special
+	 * ValueBinding subclass that takes a "base object" parameter which we can
+	 * point at the result of evaluating the main value expression.
 	 */
 	public void setValueBindingPrefix(String valueBindingPrefix)
 	{
@@ -202,7 +241,13 @@
 	}
 
 	/**
-	 * The bundle to use to convert the labels to readable strings
+	 * The bundle to use to convert property names to localised label strings.
+	 * <p>
+	 * For each persistent property on the value object, a pair of components
+	 * (label and value) are created. The label text is computed by using the
+	 * persistent property name as a key into the specified bundle.
+	 * <p>
+	 * This must be the name of a managed bean that implements Map.
 	 */
 	public void setBundle(String bundle)
 	{
@@ -223,7 +268,8 @@
 	 */
 
 	/**
-	 * Display the whole form in read only mode
+	 * Display the whole form in read only mode, ie all the JSF components
+	 * generated to display persistent properties are "read only".
 	 */
 	public void setDisplayOnly(boolean displayOnly)
 	{
@@ -253,7 +299,15 @@
 	}
 
     /**
-     * Display id fields in form in read only mode
+     * Display id fields (ie the key fields of the persistent object) in the form
+     * in read only mode.
+     * <p>
+     * Defaults to false.
+     * <p>
+     * When editing existing objects this should be set to true, as it is not possible
+     * to modify the key of an existing entity. When creating a new instance this should
+     * be set to true if the key is an auto-generated surrogate key, but false if the
+     * key to this entity is a "business key".  
      */
     public void setIdAsDisplayOnly(boolean idAsDisplayOnly)
     {
@@ -284,6 +338,8 @@
 
     /**
 	 * Process only fields listed by their facets
+	 * <p>
+	 * TODO: document this properly. What does this do exactly??
 	 */
 	public void setExclusiveFields(boolean exclusiveFields)
 	{
@@ -349,7 +405,11 @@
 	}
 
 	/**
-	 * get the overall configuration based on the given uri
+	 * Get the overall configuration based on the current value of the uri property.
+	 * <p>
+	 * This returns an object that simply pairs an Extractor object with the remaining
+	 * part of the URI. The Extractor instance selected is specified by the "protocol"
+	 * part of the URI.
 	 *
 	 * @see org.apache.myfaces.orchestra.dynaForm.uri.UriResolver
 	 */