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 *      https://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.Array;
020import java.lang.reflect.GenericArrayType;
021import java.lang.reflect.GenericDeclaration;
022import java.lang.reflect.ParameterizedType;
023import java.lang.reflect.Type;
024import java.lang.reflect.TypeVariable;
025import java.lang.reflect.WildcardType;
026import java.util.Arrays;
027import java.util.Collection;
028import java.util.Collections;
029import java.util.HashMap;
030import java.util.HashSet;
031import java.util.List;
032import java.util.Map;
033import java.util.Objects;
034import java.util.Set;
035import java.util.TreeSet;
036
037import org.apache.commons.lang3.AppendableJoiner;
038import org.apache.commons.lang3.ArrayUtils;
039import org.apache.commons.lang3.ClassUtils;
040import org.apache.commons.lang3.ObjectUtils;
041import org.apache.commons.lang3.Validate;
042import org.apache.commons.lang3.builder.Builder;
043
044/**
045 * Utility methods focusing on type inspection, particularly with regard to generics.
046 *
047 * @since 3.0
048 */
049public class TypeUtils {
050
051    /**
052     * GenericArrayType implementation class.
053     */
054    private static final class GenericArrayTypeImpl implements GenericArrayType {
055        private final Type componentType;
056
057        /**
058         * Constructor
059         *
060         * @param componentType of this array type
061         */
062        private GenericArrayTypeImpl(final Type componentType) {
063            this.componentType = componentType;
064        }
065
066        /**
067         * {@inheritDoc}
068         */
069        @Override
070        public boolean equals(final Object obj) {
071            return obj == this || obj instanceof GenericArrayType && TypeUtils.equals(this, (GenericArrayType) obj);
072        }
073
074        /**
075         * {@inheritDoc}
076         */
077        @Override
078        public Type getGenericComponentType() {
079            return componentType;
080        }
081
082        /**
083         * {@inheritDoc}
084         */
085        @Override
086        public int hashCode() {
087            int result = 67 << 4;
088            result |= componentType.hashCode();
089            return result;
090        }
091
092        /**
093         * {@inheritDoc}
094         */
095        @Override
096        public String toString() {
097            return TypeUtils.toString(this);
098        }
099    }
100
101    /**
102     * ParameterizedType implementation class.
103     */
104    private static final class ParameterizedTypeImpl implements ParameterizedType {
105        private final Class<?> raw;
106        private final Type useOwner;
107        private final Type[] typeArguments;
108
109        /**
110         * Constructor
111         *
112         * @param rawClass      type
113         * @param useOwner      owner type to use, if any
114         * @param typeArguments formal type arguments
115         */
116        private ParameterizedTypeImpl(final Class<?> rawClass, final Type useOwner, final Type[] typeArguments) {
117            this.raw = rawClass;
118            this.useOwner = useOwner;
119            this.typeArguments = Arrays.copyOf(typeArguments, typeArguments.length, Type[].class);
120        }
121
122        /**
123         * {@inheritDoc}
124         */
125        @Override
126        public boolean equals(final Object obj) {
127            return obj == this || obj instanceof ParameterizedType && TypeUtils.equals(this, (ParameterizedType) obj);
128        }
129
130        /**
131         * {@inheritDoc}
132         */
133        @Override
134        public Type[] getActualTypeArguments() {
135            return typeArguments.clone();
136        }
137
138        /**
139         * {@inheritDoc}
140         */
141        @Override
142        public Type getOwnerType() {
143            return useOwner;
144        }
145
146        /**
147         * {@inheritDoc}
148         */
149        @Override
150        public Type getRawType() {
151            return raw;
152        }
153
154        /**
155         * {@inheritDoc}
156         */
157        @Override
158        public int hashCode() {
159            int result = 71 << 4;
160            result |= raw.hashCode();
161            result <<= 4;
162            result |= Objects.hashCode(useOwner);
163            result <<= 8;
164            result |= Arrays.hashCode(typeArguments);
165            return result;
166        }
167
168        /**
169         * {@inheritDoc}
170         */
171        @Override
172        public String toString() {
173            return TypeUtils.toString(this);
174        }
175    }
176
177    /**
178     * {@link WildcardType} builder.
179     *
180     * @since 3.2
181     */
182    public static class WildcardTypeBuilder implements Builder<WildcardType> {
183        private Type[] upperBounds;
184
185        private Type[] lowerBounds;
186
187        /**
188         * Constructor
189         */
190        private WildcardTypeBuilder() {
191        }
192
193        /**
194         * {@inheritDoc}
195         */
196        @Override
197        public WildcardType build() {
198            return new WildcardTypeImpl(upperBounds, lowerBounds);
199        }
200
201        /**
202         * Specify lower bounds of the wildcard type to build.
203         *
204         * @param bounds to set
205         * @return {@code this}
206         */
207        public WildcardTypeBuilder withLowerBounds(final Type... bounds) {
208            this.lowerBounds = bounds;
209            return this;
210        }
211
212        /**
213         * Specify upper bounds of the wildcard type to build.
214         *
215         * @param bounds to set
216         * @return {@code this}
217         */
218        public WildcardTypeBuilder withUpperBounds(final Type... bounds) {
219            this.upperBounds = bounds;
220            return this;
221        }
222    }
223
224    /**
225     * WildcardType implementation class.
226     */
227    private static final class WildcardTypeImpl implements WildcardType {
228        private final Type[] upperBounds;
229        private final Type[] lowerBounds;
230
231        /**
232         * Constructor
233         *
234         * @param upperBounds of this type
235         * @param lowerBounds of this type
236         */
237        private WildcardTypeImpl(final Type[] upperBounds, final Type[] lowerBounds) {
238            this.upperBounds = ObjectUtils.getIfNull(upperBounds, ArrayUtils.EMPTY_TYPE_ARRAY);
239            this.lowerBounds = ObjectUtils.getIfNull(lowerBounds, ArrayUtils.EMPTY_TYPE_ARRAY);
240        }
241
242        /**
243         * {@inheritDoc}
244         */
245        @Override
246        public boolean equals(final Object obj) {
247            return obj == this || obj instanceof WildcardType && TypeUtils.equals(this, (WildcardType) obj);
248        }
249
250        /**
251         * {@inheritDoc}
252         */
253        @Override
254        public Type[] getLowerBounds() {
255            return lowerBounds.clone();
256        }
257
258        /**
259         * {@inheritDoc}
260         */
261        @Override
262        public Type[] getUpperBounds() {
263            return upperBounds.clone();
264        }
265
266        /**
267         * {@inheritDoc}
268         */
269        @Override
270        public int hashCode() {
271            int result = 73 << 8;
272            result |= Arrays.hashCode(upperBounds);
273            result <<= 8;
274            result |= Arrays.hashCode(lowerBounds);
275            return result;
276        }
277
278        /**
279         * {@inheritDoc}
280         */
281        @Override
282        public String toString() {
283            return TypeUtils.toString(this);
284        }
285    }
286
287    /**
288     * Ampersand sign joiner.
289     */
290    // @formatter:off
291    private static final AppendableJoiner<Type> AMP_JOINER = AppendableJoiner.<Type>builder()
292            .setDelimiter(" & ")
293            .setElementAppender((a, e) -> a.append(toString(e)))
294            .get();
295    // @formatter:on
296
297    /**
298     * Method classToString joiner.
299     */
300    // @formatter:off
301    private static final AppendableJoiner<TypeVariable<Class<?>>> CTJ_JOINER = AppendableJoiner.<TypeVariable<Class<?>>>builder()
302        .setDelimiter(", ")
303        .setElementAppender((a, e) -> a.append(anyToString(e)))
304        .get();
305    // @formatter:on
306
307    /**
308     * Greater than and lesser than sign joiner.
309     */
310    // @formatter:off
311    private static final AppendableJoiner<Object> GT_JOINER = AppendableJoiner.builder()
312            .setPrefix("<")
313            .setSuffix(">")
314            .setDelimiter(", ")
315            .setElementAppender((a, e) -> a.append(anyToString(e)))
316            .get();
317    // @formatter:on
318
319    /**
320     * A wildcard instance matching {@code ?}.
321     *
322     * @since 3.2
323     */
324    public static final WildcardType WILDCARD_ALL = wildcardType().withUpperBounds(Object.class).build();
325
326    private static <T> String anyToString(final T object) {
327        return object instanceof Type ? toString((Type) object) : object.toString();
328    }
329
330    private static void appendRecursiveTypes(final StringBuilder builder, final int[] recursiveTypeIndexes, final Type[] argumentTypes) {
331        for (int i = 0; i < recursiveTypeIndexes.length; i++) {
332            // toString() or SO
333            GT_JOINER.join(builder, argumentTypes[i].toString());
334        }
335        final Type[] argumentsFiltered = ArrayUtils.removeAll(argumentTypes, recursiveTypeIndexes);
336        if (argumentsFiltered.length > 0) {
337            GT_JOINER.join(builder, (Object[]) argumentsFiltered);
338        }
339    }
340
341    /**
342     * Formats a {@link Class} as a {@link String}.
343     *
344     * @param cls {@link Class} to format
345     * @return String
346     */
347    private static <T> String classToString(final Class<T> cls) {
348        if (cls.isArray()) {
349            return toString(cls.getComponentType()) + "[]";
350        }
351        if (isCyclical(cls)) {
352            return cls.getSimpleName() + "(cycle)";
353        }
354        final StringBuilder buf = new StringBuilder();
355        if (cls.getEnclosingClass() != null) {
356            buf.append(classToString(cls.getEnclosingClass())).append('.').append(cls.getSimpleName());
357        } else {
358            buf.append(cls.getName());
359        }
360        if (cls.getTypeParameters().length > 0) {
361            CTJ_JOINER.join(buf, (TypeVariable[]) cls.getTypeParameters());
362        }
363        return buf.toString();
364    }
365
366    /**
367     * Tests, recursively, whether any of the type parameters associated with {@code type} are bound to variables.
368     *
369     * @param type the type to check for type variables
370     * @return boolean
371     * @since 3.2
372     */
373    public static boolean containsTypeVariables(final Type type) {
374        if (type instanceof TypeVariable<?>) {
375            return true;
376        }
377        if (type instanceof Class<?>) {
378            return ((Class<?>) type).getTypeParameters().length > 0;
379        }
380        if (type instanceof ParameterizedType) {
381            for (final Type arg : ((ParameterizedType) type).getActualTypeArguments()) {
382                if (containsTypeVariables(arg)) {
383                    return true;
384                }
385            }
386            return false;
387        }
388        if (type instanceof WildcardType) {
389            final WildcardType wild = (WildcardType) type;
390            return containsTypeVariables(getImplicitLowerBounds(wild)[0]) || containsTypeVariables(getImplicitUpperBounds(wild)[0]);
391        }
392        if (type instanceof GenericArrayType) {
393            return containsTypeVariables(((GenericArrayType) type).getGenericComponentType());
394        }
395        return false;
396    }
397
398    private static boolean containsVariableTypeSameParametrizedTypeBound(final TypeVariable<?> typeVariable, final ParameterizedType parameterizedType) {
399        return ArrayUtils.contains(typeVariable.getBounds(), parameterizedType);
400    }
401
402    /**
403     * Tries to determine the type arguments of a class/interface based on a super parameterized type's type arguments. This method is the inverse of
404     * {@link #getTypeArguments(Type, Class)} which gets a class/interface's type arguments based on a subtype. It is far more limited in determining the type
405     * arguments for the subject class's type variables in that it can only determine those parameters that map from the subject {@link Class} object to the
406     * supertype.
407     *
408     * <p>
409     * Example: {@link java.util.TreeSet TreeSet} sets its parameter as the parameter for {@link java.util.NavigableSet NavigableSet}, which in turn sets the
410     * parameter of {@link java.util.SortedSet}, which in turn sets the parameter of {@link Set}, which in turn sets the parameter of
411     * {@link java.util.Collection}, which in turn sets the parameter of {@link Iterable}. Since {@link TreeSet}'s parameter maps (indirectly) to
412     * {@link Iterable}'s parameter, it will be able to determine that based on the super type {@code Iterable<? extends
413     * Map<Integer, ? extends Collection<?>>>}, the parameter of {@link TreeSet} is {@code ? extends Map<Integer, ? extends
414     * Collection<?>>}.
415     * </p>
416     *
417     * @param cls                    the class whose type parameters are to be determined, not {@code null}
418     * @param superParameterizedType the super type from which {@code cls}'s type arguments are to be determined, not {@code null}
419     * @return a {@link Map} of the type assignments that could be determined for the type variables in each type in the inheritance hierarchy from {@code type}
420     *         to {@code toClass} inclusive.
421     * @throws NullPointerException if either {@code cls} or {@code superParameterizedType} is {@code null}
422     */
423    public static Map<TypeVariable<?>, Type> determineTypeArguments(final Class<?> cls, final ParameterizedType superParameterizedType) {
424        Objects.requireNonNull(cls, "cls");
425        Objects.requireNonNull(superParameterizedType, "superParameterizedType");
426        final Class<?> superClass = getRawType(superParameterizedType);
427        // compatibility check
428        if (!isAssignable(cls, superClass)) {
429            return null;
430        }
431        if (cls.equals(superClass)) {
432            return getTypeArguments(superParameterizedType, superClass, null);
433        }
434        // get the next class in the inheritance hierarchy
435        final Type midType = getClosestParentType(cls, superClass);
436        // can only be a class or a parameterized type
437        if (midType instanceof Class<?>) {
438            return determineTypeArguments((Class<?>) midType, superParameterizedType);
439        }
440        final ParameterizedType midParameterizedType = (ParameterizedType) midType;
441        final Class<?> midClass = getRawType(midParameterizedType);
442        // get the type variables of the mid class that map to the type
443        // arguments of the super class
444        final Map<TypeVariable<?>, Type> typeVarAssigns = determineTypeArguments(midClass, superParameterizedType);
445        // map the arguments of the mid type to the class type variables
446        mapTypeVariablesToArguments(cls, midParameterizedType, typeVarAssigns);
447        return typeVarAssigns;
448    }
449
450    /**
451     * Tests whether {@code t} equals {@code a}.
452     *
453     * @param genericArrayType LHS
454     * @param type             RHS
455     * @return boolean
456     */
457    private static boolean equals(final GenericArrayType genericArrayType, final Type type) {
458        return type instanceof GenericArrayType && equals(genericArrayType.getGenericComponentType(), ((GenericArrayType) type).getGenericComponentType());
459    }
460
461    /**
462     * Tests whether {@code t} equals {@code p}.
463     *
464     * @param parameterizedType LHS
465     * @param type              RHS
466     * @return boolean
467     */
468    private static boolean equals(final ParameterizedType parameterizedType, final Type type) {
469        if (type instanceof ParameterizedType) {
470            final ParameterizedType other = (ParameterizedType) type;
471            if (equals(parameterizedType.getRawType(), other.getRawType()) && equals(parameterizedType.getOwnerType(), other.getOwnerType())) {
472                return equals(parameterizedType.getActualTypeArguments(), other.getActualTypeArguments());
473            }
474        }
475        return false;
476    }
477
478    /**
479     * Tests equality of types.
480     *
481     * @param type1 the first type
482     * @param type2 the second type
483     * @return boolean
484     * @since 3.2
485     */
486    public static boolean equals(final Type type1, final Type type2) {
487        if (Objects.equals(type1, type2)) {
488            return true;
489        }
490        if (type1 instanceof ParameterizedType) {
491            return equals((ParameterizedType) type1, type2);
492        }
493        if (type1 instanceof GenericArrayType) {
494            return equals((GenericArrayType) type1, type2);
495        }
496        if (type1 instanceof WildcardType) {
497            return equals((WildcardType) type1, type2);
498        }
499        return false;
500    }
501
502    /**
503     * Tests whether {@code t1} equals {@code t2}.
504     *
505     * @param type1 LHS
506     * @param type2 RHS
507     * @return boolean
508     */
509    private static boolean equals(final Type[] type1, final Type[] type2) {
510        if (type1.length == type2.length) {
511            for (int i = 0; i < type1.length; i++) {
512                if (!equals(type1[i], type2[i])) {
513                    return false;
514                }
515            }
516            return true;
517        }
518        return false;
519    }
520
521    /**
522     * Tests whether {@code t} equals {@code w}.
523     *
524     * @param wildcardType LHS
525     * @param type         RHS
526     * @return boolean
527     */
528    private static boolean equals(final WildcardType wildcardType, final Type type) {
529        if (type instanceof WildcardType) {
530            final WildcardType other = (WildcardType) type;
531            return equals(getImplicitLowerBounds(wildcardType), getImplicitLowerBounds(other))
532                    && equals(getImplicitUpperBounds(wildcardType), getImplicitUpperBounds(other));
533        }
534        return false;
535    }
536
537    /**
538     * Helper method to establish the formal parameters for a parameterized type.
539     *
540     * @param mappings  map containing the assignments
541     * @param variables expected map keys
542     * @return array of map values corresponding to specified keys
543     */
544    private static Type[] extractTypeArgumentsFrom(final Map<TypeVariable<?>, Type> mappings, final TypeVariable<?>[] variables) {
545        final Type[] result = new Type[variables.length];
546        int index = 0;
547        for (final TypeVariable<?> var : variables) {
548            Validate.isTrue(mappings.containsKey(var), () -> String.format("missing argument mapping for %s", toString(var)));
549            result[index++] = mappings.get(var);
550        }
551        return result;
552    }
553
554    private static int[] findRecursiveTypes(final ParameterizedType parameterizedType) {
555        final Type[] filteredArgumentTypes = Arrays.copyOf(parameterizedType.getActualTypeArguments(), parameterizedType.getActualTypeArguments().length);
556        int[] indexesToRemove = {};
557        for (int i = 0; i < filteredArgumentTypes.length; i++) {
558            if (filteredArgumentTypes[i] instanceof TypeVariable<?>
559                    && containsVariableTypeSameParametrizedTypeBound((TypeVariable<?>) filteredArgumentTypes[i], parameterizedType)) {
560                indexesToRemove = ArrayUtils.add(indexesToRemove, i);
561            }
562        }
563        return indexesToRemove;
564    }
565
566    /**
567     * Creates a generic array type instance.
568     *
569     * @param componentType the type of the elements of the array. For example the component type of {@code boolean[]} is {@code boolean}
570     * @return {@link GenericArrayType}
571     * @since 3.2
572     */
573    public static GenericArrayType genericArrayType(final Type componentType) {
574        return new GenericArrayTypeImpl(Objects.requireNonNull(componentType, "componentType"));
575    }
576
577    /**
578     * Formats a {@link GenericArrayType} as a {@link String}.
579     *
580     * @param genericArrayType {@link GenericArrayType} to format
581     * @return String
582     */
583    private static String genericArrayTypeToString(final GenericArrayType genericArrayType) {
584        return String.format("%s[]", toString(genericArrayType.getGenericComponentType()));
585    }
586
587    /**
588     * Gets the array component type of {@code type}.
589     *
590     * @param type the type to be checked
591     * @return component type or null if type is not an array type
592     */
593    public static Type getArrayComponentType(final Type type) {
594        if (type instanceof Class<?>) {
595            final Class<?> cls = (Class<?>) type;
596            return cls.isArray() ? cls.getComponentType() : null;
597        }
598        if (type instanceof GenericArrayType) {
599            return ((GenericArrayType) type).getGenericComponentType();
600        }
601        return null;
602    }
603
604    /**
605     * Gets the closest parent type to the super class specified by {@code superClass}.
606     *
607     * @param cls        the class in question
608     * @param superClass the super class
609     * @return the closes parent type
610     */
611    private static Type getClosestParentType(final Class<?> cls, final Class<?> superClass) {
612        // only look at the interfaces if the super class is also an interface
613        if (superClass.isInterface()) {
614            // get the generic interfaces of the subject class
615            final Type[] interfaceTypes = cls.getGenericInterfaces();
616            // will hold the best generic interface match found
617            Type genericInterface = null;
618            // find the interface closest to the super class
619            for (final Type midType : interfaceTypes) {
620                final Class<?> midClass;
621                if (midType instanceof ParameterizedType) {
622                    midClass = getRawType((ParameterizedType) midType);
623                } else if (midType instanceof Class<?>) {
624                    midClass = (Class<?>) midType;
625                } else {
626                    throw new IllegalStateException("Unexpected generic" + " interface type found: " + midType);
627                }
628                // check if this interface is further up the inheritance chain
629                // than the previously found match
630                if (isAssignable(midClass, superClass) && isAssignable(genericInterface, (Type) midClass)) {
631                    genericInterface = midType;
632                }
633            }
634            // found a match?
635            if (genericInterface != null) {
636                return genericInterface;
637            }
638        }
639        // none of the interfaces were descendants of the target class, so the
640        // super class has to be one, instead
641        return cls.getGenericSuperclass();
642    }
643
644    /**
645     * Gets an array containing the sole type of {@link Object} if {@link TypeVariable#getBounds()} returns an empty array. Otherwise, it returns the result of
646     * {@link TypeVariable#getBounds()} passed into {@link #normalizeUpperBounds}.
647     *
648     * @param typeVariable the subject type variable, not {@code null}
649     * @return a non-empty array containing the bounds of the type variable, which could be {@link Object}.
650     * @throws NullPointerException if {@code typeVariable} is {@code null}
651     */
652    public static Type[] getImplicitBounds(final TypeVariable<?> typeVariable) {
653        return normalizeUpperToObject(Objects.requireNonNull(typeVariable, "typeVariable").getBounds());
654    }
655
656    /**
657     * Gets an array containing a single value of {@code null} if {@link WildcardType#getLowerBounds()} returns an empty array. Otherwise, it returns the result
658     * of {@link WildcardType#getLowerBounds()}.
659     *
660     * @param wildcardType the subject wildcard type, not {@code null}
661     * @return a non-empty array containing the lower bounds of the wildcard type, which could be null.
662     * @throws NullPointerException if {@code wildcardType} is {@code null}
663     */
664    public static Type[] getImplicitLowerBounds(final WildcardType wildcardType) {
665        Objects.requireNonNull(wildcardType, "wildcardType");
666        final Type[] bounds = wildcardType.getLowerBounds();
667        return bounds.length == 0 ? new Type[] { null } : bounds;
668    }
669
670    /**
671     * Gets an array containing the sole value of {@link Object} if {@link WildcardType#getUpperBounds()} returns an empty array. Otherwise, it returns the
672     * result of {@link WildcardType#getUpperBounds()} passed into {@link #normalizeUpperBounds}.
673     *
674     * @param wildcardType the subject wildcard type, not {@code null}
675     * @return a non-empty array containing the upper bounds of the wildcard type.
676     * @throws NullPointerException if {@code wildcardType} is {@code null}
677     */
678    public static Type[] getImplicitUpperBounds(final WildcardType wildcardType) {
679        return normalizeUpperToObject(Objects.requireNonNull(wildcardType, "wildcardType").getUpperBounds());
680    }
681
682    /**
683     * Transforms the passed in type to a {@link Class} object. Type-checking method of convenience.
684     *
685     * @param parameterizedType the type to be converted
686     * @return the corresponding {@link Class} object
687     * @throws IllegalStateException if the conversion fails
688     */
689    private static Class<?> getRawType(final ParameterizedType parameterizedType) {
690        final Type rawType = parameterizedType.getRawType();
691        // check if raw type is a Class object
692        // not currently necessary, but since the return type is Type instead of
693        // Class, there's enough reason to believe that future versions of Java
694        // may return other Type implementations. And type-safety checking is
695        // rarely a bad idea.
696        if (!(rawType instanceof Class<?>)) {
697            throw new IllegalStateException("Type of rawType: " + rawType);
698        }
699        return (Class<?>) rawType;
700    }
701
702    /**
703     * Gets the raw type of a Java type, given its context. Primarily for use with {@link TypeVariable}s and {@link GenericArrayType}s, or when you do not know
704     * the runtime type of {@code type}: if you know you have a {@link Class} instance, it is already raw; if you know you have a {@link ParameterizedType}, its
705     * raw type is only a method call away.
706     *
707     * @param type          to resolve
708     * @param assigningType type to be resolved against
709     * @return the resolved {@link Class} object or {@code null} if the type could not be resolved
710     */
711    public static Class<?> getRawType(final Type type, final Type assigningType) {
712        if (type instanceof Class<?>) {
713            // it is raw, no problem
714            return (Class<?>) type;
715        }
716        if (type instanceof ParameterizedType) {
717            // simple enough to get the raw type of a ParameterizedType
718            return getRawType((ParameterizedType) type);
719        }
720        if (type instanceof TypeVariable<?>) {
721            if (assigningType == null) {
722                return null;
723            }
724            // get the entity declaring this type variable
725            final Object genericDeclaration = ((TypeVariable<?>) type).getGenericDeclaration();
726            // can't get the raw type of a method- or constructor-declared type
727            // variable
728            if (!(genericDeclaration instanceof Class<?>)) {
729                return null;
730            }
731            // get the type arguments for the declaring class/interface based
732            // on the enclosing type
733            final Map<TypeVariable<?>, Type> typeVarAssigns = getTypeArguments(assigningType, (Class<?>) genericDeclaration);
734            // enclosingType has to be a subclass (or subinterface) of the
735            // declaring type
736            if (typeVarAssigns == null) {
737                return null;
738            }
739            // get the argument assigned to this type variable
740            final Type typeArgument = typeVarAssigns.get(type);
741            if (typeArgument == null) {
742                return null;
743            }
744            // get the argument for this type variable
745            return getRawType(typeArgument, assigningType);
746        }
747        if (type instanceof GenericArrayType) {
748            // get raw component type
749            final Class<?> rawComponentType = getRawType(((GenericArrayType) type).getGenericComponentType(), assigningType);
750            // create array type from raw component type and return its class
751            return rawComponentType != null ? Array.newInstance(rawComponentType, 0).getClass() : null;
752        }
753        // (hand-waving) this is not the method you're looking for
754        if (type instanceof WildcardType) {
755            return null;
756        }
757        throw new IllegalArgumentException("unknown type: " + type);
758    }
759
760    /**
761     * Gets a map of the type arguments of a class in the context of {@code toClass}.
762     *
763     * @param cls               the class in question
764     * @param toClass           the context class
765     * @param subtypeVarAssigns a map with type variables
766     * @return the {@link Map} with type arguments
767     */
768    private static Map<TypeVariable<?>, Type> getTypeArguments(Class<?> cls, final Class<?> toClass, final Map<TypeVariable<?>, Type> subtypeVarAssigns) {
769        // make sure they're assignable
770        if (!isAssignable(cls, toClass)) {
771            return null;
772        }
773        // can't work with primitives
774        if (cls.isPrimitive()) {
775            // both classes are primitives?
776            if (toClass.isPrimitive()) {
777                // dealing with widening here. No type arguments to be
778                // harvested with these two types.
779                return new HashMap<>();
780            }
781            // work with wrapper the wrapper class instead of the primitive
782            cls = ClassUtils.primitiveToWrapper(cls);
783        }
784        // create a copy of the incoming map, or an empty one if it's null
785        final HashMap<TypeVariable<?>, Type> typeVarAssigns = subtypeVarAssigns == null ? new HashMap<>() : new HashMap<>(subtypeVarAssigns);
786        // has target class been reached?
787        if (toClass.equals(cls)) {
788            return typeVarAssigns;
789        }
790        // walk the inheritance hierarchy until the target class is reached
791        return getTypeArguments(getClosestParentType(cls, toClass), toClass, typeVarAssigns);
792    }
793
794    /**
795     * Gets all the type arguments for this parameterized type including owner hierarchy arguments such as {@code Outer<K, V>.Inner<T>.DeepInner<E>} . The
796     * arguments are returned in a {@link Map} specifying the argument type for each {@link TypeVariable}.
797     *
798     * @param type specifies the subject parameterized type from which to harvest the parameters.
799     * @return a {@link Map} of the type arguments to their respective type variables.
800     */
801    public static Map<TypeVariable<?>, Type> getTypeArguments(final ParameterizedType type) {
802        return getTypeArguments(type, getRawType(type), null);
803    }
804
805    /**
806     * Gets a map of the type arguments of a parameterized type in the context of {@code toClass}.
807     *
808     * @param parameterizedType the parameterized type
809     * @param toClass           the class
810     * @param subtypeVarAssigns a map with type variables
811     * @return the {@link Map} with type arguments
812     */
813    private static Map<TypeVariable<?>, Type> getTypeArguments(final ParameterizedType parameterizedType, final Class<?> toClass,
814            final Map<TypeVariable<?>, Type> subtypeVarAssigns) {
815        final Class<?> cls = getRawType(parameterizedType);
816        // make sure they're assignable
817        if (!isAssignable(cls, toClass)) {
818            return null;
819        }
820        final Type ownerType = parameterizedType.getOwnerType();
821        final Map<TypeVariable<?>, Type> typeVarAssigns;
822        if (ownerType instanceof ParameterizedType) {
823            // get the owner type arguments first
824            final ParameterizedType parameterizedOwnerType = (ParameterizedType) ownerType;
825            typeVarAssigns = getTypeArguments(parameterizedOwnerType, getRawType(parameterizedOwnerType), subtypeVarAssigns);
826        } else {
827            // no owner, prep the type variable assignments map
828            typeVarAssigns = subtypeVarAssigns == null ? new HashMap<>() : new HashMap<>(subtypeVarAssigns);
829        }
830        // get the subject parameterized type's arguments
831        final Type[] typeArgs = parameterizedType.getActualTypeArguments();
832        // and get the corresponding type variables from the raw class
833        final TypeVariable<?>[] typeParams = cls.getTypeParameters();
834        // map the arguments to their respective type variables
835        for (int i = 0; i < typeParams.length; i++) {
836            final Type typeArg = typeArgs[i];
837            typeVarAssigns.put(typeParams[i], typeVarAssigns.getOrDefault(typeArg, typeArg));
838        }
839        if (toClass.equals(cls)) {
840            // target class has been reached. Done.
841            return typeVarAssigns;
842        }
843        // walk the inheritance hierarchy until the target class is reached
844        return getTypeArguments(getClosestParentType(cls, toClass), toClass, typeVarAssigns);
845    }
846
847    /**
848     * Gets the type arguments of a class/interface based on a subtype. For instance, this method will determine that both of the parameters for the interface
849     * {@link Map} are {@link Object} for the subtype {@link java.util.Properties Properties} even though the subtype does not directly implement the
850     * {@link Map} interface.
851     *
852     * <p>
853     * This method returns {@code null} if {@code type} is not assignable to {@code toClass}. It returns an empty map if none of the classes or interfaces in
854     * its inheritance hierarchy specify any type arguments.
855     * </p>
856     *
857     * <p>
858     * A side effect of this method is that it also retrieves the type arguments for the classes and interfaces that are part of the hierarchy between
859     * {@code type} and {@code toClass}. So with the above example, this method will also determine that the type arguments for {@link java.util.Hashtable
860     * Hashtable} are also both {@link Object}. In cases where the interface specified by {@code toClass} is (indirectly) implemented more than once (e.g. where
861     * {@code toClass} specifies the interface {@link Iterable Iterable} and {@code type} specifies a parameterized type that implements both
862     * {@link java.util.Set Set} and {@link java.util.Collection Collection}), this method will look at the inheritance hierarchy of only one of the
863     * implementations/subclasses; the first interface encountered that isn't a subinterface to one of the others in the {@code type} to {@code toClass}
864     * hierarchy.
865     * </p>
866     *
867     * @param type    the type from which to determine the type parameters of {@code toClass}
868     * @param toClass the class whose type parameters are to be determined based on the subtype {@code type}
869     * @return a {@link Map} of the type assignments for the type variables in each type in the inheritance hierarchy from {@code type} to {@code toClass}
870     *         inclusive.
871     */
872    public static Map<TypeVariable<?>, Type> getTypeArguments(final Type type, final Class<?> toClass) {
873        return getTypeArguments(type, toClass, null);
874    }
875
876    /**
877     * Gets a map of the type arguments of {@code type} in the context of {@code toClass}.
878     *
879     * @param type              the type in question
880     * @param toClass           the class
881     * @param subtypeVarAssigns a map with type variables
882     * @return the {@link Map} with type arguments
883     */
884    private static Map<TypeVariable<?>, Type> getTypeArguments(final Type type, final Class<?> toClass, final Map<TypeVariable<?>, Type> subtypeVarAssigns) {
885        if (type instanceof Class<?>) {
886            return getTypeArguments((Class<?>) type, toClass, subtypeVarAssigns);
887        }
888        if (type instanceof ParameterizedType) {
889            return getTypeArguments((ParameterizedType) type, toClass, subtypeVarAssigns);
890        }
891        if (type instanceof GenericArrayType) {
892            return getTypeArguments(((GenericArrayType) type).getGenericComponentType(), toClass.isArray() ? toClass.getComponentType() : toClass,
893                    subtypeVarAssigns);
894        }
895        // since wildcard types are not assignable to classes, should this just
896        // return null?
897        if (type instanceof WildcardType) {
898            for (final Type bound : getImplicitUpperBounds((WildcardType) type)) {
899                // find the first bound that is assignable to the target class
900                if (isAssignable(bound, toClass)) {
901                    return getTypeArguments(bound, toClass, subtypeVarAssigns);
902                }
903            }
904            return null;
905        }
906        if (type instanceof TypeVariable<?>) {
907            for (final Type bound : getImplicitBounds((TypeVariable<?>) type)) {
908                // find the first bound that is assignable to the target class
909                if (isAssignable(bound, toClass)) {
910                    return getTypeArguments(bound, toClass, subtypeVarAssigns);
911                }
912            }
913            return null;
914        }
915        throw new IllegalStateException("found an unhandled type: " + type);
916    }
917
918    /**
919     * Tests whether the specified type denotes an array type.
920     *
921     * @param type the type to be checked
922     * @return {@code true} if {@code type} is an array class or a {@link GenericArrayType}.
923     */
924    public static boolean isArrayType(final Type type) {
925        return type instanceof GenericArrayType || type instanceof Class<?> && ((Class<?>) type).isArray();
926    }
927
928    /**
929     * Tests if the subject type may be implicitly cast to the target class following the Java generics rules.
930     *
931     * @param type    the subject type to be assigned to the target type
932     * @param toClass the target class
933     * @return {@code true} if {@code type} is assignable to {@code toClass}.
934     */
935    private static boolean isAssignable(final Type type, final Class<?> toClass) {
936        if (type == null) {
937            // consistency with ClassUtils.isAssignable() behavior
938            return toClass == null || !toClass.isPrimitive();
939        }
940        // only a null type can be assigned to null type which
941        // would have cause the previous to return true
942        if (toClass == null) {
943            return false;
944        }
945        // all types are assignable to themselves
946        if (toClass.equals(type)) {
947            return true;
948        }
949        if (type instanceof Class<?>) {
950            // just comparing two classes
951            return ClassUtils.isAssignable((Class<?>) type, toClass);
952        }
953        if (type instanceof ParameterizedType) {
954            // only have to compare the raw type to the class
955            return isAssignable(getRawType((ParameterizedType) type), toClass);
956        }
957        // *
958        if (type instanceof TypeVariable<?>) {
959            // if any of the bounds are assignable to the class, then the
960            // type is assignable to the class.
961            for (final Type bound : ((TypeVariable<?>) type).getBounds()) {
962                if (isAssignable(bound, toClass)) {
963                    return true;
964                }
965            }
966            return false;
967        }
968        // the only classes to which a generic array type can be assigned
969        // are class Object and array classes
970        if (type instanceof GenericArrayType) {
971            return toClass.equals(Object.class)
972                    || toClass.isArray() && isAssignable(((GenericArrayType) type).getGenericComponentType(), toClass.getComponentType());
973        }
974        // wildcard types are not assignable to a class (though one would think
975        // "? super Object" would be assignable to Object)
976        if (type instanceof WildcardType) {
977            return false;
978        }
979        throw new IllegalStateException("found an unhandled type: " + type);
980    }
981
982    /**
983     * Tests if the subject type may be implicitly cast to the target generic array type following the Java generics rules.
984     *
985     * @param type               the subject type to be assigned to the target type
986     * @param toGenericArrayType the target generic array type
987     * @param typeVarAssigns     a map with type variables
988     * @return {@code true} if {@code type} is assignable to {@code toGenericArrayType}.
989     */
990    private static boolean isAssignable(final Type type, final GenericArrayType toGenericArrayType, final Map<TypeVariable<?>, Type> typeVarAssigns) {
991        if (type == null) {
992            return true;
993        }
994        // only a null type can be assigned to null type which
995        // would have cause the previous to return true
996        if (toGenericArrayType == null) {
997            return false;
998        }
999        // all types are assignable to themselves
1000        if (toGenericArrayType.equals(type)) {
1001            return true;
1002        }
1003        final Type toComponentType = toGenericArrayType.getGenericComponentType();
1004        if (type instanceof Class<?>) {
1005            final Class<?> cls = (Class<?>) type;
1006            // compare the component types
1007            return cls.isArray() && isAssignable(cls.getComponentType(), toComponentType, typeVarAssigns);
1008        }
1009        if (type instanceof GenericArrayType) {
1010            // compare the component types
1011            return isAssignable(((GenericArrayType) type).getGenericComponentType(), toComponentType, typeVarAssigns);
1012        }
1013        if (type instanceof WildcardType) {
1014            // so long as one of the upper bounds is assignable, it's good
1015            for (final Type bound : getImplicitUpperBounds((WildcardType) type)) {
1016                if (isAssignable(bound, toGenericArrayType)) {
1017                    return true;
1018                }
1019            }
1020            return false;
1021        }
1022        if (type instanceof TypeVariable<?>) {
1023            // probably should remove the following logic and just return false.
1024            // type variables cannot specify arrays as bounds.
1025            for (final Type bound : getImplicitBounds((TypeVariable<?>) type)) {
1026                if (isAssignable(bound, toGenericArrayType)) {
1027                    return true;
1028                }
1029            }
1030            return false;
1031        }
1032        if (type instanceof ParameterizedType) {
1033            // the raw type of a parameterized type is never an array or
1034            // generic array, otherwise the declaration would look like this:
1035            // Collection[]< ? extends String > collection;
1036            return false;
1037        }
1038        throw new IllegalStateException("found an unhandled type: " + type);
1039    }
1040
1041    /**
1042     * Tests if the subject type may be implicitly cast to the target parameterized type following the Java generics rules.
1043     *
1044     * @param type                the subject type to be assigned to the target type
1045     * @param toParameterizedType the target parameterized type
1046     * @param typeVarAssigns      a map with type variables
1047     * @return {@code true} if {@code type} is assignable to {@code toType}.
1048     */
1049    private static boolean isAssignable(final Type type, final ParameterizedType toParameterizedType, final Map<TypeVariable<?>, Type> typeVarAssigns) {
1050        if (type == null) {
1051            return true;
1052        }
1053        // only a null type can be assigned to null type which
1054        // would have cause the previous to return true
1055        if (toParameterizedType == null) {
1056            return false;
1057        }
1058        // cannot cast an array type to a parameterized type.
1059        if (type instanceof GenericArrayType) {
1060            return false;
1061        }
1062        // all types are assignable to themselves
1063        if (toParameterizedType.equals(type)) {
1064            return true;
1065        }
1066        // get the target type's raw type
1067        final Class<?> toClass = getRawType(toParameterizedType);
1068        // get the subject type's type arguments including owner type arguments
1069        // and supertype arguments up to and including the target class.
1070        final Map<TypeVariable<?>, Type> fromTypeVarAssigns = getTypeArguments(type, toClass, null);
1071        // null means the two types are not compatible
1072        if (fromTypeVarAssigns == null) {
1073            return false;
1074        }
1075        // compatible types, but there's no type arguments. this is equivalent
1076        // to comparing Map< ?, ? > to Map, and raw types are always assignable
1077        // to parameterized types.
1078        if (fromTypeVarAssigns.isEmpty()) {
1079            return true;
1080        }
1081        // get the target type's type arguments including owner type arguments
1082        final Map<TypeVariable<?>, Type> toTypeVarAssigns = getTypeArguments(toParameterizedType, toClass, typeVarAssigns);
1083        // now to check each type argument
1084        for (final TypeVariable<?> var : toTypeVarAssigns.keySet()) {
1085            final Type toTypeArg = unrollVariableAssignments(var, toTypeVarAssigns);
1086            final Type fromTypeArg = unrollVariableAssignments(var, fromTypeVarAssigns);
1087            if (toTypeArg == null && fromTypeArg instanceof Class) {
1088                continue;
1089            }
1090            // parameters must either be absent from the subject type, within
1091            // the bounds of the wildcard type, or be an exact match to the
1092            // parameters of the target type.
1093            if (fromTypeArg != null && toTypeArg != null && !toTypeArg.equals(fromTypeArg)
1094                    && !(toTypeArg instanceof WildcardType && isAssignable(fromTypeArg, toTypeArg, typeVarAssigns))) {
1095                return false;
1096            }
1097        }
1098        return true;
1099    }
1100
1101    /**
1102     * Tests if the subject type may be implicitly cast to the target type following the Java generics rules. If both types are {@link Class} objects, the
1103     * method returns the result of {@link ClassUtils#isAssignable(Class, Class)}.
1104     *
1105     * @param type   the subject type to be assigned to the target type
1106     * @param toType the target type
1107     * @return {@code true} if {@code type} is assignable to {@code toType}.
1108     */
1109    public static boolean isAssignable(final Type type, final Type toType) {
1110        return isAssignable(type, toType, null);
1111    }
1112
1113    /**
1114     * Tests if the subject type may be implicitly cast to the target type following the Java generics rules.
1115     *
1116     * @param type           the subject type to be assigned to the target type
1117     * @param toType         the target type
1118     * @param typeVarAssigns optional map of type variable assignments
1119     * @return {@code true} if {@code type} is assignable to {@code toType}.
1120     */
1121    private static boolean isAssignable(final Type type, final Type toType, final Map<TypeVariable<?>, Type> typeVarAssigns) {
1122        if (toType == null || toType instanceof Class<?>) {
1123            return isAssignable(type, (Class<?>) toType);
1124        }
1125        if (toType instanceof ParameterizedType) {
1126            return isAssignable(type, (ParameterizedType) toType, typeVarAssigns);
1127        }
1128        if (toType instanceof GenericArrayType) {
1129            return isAssignable(type, (GenericArrayType) toType, typeVarAssigns);
1130        }
1131        if (toType instanceof WildcardType) {
1132            return isAssignable(type, (WildcardType) toType, typeVarAssigns);
1133        }
1134        if (toType instanceof TypeVariable<?>) {
1135            return isAssignable(type, (TypeVariable<?>) toType, typeVarAssigns);
1136        }
1137        throw new IllegalStateException("found an unhandled type: " + toType);
1138    }
1139
1140    /**
1141     * Tests if the subject type may be implicitly cast to the target type variable following the Java generics rules.
1142     *
1143     * @param type           the subject type to be assigned to the target type
1144     * @param toTypeVariable the target type variable
1145     * @param typeVarAssigns a map with type variables
1146     * @return {@code true} if {@code type} is assignable to {@code toTypeVariable}.
1147     */
1148    private static boolean isAssignable(final Type type, final TypeVariable<?> toTypeVariable, final Map<TypeVariable<?>, Type> typeVarAssigns) {
1149        if (type == null) {
1150            return true;
1151        }
1152        // only a null type can be assigned to null type which
1153        // would have cause the previous to return true
1154        if (toTypeVariable == null) {
1155            return false;
1156        }
1157        // all types are assignable to themselves
1158        if (toTypeVariable.equals(type)) {
1159            return true;
1160        }
1161        if (type instanceof TypeVariable<?>) {
1162            // a type variable is assignable to another type variable, if
1163            // and only if the former is the latter, extends the latter, or
1164            // is otherwise a descendant of the latter.
1165            final Type[] bounds = getImplicitBounds((TypeVariable<?>) type);
1166            for (final Type bound : bounds) {
1167                if (isAssignable(bound, toTypeVariable, typeVarAssigns)) {
1168                    return true;
1169                }
1170            }
1171        }
1172        if (type instanceof Class<?> || type instanceof ParameterizedType || type instanceof GenericArrayType || type instanceof WildcardType) {
1173            return false;
1174        }
1175        throw new IllegalStateException("found an unhandled type: " + type);
1176    }
1177
1178    /**
1179     * Tests if the subject type may be implicitly cast to the target wildcard type following the Java generics rules.
1180     *
1181     * @param type           the subject type to be assigned to the target type
1182     * @param toWildcardType the target wildcard type
1183     * @param typeVarAssigns a map with type variables
1184     * @return {@code true} if {@code type} is assignable to {@code toWildcardType}.
1185     */
1186    private static boolean isAssignable(final Type type, final WildcardType toWildcardType, final Map<TypeVariable<?>, Type> typeVarAssigns) {
1187        if (type == null) {
1188            return true;
1189        }
1190        // only a null type can be assigned to null type which
1191        // would have cause the previous to return true
1192        if (toWildcardType == null) {
1193            return false;
1194        }
1195        // all types are assignable to themselves
1196        if (toWildcardType.equals(type)) {
1197            return true;
1198        }
1199        final Type[] toUpperBounds = getImplicitUpperBounds(toWildcardType);
1200        final Type[] toLowerBounds = getImplicitLowerBounds(toWildcardType);
1201        if (type instanceof WildcardType) {
1202            final WildcardType wildcardType = (WildcardType) type;
1203            final Type[] upperBounds = getImplicitUpperBounds(wildcardType);
1204            final Type[] lowerBounds = getImplicitLowerBounds(wildcardType);
1205            for (Type toBound : toUpperBounds) {
1206                // if there are assignments for unresolved type variables,
1207                // now's the time to substitute them.
1208                toBound = substituteTypeVariables(toBound, typeVarAssigns);
1209                // each upper bound of the subject type has to be assignable to
1210                // each
1211                // upper bound of the target type
1212                for (final Type bound : upperBounds) {
1213                    if (!isAssignable(bound, toBound, typeVarAssigns)) {
1214                        return false;
1215                    }
1216                }
1217            }
1218            for (Type toBound : toLowerBounds) {
1219                // if there are assignments for unresolved type variables,
1220                // now's the time to substitute them.
1221                toBound = substituteTypeVariables(toBound, typeVarAssigns);
1222                // each lower bound of the target type has to be assignable to
1223                // each
1224                // lower bound of the subject type
1225                for (final Type bound : lowerBounds) {
1226                    if (!isAssignable(toBound, bound, typeVarAssigns)) {
1227                        return false;
1228                    }
1229                }
1230            }
1231            return true;
1232        }
1233        for (final Type toBound : toUpperBounds) {
1234            // if there are assignments for unresolved type variables,
1235            // now's the time to substitute them.
1236            if (!isAssignable(type, substituteTypeVariables(toBound, typeVarAssigns), typeVarAssigns)) {
1237                return false;
1238            }
1239        }
1240        for (final Type toBound : toLowerBounds) {
1241            // if there are assignments for unresolved type variables,
1242            // now's the time to substitute them.
1243            if (!isAssignable(substituteTypeVariables(toBound, typeVarAssigns), type, typeVarAssigns)) {
1244                return false;
1245            }
1246        }
1247        return true;
1248    }
1249
1250    /**
1251     * Tests whether the class contains a cyclical reference in the qualified name of a class. If any of the type parameters of A class is extending X class
1252     * which is in scope of A class, then it forms cycle.
1253     *
1254     * @param cls the class to test.
1255     * @return whether the class contains a cyclical reference.
1256     */
1257    private static boolean isCyclical(final Class<?> cls) {
1258        for (final TypeVariable<?> typeParameter : cls.getTypeParameters()) {
1259            for (final Type bound : typeParameter.getBounds()) {
1260                if (bound.getTypeName().contains(cls.getName())) {
1261                    return true;
1262                }
1263            }
1264        }
1265        return false;
1266    }
1267
1268    /**
1269     * Tests if the given value can be assigned to the target type following the Java generics rules.
1270     *
1271     * @param value the value to be checked
1272     * @param type  the target type
1273     * @return {@code true} if {@code value} is an instance of {@code type}.
1274     */
1275    public static boolean isInstance(final Object value, final Type type) {
1276        if (type == null) {
1277            return false;
1278        }
1279        return value == null ? !(type instanceof Class<?>) || !((Class<?>) type).isPrimitive() : isAssignable(value.getClass(), type, null);
1280    }
1281
1282    /**
1283     * Maps type variables.
1284     *
1285     * @param <T>               the generic type of the class in question
1286     * @param cls               the class in question
1287     * @param parameterizedType the parameterized type
1288     * @param typeVarAssigns    the map to be filled
1289     */
1290    private static <T> void mapTypeVariablesToArguments(final Class<T> cls, final ParameterizedType parameterizedType,
1291            final Map<TypeVariable<?>, Type> typeVarAssigns) {
1292        // capture the type variables from the owner type that have assignments
1293        final Type ownerType = parameterizedType.getOwnerType();
1294        if (ownerType instanceof ParameterizedType) {
1295            // recursion to make sure the owner's owner type gets processed
1296            mapTypeVariablesToArguments(cls, (ParameterizedType) ownerType, typeVarAssigns);
1297        }
1298        // parameterizedType is a generic interface/class (or it's in the owner
1299        // hierarchy of said interface/class) implemented/extended by the class
1300        // cls. Find out which type variables of cls are type arguments of
1301        // parameterizedType:
1302        final Type[] typeArgs = parameterizedType.getActualTypeArguments();
1303        // of the cls's type variables that are arguments of parameterizedType,
1304        // find out which ones can be determined from the super type's arguments
1305        final TypeVariable<?>[] typeVars = getRawType(parameterizedType).getTypeParameters();
1306        // use List view of type parameters of cls so the contains() method can be used:
1307        final List<TypeVariable<Class<T>>> typeVarList = Arrays.asList(cls.getTypeParameters());
1308        for (int i = 0; i < typeArgs.length; i++) {
1309            final TypeVariable<?> typeVar = typeVars[i];
1310            final Type typeArg = typeArgs[i];
1311            // argument of parameterizedType is a type variable of cls
1312            if (typeVarList.contains(typeArg)
1313                    // type variable of parameterizedType has an assignment in
1314                    // the super type.
1315                    && typeVarAssigns.containsKey(typeVar)) {
1316                // map the assignment to the cls's type variable
1317                typeVarAssigns.put((TypeVariable<?>) typeArg, typeVarAssigns.get(typeVar));
1318            }
1319        }
1320    }
1321
1322    /**
1323     * Strips out the redundant upper bound types in type variable types and wildcard types (or it would with wildcard types if multiple upper bounds were
1324     * allowed).
1325     *
1326     * <p>
1327     * Example, with the variable type declaration:
1328     * </p>
1329     *
1330     * <pre>{@code
1331     * <K extends java.util.Collection<String> & java.util.List<String>>
1332     * }</pre>
1333     *
1334     * <p>
1335     * since {@link List} is a subinterface of {@link Collection}, this method will return the bounds as if the declaration had been:
1336     * </p>
1337     *
1338     * <pre>{@code
1339     * <K extends java.util.List<String>>
1340     * }</pre>
1341     *
1342     * @param bounds an array of types representing the upper bounds of either {@link WildcardType} or {@link TypeVariable}, not {@code null}.
1343     * @return an array containing the values from {@code bounds} minus the redundant types.
1344     * @throws NullPointerException if {@code bounds} is {@code null}
1345     */
1346    public static Type[] normalizeUpperBounds(final Type[] bounds) {
1347        Objects.requireNonNull(bounds, "bounds");
1348        // don't bother if there's only one (or none) type
1349        if (bounds.length < 2) {
1350            return bounds;
1351        }
1352        final Set<Type> types = new HashSet<>(bounds.length);
1353        for (final Type type1 : bounds) {
1354            boolean subtypeFound = false;
1355            for (final Type type2 : bounds) {
1356                if (type1 != type2 && isAssignable(type2, type1, null)) {
1357                    subtypeFound = true;
1358                    break;
1359                }
1360            }
1361            if (!subtypeFound) {
1362                types.add(type1);
1363            }
1364        }
1365        return types.toArray(ArrayUtils.EMPTY_TYPE_ARRAY);
1366    }
1367
1368    /**
1369     * Delegates to {@link #normalizeUpperBounds(Type[])} unless {@code bounds} is empty in which case return an array with the element {@code Object.class}.
1370     *
1371     * @param bounds bounds an array of types representing the upper bounds of either {@link WildcardType} or {@link TypeVariable}, not {@code null}.
1372     * @return result from {@link #normalizeUpperBounds(Type[])} unless {@code bounds} is empty in which case return an array with the element
1373     *         {@code Object.class}.
1374     */
1375    private static Type[] normalizeUpperToObject(final Type[] bounds) {
1376        return bounds.length == 0 ? new Type[] { Object.class } : normalizeUpperBounds(bounds);
1377    }
1378
1379    /**
1380     * Creates a parameterized type instance.
1381     *
1382     * @param rawClass        the raw class to create a parameterized type instance for
1383     * @param typeVariableMap the map used for parameterization
1384     * @return {@link ParameterizedType}
1385     * @throws NullPointerException if either {@code rawClass} or {@code typeVariableMap} is {@code null}
1386     * @since 3.2
1387     */
1388    public static final ParameterizedType parameterize(final Class<?> rawClass, final Map<TypeVariable<?>, Type> typeVariableMap) {
1389        Objects.requireNonNull(rawClass, "rawClass");
1390        Objects.requireNonNull(typeVariableMap, "typeVariableMap");
1391        return parameterizeWithOwner(null, rawClass, extractTypeArgumentsFrom(typeVariableMap, rawClass.getTypeParameters()));
1392    }
1393
1394    /**
1395     * Creates a parameterized type instance.
1396     *
1397     * @param rawClass      the raw class to create a parameterized type instance for
1398     * @param typeArguments the types used for parameterization
1399     * @return {@link ParameterizedType}
1400     * @throws NullPointerException if {@code rawClass} is {@code null}
1401     * @since 3.2
1402     */
1403    public static final ParameterizedType parameterize(final Class<?> rawClass, final Type... typeArguments) {
1404        return parameterizeWithOwner(null, rawClass, typeArguments);
1405    }
1406
1407    /**
1408     * Formats a {@link ParameterizedType} as a {@link String}.
1409     *
1410     * @param parameterizedType {@link ParameterizedType} to format
1411     * @return String
1412     */
1413    private static String parameterizedTypeToString(final ParameterizedType parameterizedType) {
1414        final StringBuilder builder = new StringBuilder();
1415        final Type useOwner = parameterizedType.getOwnerType();
1416        final Class<?> raw = (Class<?>) parameterizedType.getRawType();
1417        if (useOwner == null) {
1418            builder.append(raw.getName());
1419        } else {
1420            if (useOwner instanceof Class<?>) {
1421                builder.append(((Class<?>) useOwner).getName());
1422            } else {
1423                builder.append(useOwner);
1424            }
1425            builder.append('.').append(raw.getSimpleName());
1426        }
1427        final int[] recursiveTypeIndexes = findRecursiveTypes(parameterizedType);
1428        if (recursiveTypeIndexes.length > 0) {
1429            appendRecursiveTypes(builder, recursiveTypeIndexes, parameterizedType.getActualTypeArguments());
1430        } else {
1431            GT_JOINER.join(builder, (Object[]) parameterizedType.getActualTypeArguments());
1432        }
1433        return builder.toString();
1434    }
1435
1436    /**
1437     * Creates a parameterized type instance.
1438     *
1439     * @param owner           the owning type
1440     * @param rawClass        the raw class to create a parameterized type instance for
1441     * @param typeVariableMap the map used for parameterization
1442     * @return {@link ParameterizedType}
1443     * @throws NullPointerException if either {@code rawClass} or {@code typeVariableMap} is {@code null}
1444     * @since 3.2
1445     */
1446    public static final ParameterizedType parameterizeWithOwner(final Type owner, final Class<?> rawClass, final Map<TypeVariable<?>, Type> typeVariableMap) {
1447        Objects.requireNonNull(rawClass, "rawClass");
1448        Objects.requireNonNull(typeVariableMap, "typeVariableMap");
1449        return parameterizeWithOwner(owner, rawClass, extractTypeArgumentsFrom(typeVariableMap, rawClass.getTypeParameters()));
1450    }
1451
1452    /**
1453     * Creates a parameterized type instance.
1454     *
1455     * @param owner         the owning type
1456     * @param rawClass      the raw class to create a parameterized type instance for
1457     * @param typeArguments the types used for parameterization
1458     * @return {@link ParameterizedType}
1459     * @throws NullPointerException if {@code rawClass} is {@code null}
1460     * @since 3.2
1461     */
1462    public static final ParameterizedType parameterizeWithOwner(final Type owner, final Class<?> rawClass, final Type... typeArguments) {
1463        Objects.requireNonNull(rawClass, "rawClass");
1464        final Type useOwner;
1465        if (rawClass.getEnclosingClass() == null) {
1466            Validate.isTrue(owner == null, "no owner allowed for top-level %s", rawClass);
1467            useOwner = null;
1468        } else if (owner == null) {
1469            useOwner = rawClass.getEnclosingClass();
1470        } else {
1471            Validate.isTrue(isAssignable(owner, rawClass.getEnclosingClass()), "%s is invalid owner type for parameterized %s", owner, rawClass);
1472            useOwner = owner;
1473        }
1474        Validate.noNullElements(typeArguments, "null type argument at index %s");
1475        Validate.isTrue(rawClass.getTypeParameters().length == typeArguments.length, "invalid number of type parameters specified: expected %d, got %d",
1476                rawClass.getTypeParameters().length, typeArguments.length);
1477        return new ParameterizedTypeImpl(rawClass, useOwner, typeArguments);
1478    }
1479
1480    /**
1481     * Finds the mapping for {@code type} in {@code typeVarAssigns}.
1482     *
1483     * @param type           the type to be replaced
1484     * @param typeVarAssigns the map with type variables
1485     * @return the replaced type
1486     * @throws IllegalArgumentException if the type cannot be substituted
1487     */
1488    private static Type substituteTypeVariables(final Type type, final Map<TypeVariable<?>, Type> typeVarAssigns) {
1489        if (type instanceof TypeVariable<?> && typeVarAssigns != null) {
1490            final Type replacementType = typeVarAssigns.get(type);
1491            if (replacementType == null) {
1492                throw new IllegalArgumentException("missing assignment type for type variable " + type);
1493            }
1494            return replacementType;
1495        }
1496        return type;
1497    }
1498
1499    /**
1500     * Formats a {@link TypeVariable} including its {@link GenericDeclaration}.
1501     *
1502     * @param typeVariable the type variable to create a String representation for, not {@code null}
1503     * @return String
1504     * @throws NullPointerException if {@code typeVariable} is {@code null}
1505     * @since 3.2
1506     */
1507    public static String toLongString(final TypeVariable<?> typeVariable) {
1508        Objects.requireNonNull(typeVariable, "typeVariable");
1509        final StringBuilder buf = new StringBuilder();
1510        final GenericDeclaration d = typeVariable.getGenericDeclaration();
1511        if (d instanceof Class<?>) {
1512            Class<?> c = (Class<?>) d;
1513            while (true) {
1514                if (c.getEnclosingClass() == null) {
1515                    buf.insert(0, c.getName());
1516                    break;
1517                }
1518                buf.insert(0, c.getSimpleName()).insert(0, '.');
1519                c = c.getEnclosingClass();
1520            }
1521        } else if (d instanceof Type) { // not possible as of now
1522            buf.append(toString((Type) d));
1523        } else {
1524            buf.append(d);
1525        }
1526        return buf.append(':').append(typeVariableToString(typeVariable)).toString();
1527    }
1528
1529    /**
1530     * Formats a given type as a Java-esque String.
1531     *
1532     * @param type the type to create a String representation for, not {@code null}
1533     * @return String
1534     * @throws NullPointerException if {@code type} is {@code null}
1535     * @since 3.2
1536     */
1537    public static String toString(final Type type) {
1538        Objects.requireNonNull(type, "type");
1539        if (type instanceof Class<?>) {
1540            return classToString((Class<?>) type);
1541        }
1542        if (type instanceof ParameterizedType) {
1543            return parameterizedTypeToString((ParameterizedType) type);
1544        }
1545        if (type instanceof WildcardType) {
1546            return wildcardTypeToString((WildcardType) type);
1547        }
1548        if (type instanceof TypeVariable<?>) {
1549            return typeVariableToString((TypeVariable<?>) type);
1550        }
1551        if (type instanceof GenericArrayType) {
1552            return genericArrayTypeToString((GenericArrayType) type);
1553        }
1554        throw new IllegalArgumentException(ObjectUtils.identityToString(type));
1555    }
1556
1557    /**
1558     * Determines whether or not specified types satisfy the bounds of their mapped type variables. When a type parameter extends another (such as
1559     * {@code <T, S extends T>}), uses another as a type parameter (such as {@code <T, S extends Comparable>>}), or otherwise depends on another type variable
1560     * to be specified, the dependencies must be included in {@code typeVarAssigns}.
1561     *
1562     * @param typeVariableMap specifies the potential types to be assigned to the type variables, not {@code null}.
1563     * @return whether or not the types can be assigned to their respective type variables.
1564     * @throws NullPointerException if {@code typeVariableMap} is {@code null}
1565     */
1566    public static boolean typesSatisfyVariables(final Map<TypeVariable<?>, Type> typeVariableMap) {
1567        Objects.requireNonNull(typeVariableMap, "typeVariableMap");
1568        // all types must be assignable to all the bounds of their mapped
1569        // type variable.
1570        for (final Map.Entry<TypeVariable<?>, Type> entry : typeVariableMap.entrySet()) {
1571            final TypeVariable<?> typeVar = entry.getKey();
1572            final Type type = entry.getValue();
1573
1574            for (final Type bound : getImplicitBounds(typeVar)) {
1575                if (!isAssignable(type, substituteTypeVariables(bound, typeVariableMap), typeVariableMap)) {
1576                    return false;
1577                }
1578            }
1579        }
1580        return true;
1581    }
1582
1583    /**
1584     * Formats a {@link TypeVariable} as a {@link String}.
1585     *
1586     * @param typeVariable {@link TypeVariable} to format
1587     * @return String
1588     */
1589    private static String typeVariableToString(final TypeVariable<?> typeVariable) {
1590        final StringBuilder builder = new StringBuilder(typeVariable.getName());
1591        final Type[] bounds = typeVariable.getBounds();
1592        if (bounds.length > 0 && !(bounds.length == 1 && Object.class.equals(bounds[0]))) {
1593            // https://issues.apache.org/jira/projects/LANG/issues/LANG-1698
1594            // There must be a better way to avoid a stack overflow on Java 17 and up.
1595            // Bounds are different in Java 17 and up where instead of Object you can get an interface like Comparable.
1596            final Type bound = bounds[0];
1597            boolean append = true;
1598            if (bound instanceof ParameterizedType) {
1599                final Type rawType = ((ParameterizedType) bound).getRawType();
1600                if (rawType instanceof Class && ((Class<?>) rawType).isInterface()) {
1601                    // Avoid recursion and stack overflow on Java 17 and up.
1602                    append = false;
1603                }
1604            }
1605            if (append) {
1606                builder.append(" extends ");
1607                AMP_JOINER.join(builder, bounds);
1608            }
1609        }
1610        return builder.toString();
1611    }
1612
1613    /**
1614     * Unrolls variables in a type bounds array.
1615     *
1616     * @param typeArguments assignments {@link Map}
1617     * @param bounds        in which to expand variables
1618     * @return {@code bounds} with any variables reassigned
1619     */
1620    private static Type[] unrollBounds(final Map<TypeVariable<?>, Type> typeArguments, final Type[] bounds) {
1621        Type[] result = bounds;
1622        int i = 0;
1623        for (; i < result.length; i++) {
1624            final Type unrolled = unrollVariables(typeArguments, result[i]);
1625            if (unrolled == null) {
1626                result = ArrayUtils.remove(result, i--);
1627            } else {
1628                result[i] = unrolled;
1629            }
1630        }
1631        return result;
1632    }
1633
1634    /**
1635     * Looks up {@code typeVariable} in {@code typeVarAssigns} <em>transitively</em>, i.e. keep looking until the value found is <em>not</em> a type variable.
1636     *
1637     * @param typeVariable   the type variable to look up
1638     * @param typeVarAssigns the map used for the look-up
1639     * @return Type or {@code null} if some variable was not in the map
1640     */
1641    private static Type unrollVariableAssignments(TypeVariable<?> typeVariable, final Map<TypeVariable<?>, Type> typeVarAssigns) {
1642        Type result;
1643        do {
1644            result = typeVarAssigns.get(typeVariable);
1645            if (!(result instanceof TypeVariable<?>) || result.equals(typeVariable)) {
1646                break;
1647            }
1648            typeVariable = (TypeVariable<?>) result;
1649        } while (true);
1650        return result;
1651    }
1652
1653    /**
1654     * Gets a type representing {@code type} with variable assignments "unrolled."
1655     *
1656     * @param typeArguments as from {@link TypeUtils#getTypeArguments(Type, Class)}
1657     * @param type          the type to unroll variable assignments for
1658     * @return Type
1659     * @since 3.2
1660     */
1661    public static Type unrollVariables(Map<TypeVariable<?>, Type> typeArguments, final Type type) {
1662        if (typeArguments == null) {
1663            typeArguments = Collections.emptyMap();
1664        }
1665        if (containsTypeVariables(type)) {
1666            if (type instanceof TypeVariable<?>) {
1667                return unrollVariables(typeArguments, typeArguments.get(type));
1668            }
1669            if (type instanceof ParameterizedType) {
1670                final ParameterizedType p = (ParameterizedType) type;
1671                final Map<TypeVariable<?>, Type> parameterizedTypeArguments;
1672                if (p.getOwnerType() == null) {
1673                    parameterizedTypeArguments = typeArguments;
1674                } else {
1675                    parameterizedTypeArguments = new HashMap<>(typeArguments);
1676                    parameterizedTypeArguments.putAll(getTypeArguments(p));
1677                }
1678                final Type[] args = p.getActualTypeArguments();
1679                for (int i = 0; i < args.length; i++) {
1680                    final Type unrolled = unrollVariables(parameterizedTypeArguments, args[i]);
1681                    if (unrolled != null) {
1682                        args[i] = unrolled;
1683                    }
1684                }
1685                return parameterizeWithOwner(p.getOwnerType(), (Class<?>) p.getRawType(), args);
1686            }
1687            if (type instanceof WildcardType) {
1688                final WildcardType wild = (WildcardType) type;
1689                return wildcardType().withUpperBounds(unrollBounds(typeArguments, wild.getUpperBounds()))
1690                        .withLowerBounds(unrollBounds(typeArguments, wild.getLowerBounds())).build();
1691            }
1692        }
1693        return type;
1694    }
1695
1696    /**
1697     * Gets a {@link WildcardTypeBuilder}.
1698     *
1699     * @return {@link WildcardTypeBuilder}
1700     * @since 3.2
1701     */
1702    public static WildcardTypeBuilder wildcardType() {
1703        return new WildcardTypeBuilder();
1704    }
1705
1706    /**
1707     * Formats a {@link WildcardType} as a {@link String}.
1708     *
1709     * @param wildcardType {@link WildcardType} to format
1710     * @return String
1711     */
1712    private static String wildcardTypeToString(final WildcardType wildcardType) {
1713        final StringBuilder builder = new StringBuilder().append('?');
1714        final Type[] lowerBounds = wildcardType.getLowerBounds();
1715        final Type[] upperBounds = wildcardType.getUpperBounds();
1716        if (lowerBounds.length > 1 || lowerBounds.length == 1 && lowerBounds[0] != null) {
1717            AMP_JOINER.join(builder.append(" super "), lowerBounds);
1718        } else if (upperBounds.length > 1 || upperBounds.length == 1 && !Object.class.equals(upperBounds[0])) {
1719            AMP_JOINER.join(builder.append(" extends "), upperBounds);
1720        }
1721        return builder.toString();
1722    }
1723
1724    /**
1725     * Wraps the specified {@link Class} in a {@link Typed} wrapper.
1726     *
1727     * @param <T>  generic type
1728     * @param type to wrap
1729     * @return {@code Typed<T>}
1730     * @since 3.2
1731     */
1732    public static <T> Typed<T> wrap(final Class<T> type) {
1733        return wrap((Type) type);
1734    }
1735
1736    /**
1737     * Wraps the specified {@link Type} in a {@link Typed} wrapper.
1738     *
1739     * @param <T>  inferred generic type
1740     * @param type to wrap
1741     * @return {@code Typed<T>}
1742     * @since 3.2
1743     */
1744    public static <T> Typed<T> wrap(final Type type) {
1745        return () -> type;
1746    }
1747
1748    /**
1749     * {@link TypeUtils} instances should NOT be constructed in standard programming. Instead, the class should be used as
1750     * {@code TypeUtils.isAssignable(cls, toClass)}.
1751     * <p>
1752     * This constructor is public to permit tools that require a JavaBean instance to operate.
1753     * </p>
1754     *
1755     * @deprecated TODO Make private in 4.0.
1756     */
1757    @Deprecated
1758    public TypeUtils() {
1759        // empty
1760    }
1761
1762}