/*

  * 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

      * @since 1.8.0

      */

     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

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

         DynaProperty[] properties = new DynaProperty[values.size()];

         Iterator iterator = values.keySet().iterator();

         while (iterator.hasNext()) {

             String name = (String)iterator.next();

             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.

      * @return A new <code>DynaBean</code> instance

      */

     public DynaBean newInstance()  {

         // Create a new instance of the Map

         Map newMap = null;

         try {

             newMap = (Map)getMap().getClass().newInstance();

         } catch(Exception ex) {

             newMap = newMap();

         }

         // Crate new LazyDynaMap and initialize properties

         LazyDynaMap lazyMap = new LazyDynaMap(newMap);

         DynaProperty[] properties = this.getDynaProperties();

         if (properties != null) {

             for (int i = 0; i < properties.length; i++) {

                 lazyMap.add(properties[i]);

             }

         }

         return lazyMap;

     }

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

     /**

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

     }

     /**

      * <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(boolean restricted) {

         this.restricted = restricted;

     }

     /**

      * Add a new dynamic property with no restrictions on data type,

      * readability, or writeability.

      *

      * @param name Name of the new dynamic property

      *

      * @exception IllegalArgumentException if name is null

      */

     public void add(String name) {

         add(name, null);

     }

     /**

      * 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)

      *

      * @exception IllegalArgumentException if name is null

      * @exception IllegalStateException if this DynaClass is currently

      *  restricted, so no new properties can be added

      */

     public void add(String name, 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.");

         }

         Object value = values.get(name);

         // Check if the property already exists

         if (value == null) {

             values.put(name, type == null ? null : createProperty(name, type));

         }

     }

     /**

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

      *

      * @exception UnsupportedOperationException anytime this method is called

      */

     public void add(String name, Class type, boolean readable, boolean writeable) {

         throw new java.lang.UnsupportedOperationException("readable/writable properties not supported");

     }

     /**

      * Add a new dynamic property.

      *

      * @param property Property the new dynamic property to add.

      *

      * @exception IllegalArgumentException if name is null

      */

     protected void add(DynaProperty property) {

         add(property.getName(), property.getType());

     }

     /**

      * 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

      *

      * @exception IllegalArgumentException if name is null

      * @exception IllegalStateException if this DynaClass is currently

      *  restricted, so no properties can be removed

      */

     public void remove(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 <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 <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(boolean returnNull) {

         this.returnNull = returnNull;

     }

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

    /**

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

      * @exception IllegalArgumentException if no property name is specified

      */

     protected boolean isDynaProperty(String name) {

         if (name == null) {

             throw new IllegalArgumentException("Property name is missing.");

         }

         return values.containsKey(name);

     }

 }