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 package org.apache.commons.beanutils2;
19
20 /**
21 * <p>
22 * A <strong>DynaBean</strong> is a Java object that supports properties whose names and data types, as well as values, may be dynamically modified. To the
23 * maximum degree feasible, other components of the BeanUtils package will recognize such beans and treat them as standard JavaBeans for the purpose of
24 * retrieving and setting property values.
25 * </p>
26 */
27 public interface DynaBean {
28
29 /**
30 * Does the specified mapped property contain a value for the specified key value?
31 *
32 * @param name Name of the property to check
33 * @param key Name of the key to check
34 * @return {@code true} if the mapped property contains a value for the specified key, otherwise {@code false}
35 * @throws IllegalArgumentException if there is no property of the specified name
36 */
37 boolean contains(String name, String key);
38
39 /**
40 * Gets the value of a simple property with the specified name.
41 *
42 * @param name Name of the property whose value is to be retrieved
43 * @return The property's value
44 * @throws IllegalArgumentException if there is no property of the specified name
45 */
46 Object get(String name);
47
48 /**
49 * Gets the value of an indexed property with the specified name.
50 *
51 * @param name Name of the property whose value is to be retrieved
52 * @param index Index of the value to be retrieved
53 * @return The indexed property's value
54 * @throws IllegalArgumentException if there is no property of the specified name
55 * @throws IllegalArgumentException if the specified property exists, but is not indexed
56 * @throws IndexOutOfBoundsException if the specified index is outside the range of the underlying property
57 * @throws NullPointerException if no array or List has been initialized for this property
58 */
59 Object get(String name, int index);
60
61 /**
62 * Gets the value of a mapped property with the specified name, or {@code null} if there is no value for the specified key.
63 *
64 * @param name Name of the property whose value is to be retrieved
65 * @param key Key of the value to be retrieved
66 * @return The mapped property's value
67 * @throws IllegalArgumentException if there is no property of the specified name
68 * @throws IllegalArgumentException if the specified property exists, but is not mapped
69 */
70 Object get(String name, String key);
71
72 /**
73 * Gets the {@code DynaClass} instance that describes the set of properties available for this DynaBean.
74 *
75 * @return The associated DynaClass
76 */
77 DynaClass getDynaClass();
78
79 /**
80 * Remove any existing value for the specified key on the specified mapped property.
81 *
82 * @param name Name of the property for which a value is to be removed
83 * @param key Key of the value to be removed
84 * @throws IllegalArgumentException if there is no property of the specified name
85 */
86 void remove(String name, String key);
87
88 /**
89 * Sets the value of an indexed property with the specified name.
90 *
91 * @param name Name of the property whose value is to be set
92 * @param index Index of the property to be set
93 * @param value Value to which this property is to be set
94 * @throws ConversionException if the specified value cannot be converted to the type required for this property
95 * @throws IllegalArgumentException if there is no property of the specified name
96 * @throws IllegalArgumentException if the specified property exists, but is not indexed
97 * @throws IndexOutOfBoundsException if the specified index is outside the range of the underlying property
98 */
99 void set(String name, int index, Object value);
100
101 /**
102 * Sets the value of a simple property with the specified name.
103 *
104 * @param name Name of the property whose value is to be set
105 * @param value Value to which this property is to be set
106 * @throws ConversionException if the specified value cannot be converted to the type required for this property
107 * @throws IllegalArgumentException if there is no property of the specified name
108 * @throws NullPointerException if an attempt is made to set a primitive property to null
109 */
110 void set(String name, Object value);
111
112 /**
113 * Sets the value of a mapped property with the specified name.
114 *
115 * @param name Name of the property whose value is to be set
116 * @param key Key of the property to be set
117 * @param value Value to which this property is to be set
118 * @throws ConversionException if the specified value cannot be converted to the type required for this property
119 * @throws IllegalArgumentException if there is no property of the specified name
120 * @throws IllegalArgumentException if the specified property exists, but is not mapped
121 */
122 void set(String name, String key, Object value);
123
124 }