View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */ 
16  
17  
18  package org.apache.commons.beanutils;
19  
20  
21  /**
22   * <p>A <strong>DynaBean</strong> is a Java object that supports properties
23   * whose names and data types, as well as values, may be dynamically modified.
24   * To the maximum degree feasible, other components of the BeanUtils package
25   * will recognize such beans and treat them as standard JavaBeans for the
26   * purpose of retrieving and setting property values.</p>
27   *
28   * @author Craig McClanahan
29   * @author Paulo Gaspar
30   * @version $Revision: 1.9 $ $Date: 2004/02/28 13:18:33 $
31   */
32  
33  public interface DynaBean {
34  
35  
36      /**
37       * Does the specified mapped property contain a value for the specified
38       * key value?
39       *
40       * @param name Name of the property to check
41       * @param key Name of the key to check
42       *
43       * @exception IllegalArgumentException if there is no property
44       *  of the specified name
45       */
46      public boolean contains(String name, String key);
47  
48  
49      /**
50       * Return the value of a simple property with the specified name.
51       *
52       * @param name Name of the property whose value is to be retrieved
53       *
54       * @exception IllegalArgumentException if there is no property
55       *  of the specified name
56       */
57      public Object get(String name);
58  
59  
60      /**
61       * Return the value of an indexed property with the specified name.
62       *
63       * @param name Name of the property whose value is to be retrieved
64       * @param index Index of the value to be retrieved
65       *
66       * @exception IllegalArgumentException if there is no property
67       *  of the specified name
68       * @exception IllegalArgumentException if the specified property
69       *  exists, but is not indexed
70       * @exception IndexOutOfBoundsException if the specified index
71       *  is outside the range of the underlying property
72       * @exception NullPointerException if no array or List has been
73       *  initialized for this property
74       */
75      public Object get(String name, int index);
76  
77  
78      /**
79       * Return the value of a mapped property with the specified name,
80       * or <code>null</code> if there is no value for the specified key.
81       *
82       * @param name Name of the property whose value is to be retrieved
83       * @param key Key of the value to be retrieved
84       *
85       * @exception IllegalArgumentException if there is no property
86       *  of the specified name
87       * @exception IllegalArgumentException if the specified property
88       *  exists, but is not mapped
89       */
90      public Object get(String name, String key);
91  
92  
93      /**
94       * Return the <code>DynaClass</code> instance that describes the set of
95       * properties available for this DynaBean.
96       */
97      public DynaClass getDynaClass();
98  
99  
100     /**
101      * Remove any existing value for the specified key on the
102      * specified mapped property.
103      *
104      * @param name Name of the property for which a value is to
105      *  be removed
106      * @param key Key of the value to be removed
107      *
108      * @exception IllegalArgumentException if there is no property
109      *  of the specified name
110      */
111     public void remove(String name, String key);
112 
113 
114     /**
115      * Set the value of a simple property with the specified name.
116      *
117      * @param name Name of the property whose value is to be set
118      * @param value Value to which this property is to be set
119      *
120      * @exception ConversionException if the specified value cannot be
121      *  converted to the type required for this property
122      * @exception IllegalArgumentException if there is no property
123      *  of the specified name
124      * @exception NullPointerException if an attempt is made to set a
125      *  primitive property to null
126      */
127     public void set(String name, Object value);
128 
129 
130     /**
131      * Set the value of an indexed property with the specified name.
132      *
133      * @param name Name of the property whose value is to be set
134      * @param index Index of the property to be set
135      * @param value Value to which this property is to be set
136      *
137      * @exception ConversionException if the specified value cannot be
138      *  converted to the type required for this property
139      * @exception IllegalArgumentException if there is no property
140      *  of the specified name
141      * @exception IllegalArgumentException if the specified property
142      *  exists, but is not indexed
143      * @exception IndexOutOfBoundsException if the specified index
144      *  is outside the range of the underlying property
145      */
146     public void set(String name, int index, Object value);
147 
148 
149     /**
150      * Set the value of a mapped property with the specified name.
151      *
152      * @param name Name of the property whose value is to be set
153      * @param key Key of the property to be set
154      * @param value Value to which this property is to be set
155      *
156      * @exception ConversionException if the specified value cannot be
157      *  converted to the type required for this property
158      * @exception IllegalArgumentException if there is no property
159      *  of the specified name
160      * @exception IllegalArgumentException if the specified property
161      *  exists, but is not mapped
162      */
163     public void set(String name, String key, Object value);
164 
165 
166 }