    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.beanutils;
    018
    019import java.util.Map;
    020
    021/**
    022 * <p>Provides a <em>light weight</em> <code>DynaBean</code> facade to a <code>Map</code>
    023 *  with <em>lazy</em> map/list processing.</p>
    024 *
    025 * <p>Its a <em>light weight</em> <code>DynaBean</code> implementation because there is no
    026 *    actual <code>DynaClass</code> associated with this <code>DynaBean</code> - in fact
    027 *    it implements the <code>DynaClass</code> interface itself providing <em>pseudo</em> DynaClass
    028 *    behaviour from the actual values stored in the <code>Map</code>.</p>
    029 *
    030 * <p>As well providing rhe standard <code>DynaBean</code> access to the <code>Map</code>'s properties
    031 *    this class also provides the usual <em>Lazy</em> behaviour:</p>
    032 *    <ul>
    033 *       <li>Properties don't need to be pre-defined in a <code>DynaClass</code></li>
    034 *       <li>Indexed properties (<code>Lists</code> or <code>Arrays</code>) are automatically instantiated
    035 *           and <em>grown</em> so that they are large enough to cater for the index being set.</li>
    036 *       <li>Mapped properties are automatically instantiated.</li>
    037 *    </ul>
    038 *
    039 * <p><strong><u><em>Restricted</em> DynaClass</u></strong></p>
    040 *    <p>This class implements the <code>MutableDynaClass</code> interface.
    041 *       <code>MutableDynaClass</code> have a facility to <em>restrict</em> the <code>DynaClass</code>
    042 *       so that its properties cannot be modified. If the <code>MutableDynaClass</code> is
    043 *       restricted then calling any of the <code>set()</code> methods for a property which
    044 *       doesn't exist will result in a <code>IllegalArgumentException</code> being thrown.</p>
    045 *
    046 */
    047public class LazyDynaMap extends LazyDynaBean implements MutableDynaClass {
    048
    049    private static final long serialVersionUID = 1L;
    050
    051    /**
    052     * The name of this DynaClass (analogous to the
    053     * <code>getName()</code> method of <code>java.lang.Class</code>).
    054     */
    055    protected String name;
    056
    057    /**
    058     * Controls whether changes to this DynaClass's properties are allowed.
    059     */
    060    protected boolean restricted;
    061
    062    /**
    063     * <p>Controls whether the <code>getDynaProperty()</code> method returns
    064     * null if a property doesn't exist - or creates a new one.</p>
    065     *
    066     * <p>Default is <code>false</code>.
    067     */
    068    protected boolean returnNull;
    069
    070    /**
    071     * Constructs a new instance.
    072     */
    073    public LazyDynaMap() {
    074        this(null, (Map<String, Object>)null);
    075    }
    076
    077    /**
    078     * Construct a new <code>LazyDynaMap</code> based on an exisiting DynaClass
    079     *
    080     * @param dynaClass DynaClass to copy the name and properties from
    081     */
    082    public LazyDynaMap(final DynaClass dynaClass) {
    083        this(dynaClass.getName(), dynaClass.getDynaProperties());
    084    }
    085
    086    /**
    087     * Construct a new <code>LazyDynaMap</code> with the specified properties.
    088     *
    089     * @param properties Property descriptors for the supported properties
    090     */
    091    public LazyDynaMap(final DynaProperty[] properties) {
    092        this(null, properties);
    093    }
    094
    095    /**
    096     * Construct a new <code>LazyDynaMap</code> with the specified <code>Map</code>.
    097     *
    098     * @param values The Map backing this <code>LazyDynaMap</code>
    099     */
    100    public LazyDynaMap(final Map<String, Object> values) {
    101        this(null, values);
    102    }
    103
    104    /**
    105     * Construct a new <code>LazyDynaMap</code> with the specified name.
    106     *
    107     * @param name Name of this DynaBean class
    108     */
    109    public LazyDynaMap(final String name) {
    110        this(name, (Map<String, Object>)null);
    111    }
    112
    113    /**
    114     * Construct a new <code>LazyDynaMap</code> with the specified name and properties.
    115     *
    116     * @param name Name of this DynaBean class
    117     * @param properties Property descriptors for the supported properties
    118     */
    119    public LazyDynaMap(final String name, final DynaProperty[] properties) {
    120        this(name, (Map<String, Object>)null);
    121        if (properties != null) {
    122            for (final DynaProperty propertie : properties) {
    123                add(propertie);
    124            }
    125        }
    126    }
    127
    128    /**
    129     * Construct a new <code>LazyDynaMap</code> with the specified name and  <code>Map</code>.
    130     *
    131     * @param name Name of this DynaBean class
    132     * @param values The Map backing this <code>LazyDynaMap</code>
    133     */
    134    public LazyDynaMap(final String name, final Map<String, Object> values) {
    135        this.name      = name   == null ? "LazyDynaMap" : name;
    136        this.values    = values == null ? newMap()      : values;
    137        this.dynaClass = this;
    138    }
    139
    140    /**
    141     * Add a new dynamic property.
    142     *
    143     * @param property Property the new dynamic property to add.
    144     * @throws IllegalArgumentException if name is null
    145     */
    146    protected void add(final DynaProperty property) {
    147        add(property.getName(), property.getType());
    148    }
    149
    150    /**
    151     * Add a new dynamic property with no restrictions on data type,
    152     * readability, or writeability.
    153     *
    154     * @param name Name of the new dynamic property
    155     * @throws IllegalArgumentException if name is null
    156     */
    157    @Override
    158    public void add(final String name) {
    159        add(name, null);
    160    }
    161
    162    /**
    163     * Add a new dynamic property with the specified data type, but with
    164     * no restrictions on readability or writeability.
    165     *
    166     * @param name Name of the new dynamic property
    167     * @param type Data type of the new dynamic property (null for no
    168     *  restrictions)
    169     *
    170     * @throws IllegalArgumentException if name is null
    171     * @throws IllegalStateException if this DynaClass is currently
    172     *  restricted, so no new properties can be added
    173     */
    174    @Override
    175    public void add(final String name, final Class<?> type) {
    176
    177        if (name == null) {
    178            throw new IllegalArgumentException("Property name is missing.");
    179        }
    180
    181        if (isRestricted()) {
    182            throw new IllegalStateException("DynaClass is currently restricted. No new properties can be added.");
    183        }
    184
    185        final Object value = values.get(name);
    186
    187        // Check if the property already exists
    188        if (value == null) {
    189            values.put(name, type == null ? null : createProperty(name, type));
    190        }
    191
    192    }
    193
    194    /**
    195     * <p>Add a new dynamic property with the specified data type, readability,
    196     * and writeability.</p>
    197     *
    198     * <p><strong>N.B.</strong>Support for readable/writeable properties has not been implemented
    199     *    and this method always throws a <code>UnsupportedOperationException</code>.</p>
    200     *
    201     * <p>I'm not sure the intention of the original authors for this method, but it seems to
    202     *    me that readable/writable should be attributes of the <code>DynaProperty</code> class
    203     *    (which they are not) and is the reason this method has not been implemented.</p>
    204     *
    205     * @param name Name of the new dynamic property
    206     * @param type Data type of the new dynamic property (null for no
    207     *  restrictions)
    208     * @param readable Set to <code>true</code> if this property value
    209     *  should be readable
    210     * @param writeable Set to <code>true</code> if this property value
    211     *  should be writeable
    212     *
    213     * @throws UnsupportedOperationException anytime this method is called
    214     */
    215    @Override
    216    public void add(final String name, final Class<?> type, final boolean readable, final boolean writeable) {
    217        throw new UnsupportedOperationException("readable/writable properties not supported");
    218    }
    219
    220    /**
    221     * <p>Return an array of <code>ProperyDescriptors</code> for the properties
    222     * currently defined in this DynaClass.  If no properties are defined, a
    223     * zero-length array will be returned.</p>
    224     *
    225     * <p><strong>FIXME</strong> - Should we really be implementing
    226     * <code>getBeanInfo()</code> instead, which returns property descriptors
    227     * and a bunch of other stuff?</p>
    228     * @return the set of properties for this DynaClass
    229     */
    230    @Override
    231    public DynaProperty[] getDynaProperties() {
    232
    233        int i = 0;
    234        final DynaProperty[] properties = new DynaProperty[values.size()];
    235        for (final Map.Entry<String, Object> e : values.entrySet()) {
    236            final String name = e.getKey();
    237            final Object value = values.get(name);
    238            properties[i++] = new DynaProperty(name, value == null ? null
    239                    : value.getClass());
    240        }
    241
    242        return properties;
    243
    244    }
    245
    246    /**
    247     * <p>Return a property descriptor for the specified property.</p>
    248     *
    249     * <p>If the property is not found and the <code>returnNull</code> indicator is
    250     *    <code>true</code>, this method always returns <code>null</code>.</p>
    251     *
    252     * <p>If the property is not found and the <code>returnNull</code> indicator is
    253     *    <code>false</code> a new property descriptor is created and returned (although
    254     *    its not actually added to the DynaClass's properties). This is the default
    255     *    beahviour.</p>
    256     *
    257     * <p>The reason for not returning a <code>null</code> property descriptor is that
    258     *    <code>BeanUtils</code> uses this method to check if a property exists
    259     *    before trying to set it - since these <em>Map</em> implementations automatically
    260     *    add any new properties when they are set, returning <code>null</code> from
    261     *    this method would defeat their purpose.</p>
    262     *
    263     * @param name Name of the dynamic property for which a descriptor
    264     *  is requested
    265     * @return The descriptor for the specified property
    266     * @throws IllegalArgumentException if no property name is specified
    267     */
    268    @Override
    269    public DynaProperty getDynaProperty(final String name) {
    270
    271        if (name == null) {
    272            throw new IllegalArgumentException("Property name is missing.");
    273        }
    274
    275        // If it doesn't exist and returnNull is false
    276        // create a new DynaProperty
    277        if (!values.containsKey(name) && isReturnNull()) {
    278            return null;
    279        }
    280
    281        final Object value = values.get(name);
    282
    283        if (value == null) {
    284            return new DynaProperty(name);
    285        }
    286        return new DynaProperty(name, value.getClass());
    287
    288    }
    289
    290    /**
    291     * Return the underlying Map backing this <code>DynaBean</code>
    292     * @return the underlying Map
    293     * @since 1.8.0
    294     */
    295    @Override
    296    public Map<String, Object> getMap() {
    297        return values;
    298    }
    299
    300    /**
    301     * Return the name of this DynaClass (analogous to the
    302     * <code>getName()</code> method of <code>java.lang.Class</code>)
    303     *
    304     * @return the name of the DynaClass
    305     */
    306    @Override
    307    public String getName() {
    308        return this.name;
    309    }
    310
    311    /**
    312         * <p>Indicate whether a property actually exists.</p>
    313         *
    314         * <p><strong>N.B.</strong> Using <code>getDynaProperty(name) == null</code>
    315         * doesn't work in this implementation because that method might
    316         * return a DynaProperty if it doesn't exist (depending on the
    317         * <code>returnNull</code> indicator).</p>
    318         *
    319         * @param name Name of the dynamic property
    320         * @return <code>true</code> if the property exists,
    321         * otherwise <code>false</code>
    322         * @throws IllegalArgumentException if no property name is specified
    323         */
    324        @Override
    325        protected boolean isDynaProperty(final String name) {
    326
    327            if (name == null) {
    328                throw new IllegalArgumentException("Property name is missing.");
    329            }
    330
    331            return values.containsKey(name);
    332
    333        }
    334
    335    /**
    336     * <p>Is this DynaClass currently restricted.</p>
    337     * <p>If restricted, no changes to the existing registration of
    338     *  property names, data types, readability, or writeability are allowed.</p>
    339     *
    340     * @return <code>true</code> if this Mutable {@link DynaClass} is restricted,
    341     * otherwise <code>false</code>
    342     */
    343    @Override
    344    public boolean isRestricted() {
    345        return restricted;
    346    }
    347
    348    /**
    349     * Should this DynaClass return a <code>null</code> from
    350     * the <code>getDynaProperty(name)</code> method if the property
    351     * doesn't exist.
    352     *
    353     * @return <code>true</code> if a <code>null</code> {@link DynaProperty}
    354     * should be returned if the property doesn't exist, otherwise
    355     * <code>false</code> if a new {@link DynaProperty} should be created.
    356     */
    357    public boolean isReturnNull() {
    358        return returnNull;
    359    }
    360
    361    /**
    362     * Instantiate and return a new DynaBean instance, associated
    363     * with this DynaClass.
    364     * @return A new <code>DynaBean</code> instance
    365     */
    366    @Override
    367    public DynaBean newInstance()  {
    368
    369        // Create a new instance of the Map
    370        Map<String, Object> newMap = null;
    371        try {
    372            @SuppressWarnings("unchecked")
    373            final
    374            // The new map is used as properties map
    375            Map<String, Object> temp = getMap().getClass().getConstructor().newInstance();
    376            newMap = temp;
    377        } catch(final Exception ex) {
    378            newMap = newMap();
    379        }
    380
    381        // Crate new LazyDynaMap and initialize properties
    382        final LazyDynaMap lazyMap = new LazyDynaMap(newMap);
    383        final DynaProperty[] properties = getDynaProperties();
    384        if (properties != null) {
    385            for (final DynaProperty propertie : properties) {
    386                lazyMap.add(propertie);
    387            }
    388        }
    389        return lazyMap;
    390    }
    391
    392    /**
    393     * Remove the specified dynamic property, and any associated data type,
    394     * readability, and writeability, from this dynamic class.
    395     * <strong>NOTE</strong> - This does <strong>NOT</strong> cause any
    396     * corresponding property values to be removed from DynaBean instances
    397     * associated with this DynaClass.
    398     *
    399     * @param name Name of the dynamic property to remove
    400     * @throws IllegalArgumentException if name is null
    401     * @throws IllegalStateException if this DynaClass is currently
    402     *  restricted, so no properties can be removed
    403     */
    404    @Override
    405    public void remove(final String name) {
    406
    407        if (name == null) {
    408            throw new IllegalArgumentException("Property name is missing.");
    409        }
    410
    411        if (isRestricted()) {
    412            throw new IllegalStateException("DynaClass is currently restricted. No properties can be removed.");
    413        }
    414
    415        // Remove, if property doesn't exist
    416        if (values.containsKey(name)) {
    417            values.remove(name);
    418        }
    419
    420    }
    421
    422    /**
    423     * Set the value of a simple property with the specified name.
    424     *
    425     * @param name Name of the property whose value is to be set
    426     * @param value Value to which this property is to be set
    427     */
    428    @Override
    429    public void set(final String name, final Object value) {
    430
    431        if (isRestricted() && !values.containsKey(name)) {
    432            throw new IllegalArgumentException
    433                    ("Invalid property name '" + name + "' (DynaClass is restricted)");
    434        }
    435
    436        values.put(name, value);
    437
    438    }
    439
    440    /**
    441     * Set the Map backing this <code>DynaBean</code>
    442     *
    443     * @param values The new Map of values
    444     */
    445    public void setMap(final Map<String, Object> values) {
    446        this.values = values;
    447    }
    448
    449    /**
    450     * <p>Set whether this DynaClass is currently restricted.</p>
    451     * <p>If restricted, no changes to the existing registration of
    452     *  property names, data types, readability, or writeability are allowed.</p>
    453     *
    454     * @param restricted The new restricted state
    455     */
    456    @Override
    457    public void setRestricted(final boolean restricted) {
    458        this.restricted = restricted;
    459    }
    460
    461   /**
    462 * Set whether this DynaClass should return a <code>null</code> from
    463 * the <code>getDynaProperty(name)</code> method if the property
    464 * doesn't exist.
    465 *
    466 * @param returnNull <code>true</code> if a <code>null</code> {@link DynaProperty}
    467 * should be returned if the property doesn't exist, otherwise
    468 * <code>false</code> if a new {@link DynaProperty} should be created.
    469 */
    470public void setReturnNull(final boolean returnNull) {
    471    this.returnNull = returnNull;
    472}
    473
    474}