    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}