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  
23  
24  /**
25   * <p>Implementation of <code>DynaBean</code> that wraps a standard JavaBean
26   * instance, so that DynaBean APIs can be used to access its properties.</p>
27   *
28   * <p>
29   * The most common use cases for this class involve wrapping an existing java bean.
30   * (This makes it different from the typical use cases for other <code>DynaBean</code>'s.) 
31   * For example:
32   * </p>
33   * <code><pre>
34   *  Object aJavaBean = ...;
35   *  ...
36   *  DynaBean db = new WrapDynaBean(aJavaBean);
37   *  ...
38   * </pre></code>
39   *
40   * <p><strong>IMPLEMENTATION NOTE</strong> - This implementation does not
41   * support the <code>contains()</code> and <code>remove()</code> methods.</p>
42   *
43   * @author Craig McClanahan
44   * @version $Revision: 1.9 $ $Date: 2004/02/28 13:18:34 $
45   */
46  
47  public class WrapDynaBean implements DynaBean {
48  
49  
50      // ---------------------------------------------------------- Constructors
51  
52  
53      /**
54       * Construct a new <code>DynaBean</code> associated with the specified
55       * JavaBean instance.
56       *
57       * @param instance JavaBean instance to be wrapped
58       */
59      public WrapDynaBean(Object instance) {
60  
61          super();
62          this.instance = instance;
63          this.dynaClass = WrapDynaClass.createDynaClass(instance.getClass());
64  
65      }
66  
67  
68      // ---------------------------------------------------- Instance Variables
69  
70  
71      /**
72       * The <code>DynaClass</code> "base class" that this DynaBean
73       * is associated with.
74       */
75      protected WrapDynaClass dynaClass = null;
76  
77  
78      /**
79       * The JavaBean instance wrapped by this WrapDynaBean.
80       */
81      protected Object instance = null;
82  
83  
84      // ------------------------------------------------------ DynaBean Methods
85  
86  
87      /**
88       * Does the specified mapped property contain a value for the specified
89       * key value?
90       *
91       * @param name Name of the property to check
92       * @param key Name of the key to check
93       *
94       * @exception IllegalArgumentException if there is no property
95       *  of the specified name
96       */
97      public boolean contains(String name, String key) {
98  
99          throw new UnsupportedOperationException
100                 ("WrapDynaBean does not support contains()");
101 
102     }
103 
104 
105     /**
106      * Return the value of a simple property with the specified name.
107      *
108      * @param name Name of the property whose value is to be retrieved
109      *
110      * @exception IllegalArgumentException if there is no property
111      *  of the specified name
112      */
113     public Object get(String name) {
114 
115         Object value = null;
116         try {
117             value = PropertyUtils.getSimpleProperty(instance, name);
118         } catch (Throwable t) {
119             throw new IllegalArgumentException
120                     ("Property '" + name + "' has no read method");
121         }
122         return (value);
123 
124     }
125 
126 
127     /**
128      * Return the value of an indexed property with the specified name.
129      *
130      * @param name Name of the property whose value is to be retrieved
131      * @param index Index of the value to be retrieved
132      *
133      * @exception IllegalArgumentException if there is no property
134      *  of the specified name
135      * @exception IllegalArgumentException if the specified property
136      *  exists, but is not indexed
137      * @exception IndexOutOfBoundsException if the specified index
138      *  is outside the range of the underlying property
139      * @exception NullPointerException if no array or List has been
140      *  initialized for this property
141      */
142     public Object get(String name, int index) {
143 
144         Object value = null;
145         try {
146             value = PropertyUtils.getIndexedProperty(instance, name, index);
147         } catch (IndexOutOfBoundsException e) {
148             throw e;
149         } catch (Throwable t) {
150             throw new IllegalArgumentException
151                     ("Property '" + name + "' has no indexed read method");
152         }
153         return (value);
154 
155     }
156 
157 
158     /**
159      * Return the value of a mapped property with the specified name,
160      * or <code>null</code> if there is no value for the specified key.
161      *
162      * @param name Name of the property whose value is to be retrieved
163      * @param key Key of the value to be retrieved
164      *
165      * @exception IllegalArgumentException if there is no property
166      *  of the specified name
167      * @exception IllegalArgumentException if the specified property
168      *  exists, but is not mapped
169      */
170     public Object get(String name, String key) {
171 
172         Object value = null;
173         try {
174             value = PropertyUtils.getMappedProperty(instance, name, key);
175         } catch (Throwable t) {
176             throw new IllegalArgumentException
177                     ("Property '" + name + "' has no mapped read method");
178         }
179         return (value);
180 
181     }
182 
183 
184     /**
185      * Return the <code>DynaClass</code> instance that describes the set of
186      * properties available for this DynaBean.
187      */
188     public DynaClass getDynaClass() {
189 
190         return (this.dynaClass);
191 
192     }
193 
194 
195     /**
196      * Remove any existing value for the specified key on the
197      * specified mapped property.
198      *
199      * @param name Name of the property for which a value is to
200      *  be removed
201      * @param key Key of the value to be removed
202      *
203      * @exception IllegalArgumentException if there is no property
204      *  of the specified name
205      */
206     public void remove(String name, String key) {
207 
208 
209         throw new UnsupportedOperationException
210                 ("WrapDynaBean does not support remove()");
211 
212     }
213 
214 
215     /**
216      * Set the value of a simple property with the specified name.
217      *
218      * @param name Name of the property whose value is to be set
219      * @param value Value to which this property is to be set
220      *
221      * @exception ConversionException if the specified value cannot be
222      *  converted to the type required for this property
223      * @exception IllegalArgumentException if there is no property
224      *  of the specified name
225      * @exception NullPointerException if an attempt is made to set a
226      *  primitive property to null
227      */
228     public void set(String name, Object value) {
229 
230         try {
231             PropertyUtils.setSimpleProperty(instance, name, value);
232         } catch (Throwable t) {
233             throw new IllegalArgumentException
234                     ("Property '" + name + "' has no write method");
235         }
236 
237     }
238 
239 
240     /**
241      * Set the value of an indexed property with the specified name.
242      *
243      * @param name Name of the property whose value is to be set
244      * @param index Index of the property to be set
245      * @param value Value to which this property is to be set
246      *
247      * @exception ConversionException if the specified value cannot be
248      *  converted to the type required for this property
249      * @exception IllegalArgumentException if there is no property
250      *  of the specified name
251      * @exception IllegalArgumentException if the specified property
252      *  exists, but is not indexed
253      * @exception IndexOutOfBoundsException if the specified index
254      *  is outside the range of the underlying property
255      */
256     public void set(String name, int index, Object value) {
257 
258         try {
259             PropertyUtils.setIndexedProperty(instance, name, index, value);
260         } catch (IndexOutOfBoundsException e) {
261             throw e;
262         } catch (Throwable t) {
263             throw new IllegalArgumentException
264                     ("Property '" + name + "' has no indexed write method");
265         }
266 
267     }
268 
269 
270     /**
271      * Set the value of a mapped property with the specified name.
272      *
273      * @param name Name of the property whose value is to be set
274      * @param key Key of the property to be set
275      * @param value Value to which this property is to be set
276      *
277      * @exception ConversionException if the specified value cannot be
278      *  converted to the type required for this property
279      * @exception IllegalArgumentException if there is no property
280      *  of the specified name
281      * @exception IllegalArgumentException if the specified property
282      *  exists, but is not mapped
283      */
284     public void set(String name, String key, Object value) {
285 
286         try {
287             PropertyUtils.setMappedProperty(instance, name, key, value);
288         } catch (Throwable t) {
289             throw new IllegalArgumentException
290                     ("Property '" + name + "' has no mapped write method");
291         }
292 
293     }
294 
295     /** 
296      * Gets the bean instance wrapped by this DynaBean.
297      * For most common use cases, 
298      * this object should already be known 
299      * and this method safely be ignored.
300      * But some creators of frameworks using <code>DynaBean</code>'s may 
301      * find this useful.
302      *
303      * @return the java bean Object wrapped by this <code>DynaBean</code>
304      */
305     public Object getInstance() {
306         return instance;
307     }
308 
309 
310     // ------------------------------------------------------ Protected Methods
311 
312 
313     /**
314      * Return the property descriptor for the specified property name.
315      *
316      * @param name Name of the property for which to retrieve the descriptor
317      *
318      * @exception IllegalArgumentException if this is not a valid property
319      *  name for our DynaClass
320      */
321     protected DynaProperty getDynaProperty(String name) {
322 
323         DynaProperty descriptor = getDynaClass().getDynaProperty(name);
324         if (descriptor == null) {
325             throw new IllegalArgumentException
326                     ("Invalid property name '" + name + "'");
327         }
328         return (descriptor);
329 
330     }
331 
332 
333 }