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 }