View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18
    19  package org.apache.commons.beanutils;
    20
    21
    22  /***
    23   * <p>A <strong>DynaBean</strong> is a Java object that supports properties
    24   * whose names and data types, as well as values, may be dynamically modified.
    25   * To the maximum degree feasible, other components of the BeanUtils package
    26   * will recognize such beans and treat them as standard JavaBeans for the
    27   * purpose of retrieving and setting property values.</p>
    28   *
    29   * @author Craig McClanahan
    30   * @author Paulo Gaspar
    31   * @version $Revision: 555824 $ $Date: 2007-07-13 01:27:15 +0100 (Fri, 13 Jul 2007) $
    32   */
    33
    34  public interface DynaBean {
    35
    36
    37      /***
    38       * Does the specified mapped property contain a value for the specified
    39       * key value?
    40       *
    41       * @param name Name of the property to check
    42       * @param key Name of the key to check
    43       * @return <code>true<code> if the mapped property contains a value for
    44       * the specified key, otherwise <code>false</code>
    45       *
    46       * @exception IllegalArgumentException if there is no property
    47       *  of the specified name
    48       */
    49      public boolean contains(String name, String key);
    50
    51
    52      /***
    53       * Return the value of a simple property with the specified name.
    54       *
    55       * @param name Name of the property whose value is to be retrieved
    56       * @return The property's value
    57       *
    58       * @exception IllegalArgumentException if there is no property
    59       *  of the specified name
    60       */
    61      public Object get(String name);
    62
    63
    64      /***
    65       * Return the value of an indexed property with the specified name.
    66       *
    67       * @param name Name of the property whose value is to be retrieved
    68       * @param index Index of the value to be retrieved
    69       * @return The indexed property's value
    70       *
    71       * @exception IllegalArgumentException if there is no property
    72       *  of the specified name
    73       * @exception IllegalArgumentException if the specified property
    74       *  exists, but is not indexed
    75       * @exception IndexOutOfBoundsException if the specified index
    76       *  is outside the range of the underlying property
    77       * @exception NullPointerException if no array or List has been
    78       *  initialized for this property
    79       */
    80      public Object get(String name, int index);
    81
    82
    83      /***
    84       * Return the value of a mapped property with the specified name,
    85       * or <code>null</code> if there is no value for the specified key.
    86       *
    87       * @param name Name of the property whose value is to be retrieved
    88       * @param key Key of the value to be retrieved
    89       * @return The mapped property's value
    90       *
    91       * @exception IllegalArgumentException if there is no property
    92       *  of the specified name
    93       * @exception IllegalArgumentException if the specified property
    94       *  exists, but is not mapped
    95       */
    96      public Object get(String name, String key);
    97
    98
    99      /***
    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 }