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 * @version $Id$
30 */
31
32 public interface DynaBean {
33
34
35 /**
36 * Does the specified mapped property contain a value for the specified
37 * key value?
38 *
39 * @param name Name of the property to check
40 * @param key Name of the key to check
41 * @return <code>true<code> if the mapped property contains a value for
42 * the specified key, otherwise <code>false</code>
43 *
44 * @throws IllegalArgumentException if there is no property
45 * of the specified name
46 */
47 public boolean contains(String name, String key);
48
49
50 /**
51 * Return the value of a simple property with the specified name.
52 *
53 * @param name Name of the property whose value is to be retrieved
54 * @return The property's value
55 *
56 * @throws IllegalArgumentException if there is no property
57 * of the specified name
58 */
59 public Object get(String name);
60
61
62 /**
63 * Return the value of an indexed property with the specified name.
64 *
65 * @param name Name of the property whose value is to be retrieved
66 * @param index Index of the value to be retrieved
67 * @return The indexed property's value
68 *
69 * @throws IllegalArgumentException if there is no property
70 * of the specified name
71 * @throws IllegalArgumentException if the specified property
72 * exists, but is not indexed
73 * @throws IndexOutOfBoundsException if the specified index
74 * is outside the range of the underlying property
75 * @throws NullPointerException if no array or List has been
76 * initialized for this property
77 */
78 public Object get(String name, int index);
79
80
81 /**
82 * Return the value of a mapped property with the specified name,
83 * or <code>null</code> if there is no value for the specified key.
84 *
85 * @param name Name of the property whose value is to be retrieved
86 * @param key Key of the value to be retrieved
87 * @return The mapped property's value
88 *
89 * @throws IllegalArgumentException if there is no property
90 * of the specified name
91 * @throws IllegalArgumentException if the specified property
92 * exists, but is not mapped
93 */
94 public Object get(String name, String key);
95
96
97 /**
98 * Return the <code>DynaClass</code> instance that describes the set of
99 * 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 }