/*
 * 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;

Provides a light weight DynaBean facade to a Map
 with lazy map/list processing.
Its a light weight DynaBean implementation because there is no
   actual DynaClass associated with this DynaBean - in fact
   it implements the DynaClass interface itself providing pseudo DynaClass
   behaviour from the actual values stored in the Map.
As well providing rhe standard DynaBean access to the Map's properties
   this class also provides the usual Lazy behaviour:
   

      
Properties don't need to be pre-defined in a DynaClass
      
Indexed properties (Lists or Arrays) are automatically instantiated
          and grown so that they are large enough to cater for the index being set.
      
Mapped properties are automatically instantiated.
   
Restricted DynaClass
   
This class implements the MutableDynaClass interface.
      MutableDynaClass have a facility to restrict the DynaClass
      so that its properties cannot be modified. If the MutableDynaClass is
      restricted then calling any of the set() methods for a property which
      doesn't exist will result in a IllegalArgumentException being thrown.
Version:
$Id$/**
 * <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>
 *
 * @version $Id$
 */
public class LazyDynaMap extends LazyDynaBean implements MutableDynaClass {

    
The name of this DynaClass (analogous to the
getName() method of java.lang.Class).
/**
     * 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.
/**
     * Controls whether changes to this DynaClass's properties are allowed.
     */
    protected boolean restricted;

    
Controls whether the getDynaProperty() method returns
null if a property doesn't exist - or creates a new one.
Default is false.
/**
     * <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.
/**
     * Default Constructor.
     */
    public LazyDynaMap() {
        this(null, (Map<String, Object>)null);
    }

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

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

    
Construct a new LazyDynaMap with the specified name and  Map.
Params:
name – Name of this DynaBean class
values – The Map backing this LazyDynaMap/**
     * 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(final String name, final Map<String, Object> values) {
        this.name      = name   == null ? "LazyDynaMap" : name;
        this.values    = values == null ? newMap()      : values;
        this.dynaClass = this;
    }

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

    
Construct a new LazyDynaMap with the specified name and properties.
Params:
name – Name of this DynaBean class
properties – Property descriptors for the supported 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(final String name, final DynaProperty[] properties) {
        this(name, (Map<String, Object>)null);
        if (properties != null) {
            for (DynaProperty propertie : properties) {
                add(propertie);
            }
        }
    }

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

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

    
Set the Map backing this DynaBean
Params:
values – The new Map of values/**
     * Set the Map backing this <code>DynaBean</code>
     *
     * @param values The new Map of values
     */
    public void setMap(final Map<String, Object> values) {
        this.values = values;
    }

    
Return the underlying Map backing this DynaBean
Returns:
the underlying Map
Since:
1.8.0/**
     * Return the underlying Map backing this <code>DynaBean</code>
     * @return the underlying Map
     * @since 1.8.0
     */
    @Override
    public Map<String, Object> getMap() {
        return values;
    }

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

    
Set the value of a simple property with the specified name.
Params:
name – Name of the property whose value is to be set
value – Value to which this property is to be set/**
     * 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
     */
    @Override
    public void set(final String name, final 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
getName() method of java.lang.Class)
Returns:
the name of the DynaClass/**
     * 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;
    }

    
Return a property descriptor for the specified property.
If the property is not found and the returnNull indicator is
   true, this method always returns null.
If the property is not found and the returnNull indicator is
   false a new property descriptor is created and returned (although
   its not actually added to the DynaClass's properties). This is the default
   beahviour.
The reason for not returning a null property descriptor is that
   BeanUtils uses this method to check if a property exists
   before trying to set it - since these Map implementations automatically
   add any new properties when they are set, returning null from
   this method would defeat their purpose.
Params:
name – Name of the dynamic property for which a descriptor
 is requested
Throws:
IllegalArgumentException – if no property name is specified
Returns:
The descriptor for the specified property/**
     * <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
     *
     * @throws IllegalArgumentException if no property name is specified
     */
    public DynaProperty getDynaProperty(final 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;
        }

        final Object value = values.get(name);

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

    }

    
Return an array of ProperyDescriptors for the properties
currently defined in this DynaClass.  If no properties are defined, a
zero-length array will be returned.
FIXME - Should we really be implementing
getBeanInfo() instead, which returns property descriptors
and a bunch of other stuff?
Returns:
the set of properties for this DynaClass/**
     * <p>Return an array of <code>ProperyDescriptors</code> for the properties
     * currently defined in this DynaClass.  If no properties are defined, a
     * zero-length array will be returned.</p>
     *
     * <p><strong>FIXME</strong> - Should we really be implementing
     * <code>getBeanInfo()</code> instead, which returns property descriptors
     * and a bunch of other stuff?</p>
     * @return the set of properties for this DynaClass
     */
    public DynaProperty[] getDynaProperties() {

        int i = 0;
        final DynaProperty[] properties = new DynaProperty[values.size()];
        for (final Map.Entry<String, Object> e : values.entrySet()) {
            final String name = e.getKey();
            final Object value = values.get(name);
            properties[i++] = new DynaProperty(name, value == null ? null
                    : value.getClass());
        }

        return properties;

    }

    
Instantiate and return a new DynaBean instance, associated
with this DynaClass.
Returns:
A new DynaBean instance/**
     * Instantiate and return a new DynaBean instance, associated
     * with this DynaClass.
     * @return A new <code>DynaBean</code> instance
     */
    public DynaBean newInstance()  {

        // Create a new instance of the Map
        Map<String, Object> newMap = null;
        try {
            @SuppressWarnings("unchecked")
            final
            // The new map is used as properties map
            Map<String, Object> temp = getMap().getClass().newInstance();
            newMap = temp;
        } catch(final Exception ex) {
            newMap = newMap();
        }

        // Crate new LazyDynaMap and initialize properties
        final LazyDynaMap lazyMap = new LazyDynaMap(newMap);
        final DynaProperty[] properties = this.getDynaProperties();
        if (properties != null) {
            for (DynaProperty propertie : properties) {
                lazyMap.add(propertie);
            }
        }
        return lazyMap;
    }


    // ------------------- MutableDynaClass Methods ----------------------------------

    
Is this DynaClass currently restricted.
If restricted, no changes to the existing registration of
 property names, data types, readability, or writeability are allowed.
Returns:
true if this Mutable DynaClass is restricted, otherwise false/**
     * <p>Is this DynaClass currently restricted.</p>
     * <p>If restricted, no changes to the existing registration of
     *  property names, data types, readability, or writeability are allowed.</p>
     *
     * @return <code>true</code> if this Mutable {@link DynaClass} is restricted,
     * otherwise <code>false</code>
     */
    public boolean isRestricted() {
        return restricted;
    }

    
Set whether this DynaClass is currently restricted.
If restricted, no changes to the existing registration of
 property names, data types, readability, or writeability are allowed.
Params:
restricted – The new restricted state/**
     * <p>Set whether this DynaClass is currently restricted.</p>
     * <p>If restricted, no changes to the existing registration of
     *  property names, data types, readability, or writeability are allowed.</p>
     *
     * @param restricted The new restricted state
     */
    public void setRestricted(final boolean restricted) {
        this.restricted = restricted;
    }

    
Add a new dynamic property with no restrictions on data type,
readability, or writeability.
Params:
name – Name of the new dynamic property
Throws:
IllegalArgumentException – if name is null/**
     * Add a new dynamic property with no restrictions on data type,
     * readability, or writeability.
     *
     * @param name Name of the new dynamic property
     *
     * @throws IllegalArgumentException if name is null
     */
    public void add(final String name) {
        add(name, null);
    }

    
Add a new dynamic property with the specified data type, but with
no restrictions on readability or writeability.
Params:
name – Name of the new dynamic property
type – Data type of the new dynamic property (null for no
 restrictions)
Throws:
IllegalArgumentException – if name is null
IllegalStateException – if this DynaClass is currently
 restricted, so no new properties can be added/**
     * Add a new dynamic property with the specified data type, but with
     * no restrictions on readability or writeability.
     *
     * @param name Name of the new dynamic property
     * @param type Data type of the new dynamic property (null for no
     *  restrictions)
     *
     * @throws IllegalArgumentException if name is null
     * @throws IllegalStateException if this DynaClass is currently
     *  restricted, so no new properties can be added
     */
    public void add(final String name, final Class<?> type) {

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

        if (isRestricted()) {
            throw new IllegalStateException("DynaClass is currently restricted. No new properties can be added.");
        }

        final Object value = values.get(name);

        // Check if the property already exists
        if (value == null) {
            values.put(name, type == null ? null : createProperty(name, type));
        }

    }

    
Add a new dynamic property with the specified data type, readability,
and writeability.
N.B.Support for readable/writeable properties has not been implemented
   and this method always throws a UnsupportedOperationException.
I'm not sure the intention of the original authors for this method, but it seems to
   me that readable/writable should be attributes of the DynaProperty class
   (which they are not) and is the reason this method has not been implemented.
Params:
name – Name of the new dynamic property
type – Data type of the new dynamic property (null for no
 restrictions)
readable – Set to true if this property value
 should be readable
writeable – Set to true if this property value
 should be writeable
Throws:
UnsupportedOperationException – anytime this method is called/**
     * <p>Add a new dynamic property with the specified data type, readability,
     * and writeability.</p>
     *
     * <p><strong>N.B.</strong>Support for readable/writeable properties has not been implemented
     *    and this method always throws a <code>UnsupportedOperationException</code>.</p>
     *
     * <p>I'm not sure the intention of the original authors for this method, but it seems to
     *    me that readable/writable should be attributes of the <code>DynaProperty</code> class
     *    (which they are not) and is the reason this method has not been implemented.</p>
     *
     * @param name Name of the new dynamic property
     * @param type Data type of the new dynamic property (null for no
     *  restrictions)
     * @param readable Set to <code>true</code> if this property value
     *  should be readable
     * @param writeable Set to <code>true</code> if this property value
     *  should be writeable
     *
     * @throws UnsupportedOperationException anytime this method is called
     */
    public void add(final String name, final Class<?> type, final boolean readable, final boolean writeable) {
        throw new java.lang.UnsupportedOperationException("readable/writable properties not supported");
    }

    
Add a new dynamic property.
Params:
property – Property the new dynamic property to add.
Throws:
IllegalArgumentException – if name is null/**
     * Add a new dynamic property.
     *
     * @param property Property the new dynamic property to add.
     *
     * @throws IllegalArgumentException if name is null
     */
    protected void add(final DynaProperty property) {
        add(property.getName(), property.getType());
    }

    
Remove the specified dynamic property, and any associated data type,
readability, and writeability, from this dynamic class.
NOTE - This does NOT cause any
corresponding property values to be removed from DynaBean instances
associated with this DynaClass.
Params:
name – Name of the dynamic property to remove
Throws:
IllegalArgumentException – if name is null
IllegalStateException – if this DynaClass is currently
 restricted, so no properties can be removed/**
     * Remove the specified dynamic property, and any associated data type,
     * readability, and writeability, from this dynamic class.
     * <strong>NOTE</strong> - This does <strong>NOT</strong> cause any
     * corresponding property values to be removed from DynaBean instances
     * associated with this DynaClass.
     *
     * @param name Name of the dynamic property to remove
     *
     * @throws IllegalArgumentException if name is null
     * @throws IllegalStateException if this DynaClass is currently
     *  restricted, so no properties can be removed
     */
    public void remove(final String name) {

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

        if (isRestricted()) {
            throw new IllegalStateException("DynaClass is currently restricted. No properties can be removed.");
        }

        // Remove, if property doesn't exist
        if (values.containsKey(name)) {
            values.remove(name);
        }

    }


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

    
Should this DynaClass return a null from
the getDynaProperty(name) method if the property
doesn't exist.
Returns:
true if a null DynaProperty should be returned if the property doesn't exist, otherwise false if a new DynaProperty should be created./**
     * Should this DynaClass return a <code>null</code> from
     * the <code>getDynaProperty(name)</code> method if the property
     * doesn't exist.
     *
     * @return <code>true</code> if a <code>null</code> {@link DynaProperty}
     * should be returned if the property doesn't exist, otherwise
     * <code>false</code> if a new {@link DynaProperty} should be created.
     */
    public boolean isReturnNull() {
        return returnNull;
    }

    
Set whether this DynaClass should return a null from
the getDynaProperty(name) method if the property
doesn't exist.
Params:
returnNull – true if a null DynaProperty should be returned if the property doesn't exist, otherwise false if a new DynaProperty should be created./**
     * Set whether this DynaClass should return a <code>null</code> from
     * the <code>getDynaProperty(name)</code> method if the property
     * doesn't exist.
     *
     * @param returnNull <code>true</code> if a <code>null</code> {@link DynaProperty}
     * should be returned if the property doesn't exist, otherwise
     * <code>false</code> if a new {@link DynaProperty} should be created.
     */
    public void setReturnNull(final boolean returnNull) {
        this.returnNull = returnNull;
    }


    // ------------------- Protected Methods ----------------------------------

   
Indicate whether a property actually exists.
N.B. Using getDynaProperty(name) == null
doesn't work in this implementation because that method might
return a DynaProperty if it doesn't exist (depending on the
returnNull indicator).
Params:
name – Name of the dynamic property
Throws:
IllegalArgumentException – if no property name is specified
Returns:
true if the property exists,
otherwise false/**
     * <p>Indicate whether a property actually exists.</p>
     *
     * <p><strong>N.B.</strong> Using <code>getDynaProperty(name) == null</code>
     * doesn't work in this implementation because that method might
     * return a DynaProperty if it doesn't exist (depending on the
     * <code>returnNull</code> indicator).</p>
     *
     * @param name Name of the dynamic property
     * @return <code>true</code> if the property exists,
     * otherwise <code>false</code>
     * @throws IllegalArgumentException if no property name is specified
     */
    @Override
    protected boolean isDynaProperty(final String name) {

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

        return values.containsKey(name);

    }

}