niallp 2004/07/18 07:43:26
Modified: beanutils/src/java/org/apache/commons/beanutils package.html
LazyDynaMap.java LazyDynaClass.java
LazyDynaBean.java
Log:
JavaDoc changes, make LazyDynaBean Serilaizable, LazyDynaMap constructor changes
Revision Changes Path
1.19 +123 -0
jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/package.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- package.html 7 Jan 2004 22:01:09 -0000 1.18
+++ package.html 18 Jul 2004 14:43:25 -0000 1.19
@@ -30,6 +30,7 @@
<li><a href="#dynamic.resultSet">ResultSetDynaClass (Wraps ResultSet in
DynaBeans)</a></li>
<li><a href="#dynamic.rowSet">RowSetDynaClass (Disconnected ResultSet as
DynaBeans)</a></li>
<li><a href="#dynamic.wrap">WrapDynaBean and WrapDynaClass</a></li>
+ <li><a href="#dynamic.lazy"><i>Lazy</i> DynaBeans</a></li>
</ul></li>
<li><a href="#conversion">Data Type Conversions</a>
<ul>
@@ -585,6 +586,128 @@
<p>Note that, although appropriate <code>WrapDynaClass</code> instances are
created internally, you never need to deal with them.</p>
+
+<a name="dynamic.lazy"></a>
+<h3><i>Lazy</i> DynaBeans (<a href="LazyDynaBean.html">LazyDynaBean</a>,
+<a href="LazyDynaMap.html">LazyDynaMap</a> and <a
href="LazyDynaClass.html">LazyDynaClass</a>)</h3>
+
+<p>You bought into the DynaBeans because it saves coding all those POJO JavaBeans
but
+ your're here because <i>lazy</i> caught your eye and wondered whats that about?
+ What makes these flavors of DynaBean <i>lazy</i> are the following features:</p>
+ <ul>
+ <li><strong><i>Lazy</i> property addition</strong> - lazy beans use a
+ <code><a href="DynaClass.html">DynaClass</a></code> which implements
+ the <code><a href="MutableDynaClass.html">MutableDynaClass</a></code>
+ interface. This provides the ability to add and remove a DynaClass's
+ properties. <i>Lazy</i> beans use this feature to automatically add
+ a property which doesn't exist to the DynaClass when
+ the <code>set(name, value)</code> method is called.</li>
+ <li><strong><i>Lazy</i> List/Array growth</strong> - If an <i>indexed</i>
property is not large
+ enough to accomodate the <code>index</code> being set then the
<code>List</code> or
+ <code>Array</code> is automatically <i>grown</i> so that it is.</li>
+ <li><strong><i>Lazy</i> List/Array instantiation</strong> - if an
<i>indexed</i>
+ property doesn't exist then calling the <a
href="DynaBean.html">DynaBean</a>'s
+ <i>indexed</i> property getter/setter methods (i.e. <code>get(name,
index)</code> or
+ <code>set(name, index, value)</code>) results in either a new
<code>List</code>
+ or <code>Array</code> being instantiated. If the indexed property has
not been
+ defined in the DynaClass then it is automatically added and a default
<code>List</code>
+ implementation instantiated.</li>
+ <li><strong><i>Lazy</i> Map instantiation</strong> - if a <i>mapped</i>
+ property doesn't exist then calling the <a
href="DynaBean.html">DynaBean</a>'s
+ <i>mapped</i> property getter/setter methods (i.e. <code>get(name,
key)</code> or
+ <code>set(name, key, value)</code>) results in a new <code>Map</code>
+ being instantiated. If the mapped property has not been defined in the
DynaClass
+ then it is automatically added and a default <code>Map</code>
implementation
+ instantiated.</li>
+ <li><strong><i>Lazy</i> Bean instantiation</strong> - if a property is
defined in
+ the <code>DynaClass</code> as a <code>DynaBean</code> or regular bean
and
+ doesn't exist in the <code>DynaBean</code> then
<code>LazyDynaBean</code> wiill
+ try to instantiate the bean using a default empty constructor.</li>
+ </ul>
+
+<p><strong><a href="LazyDynaBean.html">LazyDynaBean</a></strong> is the standard
<i>lazy</i> bean
+ implementation. By default it is associated with a <a
href="LazyDynaClass.html">LazyDynaClass</a>
+ which implements the <a href="MutableDynaClass.html">MutableDynaClass</a>
interface - however
+ it can be used with any <code>MutableDynaClass</code> implementation. The
question is <i>how do
+ I use it?</i> - well it can be as simple as creating a new bean and then calling
the getters/setters...</p>
+
+<pre>
+ DynaBean dynaBean = new LazyDynaBean();
+
+ dynaBean.set("foo", "bar"); // simple
+
+ dynaBean.set("customer", "title", "Mr"); // mapped
+ dynaBean.set("customer", "surname", "Smith"); // mapped
+
+ dynaBean.set("address", 0, addressLine1); // indexed
+ dynaBean.set("address", 1, addressLine2); // indexed
+ dynaBean.set("address", 2, addressLine3); // indexed
+</pre>
+
+<p><strong><a href="LazyDynaMap.html">LazyDynaMap</a></strong> is a <i>light
wieght</i> <code>DynaBean</code>
+ facade to a <code>Map</code> with all the usual <i>lazy</i> features. Its
<i>light weight</i> because it doesn't
+ have an associated <code>DynaClass</code> containing all the properties. In fact
it actually implements
+ the <code>DynaClass</code> interface itself (and <code>MutableDynaClass</code>)
and derives all the <i>DynaClass</i>
+ information from the actual contents of the <code>Map</code>. A
<code>LazyDynaMap</code> can be created around an
+ existing <code>Map</code> or can instantiate its own <code>Map</code>. After any
<code>DynaBean</code>
+ processing has finished the <code>Map</code> can be retrieved and the DynaBean
<i>facade</i> discarded.</p>
+
+<p>If you need a new <code>Map</code> then to use....</p>
+
+<pre>
+ DynaBean dynaBean = new LazyDynaMap(); // create DynaBean
+
+ dynaBean.set("foo", "bar"); // simple
+ dynaBean.set("customer", "title", "Mr"); // mapped
+ dynaBean.set("address", 0, addressLine1); // indexed
+
+ Map myMap = dynaBean.getMap() // retrieve the Map
+</pre>
+<p><i>or</i> to use with an existing <code>Map</code> ....</p>
+
+<pre>
+ Map myMap = .... // exisitng Map
+ DynaBean dynaBean = new LazyDynaMap(myMap); // wrap Map in DynaBean
+ dynaBean.set("foo", "bar"); // set properties
+</pre>
+
+<p><strong><a href="LazyDynaClass.html">LazyDynaClass</a></strong> extends <a
href="BasicDynaClass.html">BasicDynaClass</a>
+ and implements the <a href="MutableDynaClass.html">MutableDynaClass</a>
interface. It can be used with other
+ <code>DynaBean</code> implementations, but it is the default
<code>DynaClass</code> used by <code>LazyDynaBean</code>.
+ When using the <code>LazyDynaBean</code> there may be no need to have anything
to do with the <code>DynaClass</code>
+ However sometimes there is a requirement to set up the <code>DynaClass</code>
first - perhaps to
+ define the type of array for an indexed property, or if using the DynaBean in
<i>restricted</i> mode (see note below)
+ is required. Doing so is straight forward...</p>
+
+<p><i>Either</i> create a <code>LazyDynaClass</code> first...
+
+<pre>
+ MutableDynaClass dynaClass = new LazyDynaClass(); // create DynaClass
+
+ dynaClass.add("amount", java.lang.Integer.class); // add property
+ dynaClass.add("orders", OrderBean[].class); // add indexed property
+ dynaClass.add("orders", java.util.TreeMapp.class); // add mapped property
+
+ DynaBean dynaBean = new LazyDynaBean(dynaClass); // Create DynaBean with
associated DynaClass
+</pre>
+
+<p><i>or</i> create a <code>LazyDynaBean</code> and get the
<code>DynaClass</code>...
+
+<pre>
+ DynaBean dynaBean = new LazyDynaBean(); // Create LazyDynaBean
+ MutableDynaClass dynaClass =
+ (MutableDynaClass)dynaBean.getDynaClass(); // get DynaClass
+
+ dynaClass.add("amount", java.lang.Integer.class); // add property
+ dynaClass.add("myBeans", myPackage.MyBean[].class); // add 'array' indexed
property
+ dynaClass.add("myMap", java.util.TreeMapp.class); // add mapped property
+</pre>
+
+<p><strong>NOTE:</strong> One feature of <a
href="MutableDynaClass.html">MutableDynaClass</a> is that it
+ has a <i>Restricted</i> property. When the DynaClass is <i>restricted</i> no
properties can be added
+ or removed from the <code>DynaClass</code>. Neither the
<code>LazyDynaBean</code> or <code>LazyDynaMap</code>
+ will add properties automatically if the <code>DynaClass</code> is
<i>restricted</i>.</p>
+
<a name="conversion"></a>
<h1>Data Type Conversions</h1>
1.2 +28 -86
jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/LazyDynaMap.java
Index: LazyDynaMap.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/LazyDynaMap.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LazyDynaMap.java 16 Jul 2004 12:31:43 -0000 1.1
+++ LazyDynaMap.java 18 Jul 2004 14:43:25 -0000 1.2
@@ -44,7 +44,7 @@
*
* @author Niall Pemberton
*/
-public class LazyDynaMap extends LazyDynaBean implements MutableDynaClass {
+public class LazyDynaMap extends LazyDynaBean implements MutableDynaClass {
/**
* The name of this DynaClass (analogous to the
@@ -72,7 +72,7 @@
* Default Constructor.
*/
public LazyDynaMap() {
- this(null, null, null);
+ this(null, (Map)null);
}
/**
@@ -81,7 +81,7 @@
* @param name Name of this DynaBean class
*/
public LazyDynaMap(String name) {
- this(name, null, null);
+ this(name, (Map)null);
}
/**
@@ -90,17 +90,7 @@
* @param values The Map backing this <code>LazyDynaMap</code>
*/
public LazyDynaMap(Map values) {
- this(null, values, null);
- }
-
- /**
- * Construct a new <code>LazyDynaMap</code> with the specified properties.
- *
- * @param name Name of this DynaBean class
- * @param properties Property descriptors for the supported properties
- */
- public LazyDynaMap(DynaProperty[] properties) {
- this(null, null, properties);
+ this(null, values);
}
/**
@@ -110,39 +100,18 @@
* @param values The Map backing this <code>LazyDynaMap</code>
*/
public LazyDynaMap(String name, Map values) {
- this(name, values, null);
- }
-
- /**
- * Construct a new <code>LazyDynaMap</code> with the specified name and
properties.
- *
- * @param name Name of this DynaBean class
- * @param properties Property descriptors for the supported properties
- */
- public LazyDynaMap(String name, DynaProperty[] properties) {
- this(name, null, properties);
- }
-
- /**
- * Construct a new <code>LazyDynaMap</code> with the name, class and properties.
- *
- * @param name Name of this DynaBean class
- * @param valuesClass The implementation class for the <code>Map</code>
- * @param properties Property descriptors for the supported properties
- */
- public LazyDynaMap(Map values, DynaProperty properties[]) {
- this(null, values, properties);
+ this.name = name == null ? "LazyDynaMap" : name;
+ this.values = values == null ? newMap() : values;
+ this.dynaClass = this;
}
/**
- * Construct a new <code>LazyDynaMap</code> with the name, class and properties.
+ * Construct a new <code>LazyDynaMap</code> with the specified properties.
*
- * @param name Name of this DynaBean class
- * @param valuesClass The implementation class for the <code>Map</code>
* @param properties Property descriptors for the supported properties
*/
- public LazyDynaMap(String name, Map values, DynaProperty properties[]) {
- initialize(name, values, properties);
+ public LazyDynaMap(DynaProperty[] properties) {
+ this(null, properties);
}
/**
@@ -151,22 +120,22 @@
* @param name Name of this DynaBean class
* @param properties Property descriptors for the supported properties
*/
- public LazyDynaMap(DynaClass dynaClass) {
- this(dynaClass, null);
+ public LazyDynaMap(String name, DynaProperty[] properties) {
+ this(name, (Map)null);
+ if (properties != null) {
+ for (int i = 0; i < properties.length; i++) {
+ add(properties[i]);
+ }
+ }
}
/**
- * Construct a new <code>LazyDynaMap</code> with the specified name and
properties.
+ * Construct a new <code>LazyDynaMap</code> based on an exisiting DynaClass
*
- * @param name Name of this DynaBean class
- * @param properties Property descriptors for the supported properties
+ * @param dynaClass DynaClass to copy the name and properties from
*/
- public LazyDynaMap(DynaClass dynaClass, Map values) {
- if (dynaClass == null) {
- initialize(null, values, null);
- } else {
- initialize(dynaClass.getName(), values, dynaClass.getDynaProperties());
- }
+ public LazyDynaMap(DynaClass dynaClass) {
+ this(dynaClass.getName(), dynaClass.getDynaProperties());
}
// ------------------- Public Methods ----------------------------------
@@ -278,12 +247,6 @@
/**
* Instantiate and return a new DynaBean instance, associated
* with this DynaClass.
- *
- * @exception IllegalAccessException if the Class or the appropriate
- * constructor is not accessible
- * @exception InstantiationException if this Class represents an abstract
- * class, an array class, a primitive type, or void; or if instantiation
- * fails for some other reason
*/
public DynaBean newInstance() {
return new LazyDynaMap(this);
@@ -293,18 +256,18 @@
// ------------------- MutableDynaClass Methods
----------------------------------
/**
- * Is this DynaClass currently restricted, if so, no changes to the
- * existing registration of property names, data types, readability, or
- * writeability are allowed.
+ * <p>Is this DynaClass currently restricted.</p>
+ * <p>If restricted, no changes to the existing registration of
+ * property names, data types, readability, or writeability are allowed.</p>
*/
public boolean isRestricted() {
return restricted;
}
/**
- * Set whether this DynaClass is currently restricted. if so, no changes to the
- * existing registration of property names, data types, readability, or
- * writeability are allowed.
+ * <p>Set whether this DynaClass is currently restricted.</p>
+ * <p>If restricted, no changes to the existing registration of
+ * property names, data types, readability, or writeability are allowed.</p>
*/
public void setRestricted(boolean restricted) {
this.restricted = restricted;
@@ -380,8 +343,7 @@
/**
* Add a new dynamic property.
*
- * @param name Name of the new dynamic property
- * @param type Property the new dynamic property
+ * @param property Property the new dynamic property to add.
*
* @exception IllegalArgumentException if name is null
*/
@@ -442,26 +404,6 @@
// ------------------- Protected Methods ----------------------------------
-
- /**
- * Initialize the the new <code>LazyDynaMap</code> with the name, Map and
properties.
- *
- * @param name Name of this DynaBean class
- * @param valuesClass The implementation class for the <code>Map</code>
- * @param properties Property descriptors for the supported properties
- */
- protected void initialize(String name, Map values, DynaProperty properties[]) {
-
- this.dynaClass = this;
- this.name = name == null ? "LazyDynaMap" : name;
- this.values = values == null ? newMap() : values;
-
- if (properties != null) {
- for (int i = 0; i < properties.length; i++) {
- add(properties[i]);
- }
- }
- }
/**
* <p>Indicate whether a property actually exists.</p>
1.3 +11 -14
jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/LazyDynaClass.java
Index: LazyDynaClass.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/LazyDynaClass.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- LazyDynaClass.java 16 Jul 2004 12:31:43 -0000 1.2
+++ LazyDynaClass.java 18 Jul 2004 14:43:25 -0000 1.3
@@ -64,17 +64,16 @@
}
/**
- * Construct a new LazyDynaClass with the specified parameters.
+ * Construct a new LazyDynaClass with the specified name.
*
* @param name Name of this DynaBean class
- * @param dynaBeanClass The implementation class for new instances
*/
public LazyDynaClass(String name) {
this(name, (DynaProperty[])null);
}
/**
- * Construct a new LazyDynaClass with the specified parameters.
+ * Construct a new LazyDynaClass with the specified name and DynaBean class.
*
* @param name Name of this DynaBean class
* @param dynaBeanClass The implementation class for new instances
@@ -84,10 +83,9 @@
}
/**
- * Construct a new LazyDynaClass with the specified parameters.
+ * Construct a new LazyDynaClass with the specified name and properties.
*
* @param name Name of this DynaBean class
- * @param dynaBeanClass The implementation class for new intances
* @param properties Property descriptors for the supported properties
*/
public LazyDynaClass(String name, DynaProperty[] properties) {
@@ -95,7 +93,7 @@
}
/**
- * Construct a new LazyDynaClass with the specified parameters.
+ * Construct a new LazyDynaClass with the specified name, DynaBean class and
properties.
*
* @param name Name of this DynaBean class
* @param dynaBeanClass The implementation class for new intances
@@ -106,18 +104,18 @@
}
/**
- * Is this DynaClass currently restricted, if so, no changes to the
- * existing registration of property names, data types, readability, or
- * writeability are allowed.
+ * <p>Is this DynaClass currently restricted.</p>
+ * <p>If restricted, no changes to the existing registration of
+ * property names, data types, readability, or writeability are allowed.</p>
*/
public boolean isRestricted() {
return restricted;
}
/**
- * Set whether this DynaClass is currently restricted. if so, no changes to the
- * existing registration of property names, data types, readability, or
- * writeability are allowed.
+ * <p>Set whether this DynaClass is currently restricted.</p>
+ * <p>If restricted, no changes to the existing registration of
+ * property names, data types, readability, or writeability are allowed.</p>
*/
public void setRestricted(boolean restricted) {
this.restricted = restricted;
@@ -199,8 +197,7 @@
/**
* Add a new dynamic property.
*
- * @param name Name of the new dynamic property
- * @param type Property the new dynamic property
+ * @param property Property the new dynamic property to add.
*
* @exception IllegalArgumentException if name is null
* @exception IllegalStateException if this DynaClass is currently
1.3 +5 -4
jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/LazyDynaBean.java
Index: LazyDynaBean.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/LazyDynaBean.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- LazyDynaBean.java 16 Jul 2004 12:31:43 -0000 1.2
+++ LazyDynaBean.java 18 Jul 2004 14:43:25 -0000 1.3
@@ -23,6 +23,7 @@
import java.lang.reflect.Array;
import java.math.BigDecimal;
import java.math.BigInteger;
+import java.io.Serializable;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
@@ -105,7 +106,7 @@
* @see LazyDynaClass
* @author Niall Pemberton
*/
-public class LazyDynaBean implements DynaBean {
+public class LazyDynaBean implements DynaBean, Serializable {
/**
@@ -186,7 +187,7 @@
/**
* <p>Return the size of an indexed or mapped property.</p>
*
- * @param size Size of the Map, List or Array.
+ * @param name Name of the property
* @exception IllegalArgumentException if no property name is specified
*/
public int size(String name) {
@@ -355,7 +356,7 @@
// Check that the property is mapped
if (!dynaClass.getDynaProperty(name).isMapped()) {
throw new IllegalArgumentException
- ("Non-mapped property for '" + name + "(" + key + ")'"
+ ("Non-mapped property for '" + name + "(" + key + ")' "
+ dynaClass.getDynaProperty(name).getType().getName());
}
@@ -826,7 +827,7 @@
}
/**
- * <p>Creates a new instance of the <code>Map</code></p>
+ * <p>Creates a new instance of the <code>Map</code>.</p>
*/
protected Map newMap() {
return new HashMap();
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
