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
019package 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
034public 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}