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
018package org.apache.commons.beanutils;
019
020
021import java.beans.PropertyDescriptor;
022import java.lang.ref.Reference;
023import java.lang.ref.SoftReference;
024import java.util.Collection;
025import java.util.HashMap;
026import java.util.HashSet;
027import java.util.Iterator;
028import java.util.Map;
029import java.util.Set;
030import java.util.WeakHashMap;
031
032
033/**
034 * <p>Implementation of <code>DynaClass</code> for DynaBeans that wrap
035 * standard JavaBean instances.</p>
036 *
037 * <p>
038 * It is suggested that this class should not usually need to be used directly
039 * to create new <code>WrapDynaBean</code> instances.
040 * It's usually better to call the <code>WrapDynaBean</code> constructor directly.
041 * For example:</p>
042 * <code><pre>
043 *   Object javaBean = ...;
044 *   DynaBean wrapper = new WrapDynaBean(javaBean);
045 * </pre></code>
046 * <p>
047 *
048 * @version $Id: WrapDynaClass.html 893732 2014-01-11 19:35:15Z oheger $
049 */
050
051public class WrapDynaClass implements DynaClass {
052
053
054    // ----------------------------------------------------------- Constructors
055
056
057    /**
058     * Construct a new WrapDynaClass for the specified JavaBean class.  This
059     * constructor is private; WrapDynaClass instances will be created as
060     * needed via calls to the <code>createDynaClass(Class)</code> method.
061     *
062     * @param beanClass JavaBean class to be introspected around
063     * @param propUtils the {@code PropertyUtilsBean} associated with this class
064     */
065    private WrapDynaClass(Class<?> beanClass, PropertyUtilsBean propUtils) {
066
067        this.beanClassRef = new SoftReference<Class<?>>(beanClass);
068        this.beanClassName = beanClass.getName();
069        propertyUtilsBean = propUtils;
070        introspect();
071
072    }
073
074
075    // ----------------------------------------------------- Instance Variables
076
077    /**
078     * Name of the JavaBean class represented by this WrapDynaClass.
079     */
080    private String beanClassName = null;
081
082    /**
083     * Reference to the JavaBean class represented by this WrapDynaClass.
084     */
085    private Reference<Class<?>> beanClassRef = null;
086
087    /** Stores the associated {@code PropertyUtilsBean} instance. */
088    private final PropertyUtilsBean propertyUtilsBean;
089
090    /**
091     * The JavaBean <code>Class</code> which is represented by this
092     * <code>WrapDynaClass</code>.
093     *
094     * @deprecated No longer initialized, use getBeanClass() method instead
095     */
096    @Deprecated
097    protected Class<?> beanClass = null;
098
099
100    /**
101     * The set of PropertyDescriptors for this bean class.
102     */
103    protected PropertyDescriptor[] descriptors = null;
104
105
106    /**
107     * The set of PropertyDescriptors for this bean class, keyed by the
108     * property name.  Individual descriptor instances will be the same
109     * instances as those in the <code>descriptors</code> list.
110     */
111    protected HashMap<String, PropertyDescriptor> descriptorsMap = new HashMap<String, PropertyDescriptor>();
112
113
114    /**
115     * The set of dynamic properties that are part of this DynaClass.
116     */
117    protected DynaProperty[] properties = null;
118
119
120    /**
121     * The set of dynamic properties that are part of this DynaClass,
122     * keyed by the property name.  Individual descriptor instances will
123     * be the same instances as those in the <code>properties</code> list.
124     */
125    protected HashMap<String, DynaProperty> propertiesMap = new HashMap<String, DynaProperty>();
126
127
128    // ------------------------------------------------------- Static Variables
129
130
131    private static final ContextClassLoaderLocal<Map<CacheKey, WrapDynaClass>> CLASSLOADER_CACHE =
132        new ContextClassLoaderLocal<Map<CacheKey, WrapDynaClass>>() {
133            @Override
134            protected Map<CacheKey, WrapDynaClass> initialValue() {
135                return new WeakHashMap<CacheKey, WrapDynaClass>();
136        }
137    };
138
139    /**
140     * Get the wrap dyna classes cache. Note: This method only exists to
141     * satisfy the deprecated {@code dynaClasses} hash map.
142     */
143    @SuppressWarnings("unchecked")
144    private static Map<Object, Object> getDynaClassesMap() {
145        @SuppressWarnings("rawtypes")
146        Map cache = CLASSLOADER_CACHE.get();
147        return cache;
148    }
149
150    /**
151     * Returns the cache for the already created class instances. For each
152     * combination of bean class and {@code PropertyUtilsBean} instance an
153     * entry is created in the cache.
154     * @return the cache for already created {@code WrapDynaClass} instances
155     */
156    private static Map<CacheKey, WrapDynaClass> getClassesCache() {
157        return CLASSLOADER_CACHE.get();
158    }
159
160    /**
161     * The set of <code>WrapDynaClass</code> instances that have ever been
162     * created, keyed by the underlying bean Class. The keys to this map
163     * are Class objects, and the values are corresponding WrapDynaClass
164     * objects.
165     * <p>
166     * This static variable is safe even when this code is deployed via a
167     * shared classloader because it is keyed via a Class object. The same
168     * class loaded via two different classloaders will result in different
169     * entries in this map.
170     * <p>
171     * Note, however, that this HashMap can result in a memory leak. When
172     * this class is in a shared classloader it will retain references to
173     * classes loaded via a webapp classloader even after the webapp has been
174     * undeployed. That will prevent the entire classloader and all the classes
175     * it refers to and all their static members from being freed.
176     *
177     ************* !!!!!!!!!!!! PLEASE NOTE !!!!!!!!!!!! *************
178     *
179     * THE FOLLOWING IS A NASTY HACK TO SO THAT BEANUTILS REMAINS BINARY
180     *              COMPATIBLE WITH PREVIOUS RELEASES.
181     *
182     * There are two issues here:
183     *
184     * 1) Memory Issues: The static HashMap caused memory problems (See BEANUTILS-59)
185     *    to resolve this it has been moved into a ContextClassLoaderLocal instance
186     *    (named CLASSLOADER_CACHE above) which holds one copy per
187     *    ClassLoader in a WeakHashMap.
188     *
189     * 2) Binary Compatibility: As the "dynaClasses" static HashMap is "protected"
190     *    removing it breaks BeanUtils binary compatibility with previous versions.
191     *    To resolve this all the methods have been overriden to delegate to the
192     *    Map for the ClassLoader in the ContextClassLoaderLocal.
193     *
194     * @deprecated The dynaClasses Map will be removed in a subsequent release
195     */
196    @Deprecated
197    protected static HashMap<Object, Object> dynaClasses = new HashMap<Object, Object>() {
198        @Override
199        public void clear() {
200            getDynaClassesMap().clear();
201        }
202        @Override
203        public boolean containsKey(Object key) {
204            return getDynaClassesMap().containsKey(key);
205        }
206        @Override
207        public boolean containsValue(Object value) {
208            return getDynaClassesMap().containsValue(value);
209        }
210        @Override
211        public Set<Map.Entry<Object, Object>> entrySet() {
212            return getDynaClassesMap().entrySet();
213        }
214        @Override
215        public boolean equals(Object o) {
216            return getDynaClassesMap().equals(o);
217        }
218        @Override
219        public Object get(Object key) {
220            return getDynaClassesMap().get(key);
221        }
222        @Override
223        public int hashCode() {
224            return getDynaClassesMap().hashCode();
225        }
226        @Override
227        public boolean isEmpty() {
228            return getDynaClassesMap().isEmpty();
229        }
230        @Override
231        public Set<Object> keySet() {
232            // extract the classes from the key to stay backwards compatible
233            Set<Object> result = new HashSet<Object>();
234            for (CacheKey k : getClassesCache().keySet()) {
235                result.add(k.beanClass);
236            }
237            return result;
238        }
239        @Override
240        public Object put(Object key, Object value) {
241            return getClassesCache().put(
242                    new CacheKey((Class<?>) key, PropertyUtilsBean.getInstance()),
243                    (WrapDynaClass) value);
244        }
245        @Override
246        public void putAll(Map<? extends Object, ? extends Object> m) {
247            for (Map.Entry<? extends Object, ? extends Object> e : m.entrySet()) {
248                put(e.getKey(), e.getValue());
249            }
250        }
251        @Override
252        public Object remove(Object key) {
253            return getDynaClassesMap().remove(key);
254        }
255        @Override
256        public int size() {
257            return getDynaClassesMap().size();
258        }
259        @Override
260        public Collection<Object> values() {
261            return getDynaClassesMap().values();
262        }
263    };
264
265
266    // ------------------------------------------------------ DynaClass Methods
267
268    /**
269     * Return the class of the underlying wrapped bean.
270     *
271     * @return the class of the underlying wrapped bean
272     * @since 1.8.0
273     */
274    protected Class<?> getBeanClass() {
275        return beanClassRef.get();
276    }
277
278    /**
279     * Return the name of this DynaClass (analogous to the
280     * <code>getName()</code> method of <code>java.lang.Class</code), which
281     * allows the same <code>DynaClass</code> implementation class to support
282     * different dynamic classes, with different sets of properties.
283     *
284     * @return the name of the DynaClass
285     */
286    public String getName() {
287
288        return beanClassName;
289
290    }
291
292
293    /**
294     * Return a property descriptor for the specified property, if it exists;
295     * otherwise, return <code>null</code>.
296     *
297     * @param name Name of the dynamic property for which a descriptor
298     *  is requested
299     * @return The descriptor for the specified property
300     *
301     * @exception IllegalArgumentException if no property name is specified
302     */
303    public DynaProperty getDynaProperty(String name) {
304
305        if (name == null) {
306            throw new IllegalArgumentException
307                    ("No property name specified");
308        }
309        return (propertiesMap.get(name));
310
311    }
312
313
314    /**
315     * <p>Return an array of <code>ProperyDescriptors</code> for the properties
316     * currently defined in this DynaClass.  If no properties are defined, a
317     * zero-length array will be returned.</p>
318     *
319     * <p><strong>FIXME</strong> - Should we really be implementing
320     * <code>getBeanInfo()</code> instead, which returns property descriptors
321     * and a bunch of other stuff?</p>
322     *
323     * @return the set of properties for this DynaClass
324     */
325    public DynaProperty[] getDynaProperties() {
326
327        return (properties);
328
329    }
330
331
332    /**
333     * <p>Instantiates a new standard JavaBean instance associated with
334     * this DynaClass and return it wrapped in a new WrapDynaBean
335     * instance. <strong>NOTE</strong> the JavaBean should have a
336     * no argument constructor.</p>
337     *
338     * <strong>NOTE</strong> - Most common use cases should not need to use
339     * this method. It is usually better to create new
340     * <code>WrapDynaBean</code> instances by calling its constructor.
341     * For example:</p>
342     * <code><pre>
343     *   Object javaBean = ...;
344     *   DynaBean wrapper = new WrapDynaBean(javaBean);
345     * </pre></code>
346     * <p>
347     * (This method is needed for some kinds of <code>DynaBean</code> framework.)
348     * </p>
349     *
350     * @return A new <code>DynaBean</code> instance
351     * @exception IllegalAccessException if the Class or the appropriate
352     *  constructor is not accessible
353     * @exception InstantiationException if this Class represents an abstract
354     *  class, an array class, a primitive type, or void; or if instantiation
355     *  fails for some other reason
356     */
357    public DynaBean newInstance()
358            throws IllegalAccessException, InstantiationException {
359
360        return new WrapDynaBean(getBeanClass().newInstance());
361
362    }
363
364
365    // --------------------------------------------------------- Public Methods
366
367
368    /**
369     * Return the PropertyDescriptor for the specified property name, if any;
370     * otherwise return <code>null</code>.
371     *
372     * @param name Name of the property to be retrieved
373     * @return The descriptor for the specified property
374     */
375    public PropertyDescriptor getPropertyDescriptor(String name) {
376
377        return (descriptorsMap.get(name));
378
379    }
380
381
382    // --------------------------------------------------------- Static Methods
383
384
385    /**
386     * Clear our cache of WrapDynaClass instances.
387     */
388    public static void clear() {
389
390        getClassesCache().clear();
391
392    }
393
394
395    /**
396     * Create (if necessary) and return a new <code>WrapDynaClass</code>
397     * instance for the specified bean class.
398     *
399     * @param beanClass Bean class for which a WrapDynaClass is requested
400     * @return A new <i>Wrap</i> {@link DynaClass}
401     */
402    public static WrapDynaClass createDynaClass(Class<?> beanClass) {
403
404        return createDynaClass(beanClass, null);
405
406    }
407
408
409    /**
410     * Create (if necessary) and return a new {@code WrapDynaClass} instance
411     * for the specified bean class using the given {@code PropertyUtilsBean}
412     * instance for introspection. Using this method a specially configured
413     * {@code PropertyUtilsBean} instance can be hooked into the introspection
414     * mechanism of the managed bean. The argument is optional; if no
415     * {@code PropertyUtilsBean} object is provided, the default instance is used.
416     * @param beanClass Bean class for which a WrapDynaClass is requested
417     * @param pu the optional {@code PropertyUtilsBean} to be used for introspection
418     * @return A new <i>Wrap</i> {@link DynaClass}
419     * @since 1.9
420     */
421    public static WrapDynaClass createDynaClass(Class<?> beanClass, PropertyUtilsBean pu) {
422
423        PropertyUtilsBean propUtils = (pu != null) ? pu : PropertyUtilsBean.getInstance();
424        CacheKey key = new CacheKey(beanClass, propUtils);
425        WrapDynaClass dynaClass = getClassesCache().get(key);
426        if (dynaClass == null) {
427            dynaClass = new WrapDynaClass(beanClass, propUtils);
428            getClassesCache().put(key, dynaClass);
429        }
430        return (dynaClass);
431
432    }
433
434
435    // ------------------------------------------------------ Protected Methods
436
437    /**
438     * Returns the {@code PropertyUtilsBean} instance associated with this class. This
439     * bean is used for introspection.
440     *
441     * @return the associated {@code PropertyUtilsBean} instance
442     * @since 1.9
443     */
444    protected PropertyUtilsBean getPropertyUtilsBean() {
445        return propertyUtilsBean;
446    }
447
448    /**
449     * Introspect our bean class to identify the supported properties.
450     */
451    protected void introspect() {
452
453        // Look up the property descriptors for this bean class
454        Class<?> beanClass = getBeanClass();
455        PropertyDescriptor[] regulars =
456                getPropertyUtilsBean().getPropertyDescriptors(beanClass);
457        if (regulars == null) {
458            regulars = new PropertyDescriptor[0];
459        }
460        Map<?, ?> mappeds =
461                PropertyUtils.getMappedPropertyDescriptors(beanClass);
462        if (mappeds == null) {
463            mappeds = new HashMap<Object, Object>();
464        }
465
466        // Construct corresponding DynaProperty information
467        properties = new DynaProperty[regulars.length + mappeds.size()];
468        for (int i = 0; i < regulars.length; i++) {
469            descriptorsMap.put(regulars[i].getName(),
470                    regulars[i]);
471            properties[i] =
472                    new DynaProperty(regulars[i].getName(),
473                            regulars[i].getPropertyType());
474            propertiesMap.put(properties[i].getName(),
475                    properties[i]);
476        }
477        int j = regulars.length;
478        Iterator<?> names = mappeds.keySet().iterator();
479        while (names.hasNext()) {
480            String name = (String) names.next();
481            PropertyDescriptor descriptor =
482                    (PropertyDescriptor) mappeds.get(name);
483            properties[j] =
484                    new DynaProperty(descriptor.getName(),
485                            Map.class);
486            propertiesMap.put(properties[j].getName(),
487                    properties[j]);
488            j++;
489        }
490
491    }
492
493    /**
494     * A class representing the combined key for the cache of {@code WrapDynaClass}
495     * instances. A single key consists of a bean class and an instance of
496     * {@code PropertyUtilsBean}. Instances are immutable.
497     */
498    private static class CacheKey {
499        /** The bean class. */
500        private final Class<?> beanClass;
501
502        /** The instance of PropertyUtilsBean. */
503        private final PropertyUtilsBean propUtils;
504
505        /**
506         * Creates a new instance of {@code CacheKey}.
507         *
508         * @param beanCls the bean class
509         * @param pu the instance of {@code PropertyUtilsBean}
510         */
511        public CacheKey(Class<?> beanCls, PropertyUtilsBean pu) {
512            beanClass = beanCls;
513            propUtils = pu;
514        }
515
516        @Override
517        public int hashCode() {
518            int factor = 31;
519            int result = 17;
520            result = factor * beanClass.hashCode() + result;
521            result = factor * propUtils.hashCode() + result;
522            return result;
523        }
524
525        @Override
526        public boolean equals(Object obj) {
527            if (this == obj) {
528                return true;
529            }
530            if (!(obj instanceof CacheKey)) {
531                return false;
532            }
533
534            CacheKey c = (CacheKey) obj;
535            return beanClass.equals(c.beanClass) && propUtils.equals(c.propUtils);
536        }
537    }
538}