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 */
017package org.apache.commons.beanutils;
018
019import java.beans.IntrospectionException;
020import java.beans.Introspector;
021import java.beans.PropertyDescriptor;
022import java.lang.reflect.Method;
023import java.util.Locale;
024
025import org.apache.commons.logging.Log;
026import org.apache.commons.logging.LogFactory;
027
028/**
029 * <p>
030 * An implementation of the <code>BeanIntrospector</code> interface which can
031 * detect write methods for properties used in fluent API scenario.
032 * </p>
033 * <p>
034 * A <em>fluent API</em> allows setting multiple properties using a single
035 * statement by supporting so-called <em>method chaining</em>: Methods for
036 * setting a property value do not return <strong>void</strong>, but an object which can
037 * be called for setting another property. An example of such a fluent API could
038 * look as follows:
039 * </p>
040 * <pre>
041 * public class FooBuilder {
042 *     public FooBuilder setFooProperty1(String value) {
043 *        ...
044 *        return this;
045 *    }
046 *
047 *     public FooBuilder setFooProperty2(int value) {
048 *        ...
049 *        return this;
050 *    }
051 * }
052 * </pre>
053 * <p>
054 * Per default, <code>PropertyUtils</code> does not detect methods like this
055 * because, having a non-<strong>void</strong> return type, they violate the Java Beans
056 * specification.
057 * </p>
058 * <p>
059 * This class is more tolerant with regards to the return type of a set method.
060 * It basically iterates over all methods of a class and filters them for a
061 * configurable prefix (the default prefix is <code>set</code>). It then
062 * generates corresponding <code>PropertyDescriptor</code> objects for the
063 * methods found which use these methods as write methods.
064 * </p>
065 * <p>
066 * An instance of this class is intended to collaborate with a
067 * {@link DefaultBeanIntrospector} object. So best results are achieved by
068 * adding this instance as custom {@code BeanIntrospector} after the
069 * <code>DefaultBeanIntrospector</code> object. Then default introspection finds
070 * read-only properties because it does not detect the write methods with a
071 * non-<strong>void</strong> return type. {@code FluentPropertyBeanIntrospector}
072 * completes the descriptors for these properties by setting the correct write
073 * method.
074 * </p>
075 *
076 * @since 1.9
077 */
078public class FluentPropertyBeanIntrospector implements BeanIntrospector {
079
080    /** The default prefix for write methods. */
081    public static final String DEFAULT_WRITE_METHOD_PREFIX = "set";
082
083    private static void clearDescriptorsCacheHierarchy(final Class<?> cls) {
084        if (cls != null && cls != Object.class) {
085            Introspector.flushFromCaches(cls);
086            clearDescriptorsCacheHierarchy(cls.getSuperclass());
087        }
088    }
089
090    /** The logger. */
091    private final Log log = LogFactory.getLog(getClass());
092
093    /** The prefix of write methods to search for. */
094    private final String writeMethodPrefix;
095
096    /**
097     *
098     * Creates a new instance of <code>FluentPropertyBeanIntrospector</code> and
099     * sets the default prefix for write methods.
100     */
101    public FluentPropertyBeanIntrospector() {
102        this(DEFAULT_WRITE_METHOD_PREFIX);
103    }
104
105    /**
106     *
107     * Creates a new instance of <code>FluentPropertyBeanIntrospector</code> and
108     * initializes it with the prefix for write methods used by the classes to
109     * be inspected.
110     *
111     * @param writePrefix the prefix for write methods (must not be <strong>null</strong>)
112     * @throws IllegalArgumentException if the prefix is <strong>null</strong>
113     */
114    public FluentPropertyBeanIntrospector(final String writePrefix) {
115        if (writePrefix == null) {
116            throw new IllegalArgumentException(
117                    "Prefix for write methods must not be null!");
118        }
119        writeMethodPrefix = writePrefix;
120    }
121
122    /**
123     * Creates a property descriptor for a fluent API property.
124     *
125     * @param m the set method for the fluent API property
126     * @param propertyName the name of the corresponding property
127     * @return the descriptor
128     * @throws IntrospectionException if an error occurs
129     */
130    private PropertyDescriptor createFluentPropertyDescritor(final Method m,
131            final String propertyName) throws IntrospectionException {
132        return new PropertyDescriptor(propertyName(m), null, m);
133    }
134
135    /**
136     * Returns the prefix for write methods this instance scans for.
137     *
138     * @return the prefix for write methods
139     */
140    public String getWriteMethodPrefix() {
141        return writeMethodPrefix;
142    }
143
144    /**
145     * Performs introspection. This method scans the current class's methods for
146     * property write methods which have not been discovered by default
147     * introspection.
148     *
149     * @param icontext the introspection context
150     * @throws IntrospectionException if an error occurs
151     */
152    @Override
153    public void introspect(final IntrospectionContext icontext)
154            throws IntrospectionException {
155        for (final Method m : icontext.getTargetClass().getMethods()) {
156            if (m.getName().startsWith(getWriteMethodPrefix())) {
157                final String propertyName = propertyName(m);
158                final PropertyDescriptor pd = icontext
159                        .getPropertyDescriptor(propertyName);
160                try {
161                    if (pd == null) {
162                        icontext.addPropertyDescriptor(createFluentPropertyDescritor(
163                                m, propertyName));
164                    } else if (pd.getWriteMethod() == null) {
165                        // We change statically cached PropertyDescriptor, it may affect
166                        // other subclasses of targetClass supertype.
167                        // See BEANUTILS-541 for more details.
168                        clearDescriptorsCacheHierarchy(icontext.getTargetClass().getSuperclass());
169                        pd.setWriteMethod(m);
170                    }
171                } catch (final IntrospectionException e) {
172                    log.info("Error when creating PropertyDescriptor for " + m
173                            + "! Ignoring this property.");
174                    log.debug("Exception is:", e);
175                }
176            }
177        }
178    }
179
180    /**
181     * Derives the name of a property from the given set method.
182     *
183     * @param m the method
184     * @return the corresponding property name
185     */
186    private String propertyName(final Method m) {
187        final String methodName = m.getName().substring(
188                getWriteMethodPrefix().length());
189        return methodName.length() > 1 ? Introspector.decapitalize(methodName) : methodName
190                .toLowerCase(Locale.ROOT);
191    }
192}