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