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
018
019 package org.apache.commons.beanutils;
020
021
022 /**
023 * <p>A <strong>DynaBean</strong> is a Java object that supports properties
024 * whose names and data types, as well as values, may be dynamically modified.
025 * To the maximum degree feasible, other components of the BeanUtils package
026 * will recognize such beans and treat them as standard JavaBeans for the
027 * purpose of retrieving and setting property values.</p>
028 *
029 * @author Craig McClanahan
030 * @author Paulo Gaspar
031 * @version $Revision: 555824 $ $Date: 2007-07-13 01:27:15 +0100 (Fri, 13 Jul 2007) $
032 */
033
034 public interface DynaBean {
035
036
037 /**
038 * Does the specified mapped property contain a value for the specified
039 * key value?
040 *
041 * @param name Name of the property to check
042 * @param key Name of the key to check
043 * @return <code>true<code> if the mapped property contains a value for
044 * the specified key, otherwise <code>false</code>
045 *
046 * @exception IllegalArgumentException if there is no property
047 * of the specified name
048 */
049 public boolean contains(String name, String key);
050
051
052 /**
053 * Return the value of a simple property with the specified name.
054 *
055 * @param name Name of the property whose value is to be retrieved
056 * @return The property's value
057 *
058 * @exception IllegalArgumentException if there is no property
059 * of the specified name
060 */
061 public Object get(String name);
062
063
064 /**
065 * Return the value of an indexed property with the specified name.
066 *
067 * @param name Name of the property whose value is to be retrieved
068 * @param index Index of the value to be retrieved
069 * @return The indexed property's value
070 *
071 * @exception IllegalArgumentException if there is no property
072 * of the specified name
073 * @exception IllegalArgumentException if the specified property
074 * exists, but is not indexed
075 * @exception IndexOutOfBoundsException if the specified index
076 * is outside the range of the underlying property
077 * @exception NullPointerException if no array or List has been
078 * initialized for this property
079 */
080 public Object get(String name, int index);
081
082
083 /**
084 * Return the value of a mapped property with the specified name,
085 * or <code>null</code> if there is no value for the specified key.
086 *
087 * @param name Name of the property whose value is to be retrieved
088 * @param key Key of the value to be retrieved
089 * @return The mapped property's value
090 *
091 * @exception IllegalArgumentException if there is no property
092 * of the specified name
093 * @exception IllegalArgumentException if the specified property
094 * exists, but is not mapped
095 */
096 public Object get(String name, String key);
097
098
099 /**
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 }