    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
    019/**
    020 * <p>DynaClass which implements the <code>MutableDynaClass</code> interface.</p>
    021 *
    022 * <p>A <code>MutableDynaClass</code> is a specialized extension to <code>DynaClass</code>
    023 *    that allows properties to be added or removed dynamically.</p>
    024 *
    025 * <p>This implementation has one slightly unusual default behaviour - calling
    026 *    the <code>getDynaProperty(name)</code> method for a property which doesn't
    027 *    exist returns a <code>DynaProperty</code> rather than <code>null</code>. The
    028 *    reason for this is that <code>BeanUtils</code> calls this method to check if
    029 *    a property exists before trying to set the value. This would defeat the object
    030 *    of the <code>LazyDynaBean</code> which automatically adds missing properties
    031 *    when any of its <code>set()</code> methods are called. For this reason the
    032 *    <code>isDynaProperty(name)</code> method has been added to this implementation
    033 *    in order to determine if a property actually exists. If the more <em>normal</em>
    034 *    behaviour of returning <code>null</code> is required, then this can be achieved
    035 *    by calling the <code>setReturnNull(true)</code>.</p>
    036 *
    037 * <p>The <code>add(name, type, readable, writable)</code> method is not implemented
    038 *    and always throws an <code>UnsupportedOperationException</code>. I believe
    039 *    this attributes need to be added to the <code>DynaProperty</code> class
    040 *    in order to control read/write facilities.</p>
    041 *
    042 * @see LazyDynaBean
    043 */
    044public class LazyDynaClass extends BasicDynaClass implements MutableDynaClass  {
    045
    046    private static final long serialVersionUID = 1L;
    047
    048    /**
    049     * Controls whether changes to this DynaClass's properties are allowed.
    050     */
    051    protected boolean restricted;
    052
    053    /**
    054     * <p>Controls whether the <code>getDynaProperty()</code> method returns
    055     * null if a property doesn't exist - or creates a new one.</p>
    056     *
    057     * <p>Default is <code>false</code>.
    058     */
    059    protected boolean returnNull;
    060
    061    /**
    062     * Construct a new LazyDynaClass with default parameters.
    063     */
    064    public LazyDynaClass() {
    065        this(null, (DynaProperty[])null);
    066    }
    067
    068    /**
    069     * Construct a new LazyDynaClass with the specified name.
    070     *
    071     * @param name Name of this DynaBean class
    072     */
    073    public LazyDynaClass(final String name) {
    074        this(name, (DynaProperty[])null);
    075    }
    076
    077    /**
    078     * Construct a new LazyDynaClass with the specified name and DynaBean class.
    079     *
    080     * @param name Name of this DynaBean class
    081     * @param dynaBeanClass The implementation class for new instances
    082     */
    083    public LazyDynaClass(final String name, final Class<?> dynaBeanClass) {
    084        this(name, dynaBeanClass, null);
    085    }
    086
    087    /**
    088     * Construct a new LazyDynaClass with the specified name, DynaBean class and properties.
    089     *
    090     * @param name Name of this DynaBean class
    091     * @param dynaBeanClass The implementation class for new instances
    092     * @param properties Property descriptors for the supported properties
    093     */
    094    public LazyDynaClass(final String name, final Class<?> dynaBeanClass, final DynaProperty properties[]) {
    095        super(name, dynaBeanClass, properties);
    096    }
    097
    098    /**
    099     * Construct a new LazyDynaClass with the specified name and properties.
    100     *
    101     * @param name Name of this DynaBean class
    102     * @param properties Property descriptors for the supported properties
    103     */
    104    public LazyDynaClass(final String name, final DynaProperty[] properties) {
    105        this(name, LazyDynaBean.class, properties);
    106    }
    107
    108    /**
    109     * Add a new dynamic property.
    110     *
    111     * @param property Property the new dynamic property to add.
    112     * @throws IllegalArgumentException if name is null
    113     * @throws IllegalStateException if this DynaClass is currently
    114     *  restricted, so no new properties can be added
    115     */
    116    protected void add(final DynaProperty property) {
    117
    118        if (property.getName() == null) {
    119            throw new IllegalArgumentException("Property name is missing.");
    120        }
    121
    122        if (isRestricted()) {
    123            throw new IllegalStateException("DynaClass is currently restricted. No new properties can be added.");
    124        }
    125
    126        // Check if property already exists
    127        if (propertiesMap.get(property.getName()) != null) {
    128           return;
    129        }
    130
    131        // Create a new property array with the specified property
    132        final DynaProperty[] oldProperties = getDynaProperties();
    133        final DynaProperty[] newProperties = new DynaProperty[oldProperties.length+1];
    134        System.arraycopy(oldProperties, 0, newProperties, 0, oldProperties.length);
    135        newProperties[oldProperties.length] = property;
    136
    137       // Update the properties
    138       setProperties(newProperties);
    139
    140    }
    141
    142    /**
    143     * Add a new dynamic property with no restrictions on data type,
    144     * readability, or writeability.
    145     *
    146     * @param name Name of the new dynamic property
    147     * @throws IllegalArgumentException if name is null
    148     * @throws IllegalStateException if this DynaClass is currently
    149     *  restricted, so no new properties can be added
    150     */
    151    @Override
    152    public void add(final String name) {
    153        add(new DynaProperty(name));
    154    }
    155
    156    /**
    157     * Add a new dynamic property with the specified data type, but with
    158     * no restrictions on readability or writeability.
    159     *
    160     * @param name Name of the new dynamic property
    161     * @param type Data type of the new dynamic property (null for no
    162     *  restrictions)
    163     *
    164     * @throws IllegalArgumentException if name is null
    165     * @throws IllegalStateException if this DynaClass is currently
    166     *  restricted, so no new properties can be added
    167     */
    168    @Override
    169    public void add(final String name, final Class<?> type) {
    170        if (type == null) {
    171            add(name);
    172        } else {
    173            add(new DynaProperty(name, type));
    174        }
    175    }
    176
    177    /**
    178     * <p>Add a new dynamic property with the specified data type, readability,
    179     * and writeability.</p>
    180     *
    181     * <p><strong>N.B.</strong>Support for readable/writeable properties has not been implemented
    182     *    and this method always throws a <code>UnsupportedOperationException</code>.</p>
    183     *
    184     * <p>I'm not sure the intention of the original authors for this method, but it seems to
    185     *    me that readable/writable should be attributes of the <code>DynaProperty</code> class
    186     *    (which they are not) and is the reason this method has not been implemented.</p>
    187     *
    188     * @param name Name of the new dynamic property
    189     * @param type Data type of the new dynamic property (null for no
    190     *  restrictions)
    191     * @param readable Set to <code>true</code> if this property value
    192     *  should be readable
    193     * @param writeable Set to <code>true</code> if this property value
    194     *  should be writeable
    195     *
    196     * @throws UnsupportedOperationException anytime this method is called
    197     */
    198    @Override
    199    public void add(final String name, final Class<?> type, final boolean readable, final boolean writeable) {
    200        throw new UnsupportedOperationException("readable/writable properties not supported");
    201    }
    202
    203    /**
    204     * <p>Return a property descriptor for the specified property.</p>
    205     *
    206     * <p>If the property is not found and the <code>returnNull</code> indicator is
    207     *    <code>true</code>, this method always returns <code>null</code>.</p>
    208     *
    209     * <p>If the property is not found and the <code>returnNull</code> indicator is
    210     *    <code>false</code> a new property descriptor is created and returned (although
    211     *    its not actually added to the DynaClass's properties). This is the default
    212     *    beahviour.</p>
    213     *
    214     * <p>The reason for not returning a <code>null</code> property descriptor is that
    215     *    <code>BeanUtils</code> uses this method to check if a property exists
    216     *    before trying to set it - since these <em>Lazy</em> implementations automatically
    217     *    add any new properties when they are set, returning <code>null</code> from
    218     *    this method would defeat their purpose.</p>
    219     *
    220     * @param name Name of the dynamic property for which a descriptor
    221     *  is requested
    222     * @return The dyna property for the specified name
    223     * @throws IllegalArgumentException if no property name is specified
    224     */
    225    @Override
    226    public DynaProperty getDynaProperty(final String name) {
    227
    228        if (name == null) {
    229            throw new IllegalArgumentException("Property name is missing.");
    230        }
    231
    232        DynaProperty dynaProperty = propertiesMap.get(name);
    233
    234        // If it doesn't exist and returnNull is false
    235        // create a new DynaProperty
    236        if (dynaProperty == null && !isReturnNull() && !isRestricted()) {
    237            dynaProperty = new DynaProperty(name);
    238        }
    239
    240        return dynaProperty;
    241
    242    }
    243
    244    /**
    245     * <p>Indicate whether a property actually exists.</p>
    246     *
    247     * <p><strong>N.B.</strong> Using <code>getDynaProperty(name) == null</code>
    248     * doesn't work in this implementation because that method might
    249     * return a DynaProperty if it doesn't exist (depending on the
    250     * <code>returnNull</code> indicator).</p>
    251     *
    252     * @param name The name of the property to check
    253     * @return <code>true</code> if there is a property of the
    254     * specified name, otherwise <code>false</code>
    255     * @throws IllegalArgumentException if no property name is specified
    256     */
    257    public boolean isDynaProperty(final String name) {
    258
    259        if (name == null) {
    260            throw new IllegalArgumentException("Property name is missing.");
    261        }
    262
    263        return propertiesMap.get(name) ==  null ? false : true;
    264
    265    }
    266
    267    /**
    268     * <p>Is this DynaClass currently restricted.</p>
    269     * <p>If restricted, no changes to the existing registration of
    270     *  property names, data types, readability, or writeability are allowed.</p>
    271     * @return <code>true</code> if this {@link MutableDynaClass} cannot be changed
    272     * otherwise <code>false</code>
    273     */
    274    @Override
    275    public boolean isRestricted() {
    276        return restricted;
    277    }
    278
    279    /**
    280     * Should this DynaClass return a <code>null</code> from
    281     * the <code>getDynaProperty(name)</code> method if the property
    282     * doesn't exist.
    283     *
    284     * @return <code>true</code> if a <code>null</code> {@link DynaProperty}
    285     * should be returned if the property doesn't exist, otherwise
    286     * <code>false</code> if a new {@link DynaProperty} should be created.
    287     */
    288    public boolean isReturnNull() {
    289        return returnNull;
    290    }
    291
    292    /**
    293     * Remove the specified dynamic property, and any associated data type,
    294     * readability, and writeability, from this dynamic class.
    295     * <strong>NOTE</strong> - This does <strong>NOT</strong> cause any
    296     * corresponding property values to be removed from DynaBean instances
    297     * associated with this DynaClass.
    298     *
    299     * @param name Name of the dynamic property to remove
    300     * @throws IllegalArgumentException if name is null
    301     * @throws IllegalStateException if this DynaClass is currently
    302     *  restricted, so no properties can be removed
    303     */
    304    @Override
    305    public void remove(final String name) {
    306
    307        if (name == null) {
    308            throw new IllegalArgumentException("Property name is missing.");
    309        }
    310
    311        if (isRestricted()) {
    312            throw new IllegalStateException("DynaClass is currently restricted. No properties can be removed.");
    313        }
    314
    315        // Ignore if property doesn't exist
    316        if (propertiesMap.get(name) == null) {
    317            return;
    318        }
    319
    320        // Create a new property array of without the specified property
    321        final DynaProperty[] oldProperties = getDynaProperties();
    322        final DynaProperty[] newProperties = new DynaProperty[oldProperties.length-1];
    323        int j = 0;
    324        for (final DynaProperty oldProperty : oldProperties) {
    325            if (!name.equals(oldProperty.getName())) {
    326                newProperties[j] = oldProperty;
    327                j++;
    328            }
    329        }
    330
    331        // Update the properties
    332        setProperties(newProperties);
    333
    334    }
    335
    336    /**
    337     * <p>Set whether this DynaClass is currently restricted.</p>
    338     * <p>If restricted, no changes to the existing registration of
    339     *  property names, data types, readability, or writeability are allowed.</p>
    340     * @param restricted <code>true</code> if this {@link MutableDynaClass} cannot
    341     * be changed otherwise <code>false</code>
    342     */
    343    @Override
    344    public void setRestricted(final boolean restricted) {
    345        this.restricted = restricted;
    346    }
    347
    348    /**
    349     * Set whether this DynaClass should return a <code>null</code> from
    350     * the <code>getDynaProperty(name)</code> method if the property
    351     * doesn't exist.
    352     * @param returnNull <code>true</code> if a <code>null</code> {@link DynaProperty}
    353     * should be returned if the property doesn't exist, otherwise
    354     * <code>false</code> if a new {@link DynaProperty} should be created.
    355     */
    356    public void setReturnNull(final boolean returnNull) {
    357        this.returnNull = returnNull;
    358    }
    359
    360}