commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject cvs commit: jakarta-commons/beanutils/src/java/org/apache/commons/beanutils package.html LazyDynaMap.java LazyDynaClass.java LazyDynaBean.java
Date Sun, 18 Jul 2004 14:43:26 GMT
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message