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