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