    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 * @version $Id$
    030 */
    031
    032public interface DynaBean {
    033
    034
    035    /**
    036     * Does the specified mapped property contain a value for the specified
    037     * key value?
    038     *
    039     * @param name Name of the property to check
    040     * @param key Name of the key to check
    041     * @return <code>true<code> if the mapped property contains a value for
    042     * the specified key, otherwise <code>false</code>
    043     *
    044     * @throws IllegalArgumentException if there is no property
    045     *  of the specified name
    046     */
    047    public boolean contains(String name, String key);
    048
    049
    050    /**
    051     * Return the value of a simple property with the specified name.
    052     *
    053     * @param name Name of the property whose value is to be retrieved
    054     * @return The property's value
    055     *
    056     * @throws IllegalArgumentException if there is no property
    057     *  of the specified name
    058     */
    059    public Object get(String name);
    060
    061
    062    /**
    063     * Return the value of an indexed property with the specified name.
    064     *
    065     * @param name Name of the property whose value is to be retrieved
    066     * @param index Index of the value to be retrieved
    067     * @return The indexed property's value
    068     *
    069     * @throws IllegalArgumentException if there is no property
    070     *  of the specified name
    071     * @throws IllegalArgumentException if the specified property
    072     *  exists, but is not indexed
    073     * @throws IndexOutOfBoundsException if the specified index
    074     *  is outside the range of the underlying property
    075     * @throws NullPointerException if no array or List has been
    076     *  initialized for this property
    077     */
    078    public Object get(String name, int index);
    079
    080
    081    /**
    082     * Return the value of a mapped property with the specified name,
    083     * or <code>null</code> if there is no value for the specified key.
    084     *
    085     * @param name Name of the property whose value is to be retrieved
    086     * @param key Key of the value to be retrieved
    087     * @return The mapped property's value
    088     *
    089     * @throws IllegalArgumentException if there is no property
    090     *  of the specified name
    091     * @throws IllegalArgumentException if the specified property
    092     *  exists, but is not mapped
    093     */
    094    public Object get(String name, String key);
    095
    096
    097    /**
    098     * Return the <code>DynaClass</code> instance that describes the set of
    099     * properties available for this DynaBean.
    100     *
    101     * @return The associated DynaClass
    102     */
    103    public DynaClass getDynaClass();
    104
    105
    106    /**
    107     * Remove any existing value for the specified key on the
    108     * specified mapped property.
    109     *
    110     * @param name Name of the property for which a value is to
    111     *  be removed
    112     * @param key Key of the value to be removed
    113     *
    114     * @throws IllegalArgumentException if there is no property
    115     *  of the specified name
    116     */
    117    public void remove(String name, String key);
    118
    119
    120    /**
    121     * Set the value of a simple property with the specified name.
    122     *
    123     * @param name Name of the property whose value is to be set
    124     * @param value Value to which this property is to be set
    125     *
    126     * @throws ConversionException if the specified value cannot be
    127     *  converted to the type required for this property
    128     * @throws IllegalArgumentException if there is no property
    129     *  of the specified name
    130     * @throws NullPointerException if an attempt is made to set a
    131     *  primitive property to null
    132     */
    133    public void set(String name, Object value);
    134
    135
    136    /**
    137     * Set the value of an indexed property with the specified name.
    138     *
    139     * @param name Name of the property whose value is to be set
    140     * @param index Index of the property to be set
    141     * @param value Value to which this property is to be set
    142     *
    143     * @throws ConversionException if the specified value cannot be
    144     *  converted to the type required for this property
    145     * @throws IllegalArgumentException if there is no property
    146     *  of the specified name
    147     * @throws IllegalArgumentException if the specified property
    148     *  exists, but is not indexed
    149     * @throws IndexOutOfBoundsException if the specified index
    150     *  is outside the range of the underlying property
    151     */
    152    public void set(String name, int index, Object value);
    153
    154
    155    /**
    156     * Set the value of a mapped property with the specified name.
    157     *
    158     * @param name Name of the property whose value is to be set
    159     * @param key Key of the property to be set
    160     * @param value Value to which this property is to be set
    161     *
    162     * @throws ConversionException if the specified value cannot be
    163     *  converted to the type required for this property
    164     * @throws IllegalArgumentException if there is no property
    165     *  of the specified name
    166     * @throws IllegalArgumentException if the specified property
    167     *  exists, but is not mapped
    168     */
    169    public void set(String name, String key, Object value);
    170
    171
    172}