lazydynamap.java

这是一个有关common beanutils 的源码

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.beanutils;

import java.util.Map;
import java.util.Iterator;

/**
 * <p>Provides a <i>light weight</i> <code>DynaBean</code> facade to a <code>Map</code>
 *  with <i>lazy</i> map/list processing.</p>
 *
 * <p>Its a <i>light weight</i> <code>DynaBean</code> implementation because there is no
 *    actual <code>DynaClass</code> associated with this <code>DynaBean</code> - in fact
 *    it implements the <code>DynaClass</code> interface itself providing <i>pseudo</i> DynaClass
 *    behaviour from the actual values stored in the <code>Map</code>.</p>
 *
 * <p>As well providing rhe standard <code>DynaBean</code> access to the <code>Map</code>'s properties
 *    this class also provides the usual <i>Lazy</i> behaviour:</p>
 *    <ul>
 *       <li>Properties don't need to be pre-defined in a <code>DynaClass</code></li>
 *       <li>Indexed properties (<code>Lists</code> or <code>Arrays</code>) are automatically instantiated
 *           and <i>grown</i> so that they are large enough to cater for the index being set.</li>
 *       <li>Mapped properties are automatically instantiated.</li>
 *    </ul>
 *
 * <p><b><u><i>Restricted</i> DynaClass</u></b></p>
 *    <p>This class implements the <code>MutableDynaClass</code> interface.
 *       <code>MutableDynaClass</code> have a facility to <i>restrict</i> the <code>DynaClass</code>
 *       so that its properties cannot be modified. If the <code>MutableDynaClass</code> is
 *       restricted then calling any of the <code>set()</code> methods for a property which
 *       doesn't exist will result in a <code>IllegalArgumentException</code> being thrown.</p>
 *
 * @author Niall Pemberton
 */
public class LazyDynaMap extends LazyDynaBean implements MutableDynaClass {

    /**
     * The name of this DynaClass (analogous to the
     * <code>getName()</code> method of <code>java.lang.Class</code>).
     */
    protected String name;

    /**
     * Controls whether changes to this DynaClass's properties are allowed.
     */
    protected boolean restricted;

    /**
     * <p>Controls whether the <code>getDynaProperty()</code> method returns
     * null if a property doesn't exist - or creates a new one.</p>
     *
     * <p>Default is <code>false</code>.
     */
    protected boolean returnNull = false;


    // ------------------- Constructors ----------------------------------

    /**
     * Default Constructor.
     */
    public LazyDynaMap() {
        this(null, (Map)null);
    }

    /**
     * Construct a new <code>LazyDynaMap</code> with the specified name.
     *
     * @param name Name of this DynaBean class
     */
    public LazyDynaMap(String name) {
        this(name, (Map)null);
    }

    /**
     * Construct a new <code>LazyDynaMap</code> with the specified <code>Map</code>.
     *
     * @param values The Map backing this <code>LazyDynaMap</code>
     */
    public LazyDynaMap(Map values) {
        this(null, values);
    }

    /**
     * Construct a new <code>LazyDynaMap</code> with the specified name and  <code>Map</code>.
     *
     * @param name Name of this DynaBean class
     * @param values The Map backing this <code>LazyDynaMap</code>
     */
    public LazyDynaMap(String name, Map values) {
        this.name      = name   == null ? "LazyDynaMap" : name;
        this.values    = values == null ? newMap()      : values;
        this.dynaClass = this;
    }

    /**
     * Construct a new <code>LazyDynaMap</code> with the specified properties.
     *
     * @param properties Property descriptors for the supported properties
     */
    public LazyDynaMap(DynaProperty[] properties) {
        this(null, properties);
    }

    /**
     * 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, (Map)null);
        if (properties != null) {
            for (int i = 0; i < properties.length; i++) {
                add(properties[i]);
            }
        }
    }

    /**
     * Construct a new <code>LazyDynaMap</code> based on an exisiting DynaClass
     *
     * @param dynaClass DynaClass to copy the name and properties from
     */
    public LazyDynaMap(DynaClass dynaClass) {
        this(dynaClass.getName(), dynaClass.getDynaProperties());
    }

    // ------------------- Public Methods ----------------------------------

    /**
     * Set the Map backing this <code>DynaBean</code>
     *
     * @param values The new Map of values
     */
    public void setMap(Map values) {
        this.values = values;
    }

    /**
     * Return the underlying Map backing this <code>DynaBean</code>
     * @return the underlying Map
     */
    public Map getMap() {
        return values;
    }

    // ------------------- DynaBean Methods ----------------------------------

    /**
     * Set the value of a simple property with the specified name.
     *
     * @param name Name of the property whose value is to be set
     * @param value Value to which this property is to be set
     */
    public void set(String name, Object value) {

        if (isRestricted() && !values.containsKey(name)) {
            throw new IllegalArgumentException
                    ("Invalid property name '" + name + "' (DynaClass is restricted)");
        }

        values.put(name, value);

    }

    // ------------------- DynaClass Methods ----------------------------------

    /**
     * Return the name of this DynaClass (analogous to the
     * <code>getName()</code> method of <code>java.lang.Class</code)
     *
     * @return the name of the DynaClass
     */
    public String getName() {
        return this.name;
    }

    /**
     * <p>Return a property descriptor for the specified property.</p>
     *
     * <p>If the property is not found and the <code>returnNull</code> indicator is
     *    <code>true</code>, this method always returns <code>null</code>.</p>
     *
     * <p>If the property is not found and the <code>returnNull</code> indicator is
     *    <code>false</code> a new property descriptor is created and returned (although
     *    its not actually added to the DynaClass's properties). This is the default
     *    beahviour.</p>
     *
     * <p>The reason for not returning a <code>null</code> property descriptor is that
     *    <code>BeanUtils</code> uses this method to check if a property exists
     *    before trying to set it - since these <i>Map</i> implementations automatically
     *    add any new properties when they are set, returning <code>null</code> from
     *    this method would defeat their purpose.</p>
     *
     * @param name Name of the dynamic property for which a descriptor
     *  is requested
     * @return The descriptor for the specified property
     *
     * @exception IllegalArgumentException if no property name is specified
     */
    public DynaProperty getDynaProperty(String name) {

        if (name == null) {
            throw new IllegalArgumentException("Property name is missing.");
        }

        // If it doesn't exist and returnNull is false
        // create a new DynaProperty
        if (!values.containsKey(name) && isReturnNull()) {
            return null;
        }

        Object value = values.get(name);

        if (value == null) {
            return new DynaProperty(name);
        } else {
            return new DynaProperty(name, value.getClass());
        }

    }

    /**
     * <p>Return an array of <code>ProperyDescriptors</code> for the properties
     * currently defined in this DynaClass.  If no properties are defined, a