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