    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     */
    017
    018
    019    package org.apache.commons.beanutils;
    020
    021
    022    /**
    023     * <p>A <strong>DynaBean</strong> is a Java object that supports properties
    024     * whose names and data types, as well as values, may be dynamically modified.
    025     * To the maximum degree feasible, other components of the BeanUtils package
    026     * will recognize such beans and treat them as standard JavaBeans for the
    027     * purpose of retrieving and setting property values.</p>
    028     *
    029     * @author Craig McClanahan
    030     * @author Paulo Gaspar
    031     * @version $Revision: 555824 $ $Date: 2007-07-13 01:27:15 +0100 (Fri, 13 Jul 2007) $
    032     */
    033
    034    public interface DynaBean {
    035
    036
    037        /**
    038         * Does the specified mapped property contain a value for the specified
    039         * key value?
    040         *
    041         * @param name Name of the property to check
    042         * @param key Name of the key to check
    043         * @return <code>true<code> if the mapped property contains a value for
    044         * the specified key, otherwise <code>false</code>
    045         *
    046         * @exception IllegalArgumentException if there is no property
    047         *  of the specified name
    048         */
    049        public boolean contains(String name, String key);
    050
    051
    052        /**
    053         * Return the value of a simple property with the specified name.
    054         *
    055         * @param name Name of the property whose value is to be retrieved
    056         * @return The property's value
    057         *
    058         * @exception IllegalArgumentException if there is no property
    059         *  of the specified name
    060         */
    061        public Object get(String name);
    062
    063
    064        /**
    065         * Return the value of an indexed property with the specified name.
    066         *
    067         * @param name Name of the property whose value is to be retrieved
    068         * @param index Index of the value to be retrieved
    069         * @return The indexed property's value
    070         *
    071         * @exception IllegalArgumentException if there is no property
    072         *  of the specified name
    073         * @exception IllegalArgumentException if the specified property
    074         *  exists, but is not indexed
    075         * @exception IndexOutOfBoundsException if the specified index
    076         *  is outside the range of the underlying property
    077         * @exception NullPointerException if no array or List has been
    078         *  initialized for this property
    079         */
    080        public Object get(String name, int index);
    081
    082
    083        /**
    084         * Return the value of a mapped property with the specified name,
    085         * or <code>null</code> if there is no value for the specified key.
    086         *
    087         * @param name Name of the property whose value is to be retrieved
    088         * @param key Key of the value to be retrieved
    089         * @return The mapped property's value
    090         *
    091         * @exception IllegalArgumentException if there is no property
    092         *  of the specified name
    093         * @exception IllegalArgumentException if the specified property
    094         *  exists, but is not mapped
    095         */
    096        public Object get(String name, String key);
    097
    098
    099        /**
    100         * Return the <code>DynaClass</code> instance that describes the set of
    101         * properties available for this DynaBean.
    102         *
    103         * @return The associated DynaClass
    104         */
    105        public DynaClass getDynaClass();
    106
    107
    108        /**
    109         * Remove any existing value for the specified key on the
    110         * specified mapped property.
    111         *
    112         * @param name Name of the property for which a value is to
    113         *  be removed
    114         * @param key Key of the value to be removed
    115         *
    116         * @exception IllegalArgumentException if there is no property
    117         *  of the specified name
    118         */
    119        public void remove(String name, String key);
    120
    121
    122        /**
    123         * Set the value of a simple property with the specified name.
    124         *
    125         * @param name Name of the property whose value is to be set
    126         * @param value Value to which this property is to be set
    127         *
    128         * @exception ConversionException if the specified value cannot be
    129         *  converted to the type required for this property
    130         * @exception IllegalArgumentException if there is no property
    131         *  of the specified name
    132         * @exception NullPointerException if an attempt is made to set a
    133         *  primitive property to null
    134         */
    135        public void set(String name, Object value);
    136
    137
    138        /**
    139         * Set the value of an indexed property with the specified name.
    140         *
    141         * @param name Name of the property whose value is to be set
    142         * @param index Index of the property to be set
    143         * @param value Value to which this property is to be set
    144         *
    145         * @exception ConversionException if the specified value cannot be
    146         *  converted to the type required for this property
    147         * @exception IllegalArgumentException if there is no property
    148         *  of the specified name
    149         * @exception IllegalArgumentException if the specified property
    150         *  exists, but is not indexed
    151         * @exception IndexOutOfBoundsException if the specified index
    152         *  is outside the range of the underlying property
    153         */
    154        public void set(String name, int index, Object value);
    155
    156
    157        /**
    158         * Set the value of a mapped property with the specified name.
    159         *
    160         * @param name Name of the property whose value is to be set
    161         * @param key Key of the property to be set
    162         * @param value Value to which this property is to be set
    163         *
    164         * @exception ConversionException if the specified value cannot be
    165         *  converted to the type required for this property
    166         * @exception IllegalArgumentException if there is no property
    167         *  of the specified name
    168         * @exception IllegalArgumentException if the specified property
    169         *  exists, but is not mapped
    170         */
    171        public void set(String name, String key, Object value);
    172
    173
    174    }