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