    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.lang3.reflect;
    018
    019import java.lang.reflect.Constructor;
    020import java.lang.reflect.InvocationTargetException;
    021import java.lang.reflect.Modifier;
    022
    023import org.apache.commons.lang3.ArrayUtils;
    024import org.apache.commons.lang3.ClassUtils;
    025import org.apache.commons.lang3.Validate;
    026
    027/**
    028 * <p> Utility reflection methods focused on constructors, modeled after
    029 * {@link MethodUtils}. </p>
    030 *
    031 * <h3>Known Limitations</h3> <h4>Accessing Public Constructors In A Default
    032 * Access Superclass</h4> <p>There is an issue when invoking {@code public} constructors
    033 * contained in a default access superclass. Reflection correctly locates these
    034 * constructors and assigns them as {@code public}. However, an
    035 * {@link IllegalAccessException} is thrown if the constructor is
    036 * invoked.</p>
    037 *
    038 * <p>{@link ConstructorUtils} contains a workaround for this situation: it
    039 * will attempt to call {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} on this constructor. If this
    040 * call succeeds, then the method can be invoked as normal. This call will only
    041 * succeed when the application has sufficient security privileges. If this call
    042 * fails then a warning will be logged and the method may fail.</p>
    043 *
    044 * @since 2.5
    045 */
    046public class ConstructorUtils {
    047
    048    /**
    049     * <p>ConstructorUtils instances should NOT be constructed in standard
    050     * programming. Instead, the class should be used as
    051     * {@code ConstructorUtils.invokeConstructor(cls, args)}.</p>
    052     *
    053     * <p>This constructor is {@code public} to permit tools that require a JavaBean
    054     * instance to operate.</p>
    055     */
    056    public ConstructorUtils() {
    057        super();
    058    }
    059
    060    /**
    061     * <p>Returns a new instance of the specified class inferring the right constructor
    062     * from the types of the arguments.</p>
    063     *
    064     * <p>This locates and calls a constructor.
    065     * The constructor signature must match the argument types by assignment compatibility.</p>
    066     *
    067     * @param <T> the type to be constructed
    068     * @param cls  the class to be constructed, not {@code null}
    069     * @param args  the array of arguments, {@code null} treated as empty
    070     * @return new instance of {@code cls}, not {@code null}
    071     *
    072     * @throws NullPointerException if {@code cls} is {@code null}
    073     * @throws NoSuchMethodException if a matching constructor cannot be found
    074     * @throws IllegalAccessException if invocation is not permitted by security
    075     * @throws InvocationTargetException if an error occurs on invocation
    076     * @throws InstantiationException if an error occurs on instantiation
    077     * @see #invokeConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[])
    078     */
    079    public static <T> T invokeConstructor(final Class<T> cls, Object... args)
    080            throws NoSuchMethodException, IllegalAccessException, InvocationTargetException,
    081            InstantiationException {
    082        args = ArrayUtils.nullToEmpty(args);
    083        final Class<?> parameterTypes[] = ClassUtils.toClass(args);
    084        return invokeConstructor(cls, args, parameterTypes);
    085    }
    086
    087    /**
    088     * <p>Returns a new instance of the specified class choosing the right constructor
    089     * from the list of parameter types.</p>
    090     *
    091     * <p>This locates and calls a constructor.
    092     * The constructor signature must match the parameter types by assignment compatibility.</p>
    093     *
    094     * @param <T> the type to be constructed
    095     * @param cls  the class to be constructed, not {@code null}
    096     * @param args  the array of arguments, {@code null} treated as empty
    097     * @param parameterTypes  the array of parameter types, {@code null} treated as empty
    098     * @return new instance of {@code cls}, not {@code null}
    099     *
    100     * @throws NullPointerException if {@code cls} is {@code null}
    101     * @throws NoSuchMethodException if a matching constructor cannot be found
    102     * @throws IllegalAccessException if invocation is not permitted by security
    103     * @throws InvocationTargetException if an error occurs on invocation
    104     * @throws InstantiationException if an error occurs on instantiation
    105     * @see Constructor#newInstance
    106     */
    107    public static <T> T invokeConstructor(final Class<T> cls, Object[] args, Class<?>[] parameterTypes)
    108            throws NoSuchMethodException, IllegalAccessException, InvocationTargetException,
    109            InstantiationException {
    110        args = ArrayUtils.nullToEmpty(args);
    111        parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
    112        final Constructor<T> ctor = getMatchingAccessibleConstructor(cls, parameterTypes);
    113        if (ctor == null) {
    114            throw new NoSuchMethodException(
    115                "No such accessible constructor on object: " + cls.getName());
    116        }
    117        if (ctor.isVarArgs()) {
    118            final Class<?>[] methodParameterTypes = ctor.getParameterTypes();
    119            args = MethodUtils.getVarArgs(args, methodParameterTypes);
    120        }
    121        return ctor.newInstance(args);
    122    }
    123
    124    /**
    125     * <p>Returns a new instance of the specified class inferring the right constructor
    126     * from the types of the arguments.</p>
    127     *
    128     * <p>This locates and calls a constructor.
    129     * The constructor signature must match the argument types exactly.</p>
    130     *
    131     * @param <T> the type to be constructed
    132     * @param cls the class to be constructed, not {@code null}
    133     * @param args the array of arguments, {@code null} treated as empty
    134     * @return new instance of {@code cls}, not {@code null}
    135     *
    136     * @throws NullPointerException if {@code cls} is {@code null}
    137     * @throws NoSuchMethodException if a matching constructor cannot be found
    138     * @throws IllegalAccessException if invocation is not permitted by security
    139     * @throws InvocationTargetException if an error occurs on invocation
    140     * @throws InstantiationException if an error occurs on instantiation
    141     * @see #invokeExactConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[])
    142     */
    143    public static <T> T invokeExactConstructor(final Class<T> cls, Object... args)
    144            throws NoSuchMethodException, IllegalAccessException, InvocationTargetException,
    145            InstantiationException {
    146        args = ArrayUtils.nullToEmpty(args);
    147        final Class<?> parameterTypes[] = ClassUtils.toClass(args);
    148        return invokeExactConstructor(cls, args, parameterTypes);
    149    }
    150
    151    /**
    152     * <p>Returns a new instance of the specified class choosing the right constructor
    153     * from the list of parameter types.</p>
    154     *
    155     * <p>This locates and calls a constructor.
    156     * The constructor signature must match the parameter types exactly.</p>
    157     *
    158     * @param <T> the type to be constructed
    159     * @param cls the class to be constructed, not {@code null}
    160     * @param args the array of arguments, {@code null} treated as empty
    161     * @param parameterTypes  the array of parameter types, {@code null} treated as empty
    162     * @return new instance of <code>cls</code>, not {@code null}
    163     *
    164     * @throws NullPointerException if {@code cls} is {@code null}
    165     * @throws NoSuchMethodException if a matching constructor cannot be found
    166     * @throws IllegalAccessException if invocation is not permitted by security
    167     * @throws InvocationTargetException if an error occurs on invocation
    168     * @throws InstantiationException if an error occurs on instantiation
    169     * @see Constructor#newInstance
    170     */
    171    public static <T> T invokeExactConstructor(final Class<T> cls, Object[] args,
    172            Class<?>[] parameterTypes) throws NoSuchMethodException, IllegalAccessException,
    173            InvocationTargetException, InstantiationException {
    174        args = ArrayUtils.nullToEmpty(args);
    175        parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
    176        final Constructor<T> ctor = getAccessibleConstructor(cls, parameterTypes);
    177        if (ctor == null) {
    178            throw new NoSuchMethodException(
    179                "No such accessible constructor on object: "+ cls.getName());
    180        }
    181        return ctor.newInstance(args);
    182    }
    183
    184    //-----------------------------------------------------------------------
    185    /**
    186     * <p>Finds a constructor given a class and signature, checking accessibility.</p>
    187     *
    188     * <p>This finds the constructor and ensures that it is accessible.
    189     * The constructor signature must match the parameter types exactly.</p>
    190     *
    191     * @param <T> the constructor type
    192     * @param cls the class to find a constructor for, not {@code null}
    193     * @param parameterTypes the array of parameter types, {@code null} treated as empty
    194     * @return the constructor, {@code null} if no matching accessible constructor found
    195     * @see Class#getConstructor
    196     * @see #getAccessibleConstructor(java.lang.reflect.Constructor)
    197     * @throws NullPointerException if {@code cls} is {@code null}
    198     */
    199    public static <T> Constructor<T> getAccessibleConstructor(final Class<T> cls,
    200            final Class<?>... parameterTypes) {
    201        Validate.notNull(cls, "class cannot be null");
    202        try {
    203            return getAccessibleConstructor(cls.getConstructor(parameterTypes));
    204        } catch (final NoSuchMethodException e) {
    205            return null;
    206        }
    207    }
    208
    209    /**
    210     * <p>Checks if the specified constructor is accessible.</p>
    211     *
    212     * <p>This simply ensures that the constructor is accessible.</p>
    213     *
    214     * @param <T> the constructor type
    215     * @param ctor  the prototype constructor object, not {@code null}
    216     * @return the constructor, {@code null} if no matching accessible constructor found
    217     * @see java.lang.SecurityManager
    218     * @throws NullPointerException if {@code ctor} is {@code null}
    219     */
    220    public static <T> Constructor<T> getAccessibleConstructor(final Constructor<T> ctor) {
    221        Validate.notNull(ctor, "constructor cannot be null");
    222        return MemberUtils.isAccessible(ctor)
    223                && isAccessible(ctor.getDeclaringClass()) ? ctor : null;
    224    }
    225
    226    /**
    227     * <p>Finds an accessible constructor with compatible parameters.</p>
    228     *
    229     * <p>This checks all the constructor and finds one with compatible parameters
    230     * This requires that every parameter is assignable from the given parameter types.
    231     * This is a more flexible search than the normal exact matching algorithm.</p>
    232     *
    233     * <p>First it checks if there is a constructor matching the exact signature.
    234     * If not then all the constructors of the class are checked to see if their
    235     * signatures are assignment-compatible with the parameter types.
    236     * The first assignment-compatible matching constructor is returned.</p>
    237     *
    238     * @param <T> the constructor type
    239     * @param cls  the class to find a constructor for, not {@code null}
    240     * @param parameterTypes find method with compatible parameters
    241     * @return the constructor, null if no matching accessible constructor found
    242     * @throws NullPointerException if {@code cls} is {@code null}
    243     */
    244    public static <T> Constructor<T> getMatchingAccessibleConstructor(final Class<T> cls,
    245            final Class<?>... parameterTypes) {
    246        Validate.notNull(cls, "class cannot be null");
    247        // see if we can find the constructor directly
    248        // most of the time this works and it's much faster
    249        try {
    250            final Constructor<T> ctor = cls.getConstructor(parameterTypes);
    251            MemberUtils.setAccessibleWorkaround(ctor);
    252            return ctor;
    253        } catch (final NoSuchMethodException e) { // NOPMD - Swallow
    254        }
    255        Constructor<T> result = null;
    256        /*
    257         * (1) Class.getConstructors() is documented to return Constructor<T> so as
    258         * long as the array is not subsequently modified, everything's fine.
    259         */
    260        final Constructor<?>[] ctors = cls.getConstructors();
    261
    262        // return best match:
    263        for (Constructor<?> ctor : ctors) {
    264            // compare parameters
    265            if (MemberUtils.isMatchingConstructor(ctor, parameterTypes)) {
    266                // get accessible version of constructor
    267                ctor = getAccessibleConstructor(ctor);
    268                if (ctor != null) {
    269                    MemberUtils.setAccessibleWorkaround(ctor);
    270                    if (result == null || MemberUtils.compareConstructorFit(ctor, result, parameterTypes) < 0) {
    271                        // temporary variable for annotation, see comment above (1)
    272                        @SuppressWarnings("unchecked")
    273                        final
    274                        Constructor<T> constructor = (Constructor<T>)ctor;
    275                        result = constructor;
    276                    }
    277                }
    278            }
    279        }
    280        return result;
    281    }
    282
    283    /**
    284     * Learn whether the specified class is generally accessible, i.e. is
    285     * declared in an entirely {@code public} manner.
    286     * @param type to check
    287     * @return {@code true} if {@code type} and any enclosing classes are
    288     *         {@code public}.
    289     */
    290    private static boolean isAccessible(final Class<?> type) {
    291        Class<?> cls = type;
    292        while (cls != null) {
    293            if (!Modifier.isPublic(cls.getModifiers())) {
    294                return false;
    295            }
    296            cls = cls.getEnclosingClass();
    297        }
    298        return true;
    299    }
    300
    301}