View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.reflect;
18  
19  import java.lang.reflect.AccessibleObject;
20  import java.lang.reflect.Constructor;
21  import java.lang.reflect.Member;
22  import java.lang.reflect.Method;
23  import java.lang.reflect.Modifier;
24  
25  import org.apache.commons.lang3.ClassUtils;
26  
27  /**
28   * Contains common code for working with {@link java.lang.reflect.Method Methods}/{@link java.lang.reflect.Constructor Constructors},
29   * extracted and refactored from {@link MethodUtils} when it was imported from Commons BeanUtils.
30   */
31  final class MemberUtils {
32      // TODO extract an interface to implement compareParameterSets(...)?
33  
34      /**
35       * A class providing a subset of the API of java.lang.reflect.Executable in Java 1.8,
36       * providing a common representation for function signatures for Constructors and Methods.
37       */
38      private static final class Executable {
39  
40          private static Executable of(final Constructor<?> constructor) {
41              return new Executable(constructor);
42          }
43  
44          private static Executable of(final Method method) {
45              return new Executable(method);
46          }
47  
48          private final Class<?>[] parameterTypes;
49          private final boolean isVarArgs;
50  
51          private Executable(final Constructor<?> constructor) {
52              parameterTypes = constructor.getParameterTypes();
53              isVarArgs = constructor.isVarArgs();
54          }
55  
56          private Executable(final Method method) {
57              parameterTypes = method.getParameterTypes();
58              isVarArgs = method.isVarArgs();
59          }
60  
61          public Class<?>[] getParameterTypes() {
62              return parameterTypes;
63          }
64  
65          public boolean isVarArgs() {
66              return isVarArgs;
67          }
68      }
69  
70      private static final int ACCESS_TEST = Modifier.PUBLIC | Modifier.PROTECTED | Modifier.PRIVATE;
71  
72      /**
73       * Array of primitive number types ordered by "promotability" from narrow to wide.
74       */
75      private static final Class<?>[] WIDENING_PRIMITIVE_TYPES = {
76              // @formatter:off
77              Byte.TYPE,      // byte
78              Short.TYPE,     // short
79              Character.TYPE, // char
80              Integer.TYPE,   // int
81              Long.TYPE,      // long
82              Float.TYPE,     // float
83              Double.TYPE     // double
84              // @formatter:on
85      };
86  
87      /**
88       * Compares the relative fitness of two Constructors in terms of how well they match a set of runtime parameter types, such that a list ordered by the
89       * results of the comparison would return the best match first (least).
90       *
91       * @param left   the "left" Constructor.
92       * @param right  the "right" Constructor.
93       * @param actual the runtime parameter types to match against. {@code left}/{@code right}.
94       * @return int consistent with {@code compare} semantics.
95       */
96      static int compareConstructorFit(final Constructor<?> left, final Constructor<?> right, final Class<?>[] actual) {
97        return compareParameterTypes(Executable.of(left), Executable.of(right), actual);
98      }
99  
100     /**
101      * Compares the relative fitness of two Methods in terms of how well they match a set of runtime parameter types, such that a list ordered by the results of
102      * the comparison would return the best match first (least).
103      *
104      * @param left   the "left" Method.
105      * @param right  the "right" Method.
106      * @param actual the runtime parameter types to match against. {@code left}/{@code right}.
107      * @return int consistent with {@code compare} semantics.
108      */
109     static int compareMethodFit(final Method left, final Method right, final Class<?>[] actual) {
110       return compareParameterTypes(Executable.of(left), Executable.of(right), actual);
111     }
112 
113     /**
114      * Compares the relative fitness of two Executables in terms of how well they match a set of runtime parameter types, such that a list ordered by the
115      * results of the comparison would return the best match first (least).
116      *
117      * @param left   the "left" Executable.
118      * @param right  the "right" Executable.
119      * @param actual the runtime parameter types to match against. {@code left}/{@code right}.
120      * @return int consistent with {@code compare} semantics.
121      */
122     private static int compareParameterTypes(final Executable left, final Executable right, final Class<?>[] actual) {
123         final float leftCost = getTotalTransformationCost(actual, left);
124         final float rightCost = getTotalTransformationCost(actual, right);
125         return Float.compare(leftCost, rightCost);
126     }
127 
128     /**
129      * Gets the number of steps needed to turn the source class into the destination class. This represents the number of steps in the object hierarchy graph.
130      *
131      * @param srcClass  The source class.
132      * @param destClass The destination class.
133      * @return The cost of transforming an object.
134      */
135     private static float getObjectTransformationCost(Class<?> srcClass, final Class<?> destClass) {
136         if (destClass.isPrimitive()) {
137             return getPrimitivePromotionCost(srcClass, destClass);
138         }
139         float cost = 0.0f;
140         while (srcClass != null && !destClass.equals(srcClass)) {
141             if (destClass.isInterface() && ClassUtils.isAssignable(srcClass, destClass)) {
142                 // slight penalty for interface match.
143                 // we still want an exact match to override an interface match,
144                 // but
145                 // an interface match should override anything where we have to
146                 // get a superclass.
147                 cost += 0.25f;
148                 break;
149             }
150             cost++;
151             srcClass = srcClass.getSuperclass();
152         }
153         /*
154          * If the destination class is null, we've traveled all the way up to an Object match. We'll penalize this by adding 1.5 to the cost.
155          */
156         if (srcClass == null) {
157             cost += 1.5f;
158         }
159         return cost;
160     }
161 
162     /**
163      * Gets the number of steps required to promote a primitive to another type.
164      *
165      * @param srcClass  the (primitive) source class.
166      * @param destClass the (primitive) destination class.
167      * @return The cost of promoting the primitive.
168      */
169     private static float getPrimitivePromotionCost(final Class<?> srcClass, final Class<?> destClass) {
170         if (srcClass == null) {
171             return 1.5f;
172         }
173         float cost = 0.0f;
174         Class<?> cls = srcClass;
175         if (!cls.isPrimitive()) {
176             // slight unwrapping penalty
177             cost += 0.1f;
178             cls = ClassUtils.wrapperToPrimitive(cls);
179         }
180         // Increase the cost as the loop widens the type.
181         for (int i = 0; cls != destClass && i < WIDENING_PRIMITIVE_TYPES.length; i++) {
182             if (cls == WIDENING_PRIMITIVE_TYPES[i]) {
183                 cost += 0.1f;
184                 if (i < WIDENING_PRIMITIVE_TYPES.length - 1) {
185                     cls = WIDENING_PRIMITIVE_TYPES[i + 1];
186                 }
187             }
188         }
189         return cost;
190     }
191 
192     /**
193      * Gets the sum of the object transformation cost for each class in the source argument list.
194      *
195      * @param srcArgs    The source arguments.
196      * @param executable The executable to calculate transformation costs for.
197      * @return The total transformation cost.
198      */
199     private static float getTotalTransformationCost(final Class<?>[] srcArgs, final Executable executable) {
200         final Class<?>[] destArgs = executable.getParameterTypes();
201         final boolean isVarArgs = executable.isVarArgs();
202         // "source" and "destination" are the actual and declared args respectively.
203         float totalCost = 0.0f;
204         final long normalArgsLen = isVarArgs ? destArgs.length - 1 : destArgs.length;
205         if (srcArgs.length < normalArgsLen) {
206             return Float.MAX_VALUE;
207         }
208         for (int i = 0; i < normalArgsLen; i++) {
209             totalCost += getObjectTransformationCost(srcArgs[i], destArgs[i]);
210         }
211         if (isVarArgs) {
212             // When isVarArgs is true, srcArgs and dstArgs may differ in length.
213             // There are two special cases to consider:
214             final boolean noVarArgsPassed = srcArgs.length < destArgs.length;
215             final boolean explicitArrayForVarargs = srcArgs.length == destArgs.length && srcArgs[srcArgs.length - 1] != null
216                     && srcArgs[srcArgs.length - 1].isArray();
217             final float varArgsCost = 0.001f;
218             final Class<?> destClass = destArgs[destArgs.length - 1].getComponentType();
219             if (noVarArgsPassed) {
220                 // When no varargs passed, the best match is the most generic matching type, not the most specific.
221                 totalCost += getObjectTransformationCost(destClass, Object.class) + varArgsCost;
222             } else if (explicitArrayForVarargs) {
223                 final Class<?> sourceClass = srcArgs[srcArgs.length - 1].getComponentType();
224                 totalCost += getObjectTransformationCost(sourceClass, destClass) + varArgsCost;
225             } else {
226                 // This is typical varargs case.
227                 for (int i = destArgs.length - 1; i < srcArgs.length; i++) {
228                     final Class<?> srcClass = srcArgs[i];
229                     totalCost += getObjectTransformationCost(srcClass, destClass) + varArgsCost;
230                 }
231             }
232         }
233         return totalCost;
234     }
235 
236     /**
237      * Tests whether a {@link Member} is accessible.
238      *
239      * @param member Member to test, may be null.
240      * @return {@code true} if {@code m} is accessible.
241      */
242     static boolean isAccessible(final Member member) {
243         return isPublic(member) && !member.isSynthetic();
244     }
245 
246     static boolean isMatchingConstructor(final Constructor<?> method, final Class<?>[] parameterTypes) {
247         return isMatchingExecutable(Executable.of(method), parameterTypes);
248     }
249 
250     private static boolean isMatchingExecutable(final Executable method, final Class<?>[] parameterTypes) {
251         final Class<?>[] methodParameterTypes = method.getParameterTypes();
252         if (ClassUtils.isAssignable(parameterTypes, methodParameterTypes, true)) {
253             return true;
254         }
255         if (method.isVarArgs()) {
256             int i;
257             for (i = 0; i < methodParameterTypes.length - 1 && i < parameterTypes.length; i++) {
258                 if (!ClassUtils.isAssignable(parameterTypes[i], methodParameterTypes[i], true)) {
259                     return false;
260                 }
261             }
262             final Class<?> varArgParameterType = methodParameterTypes[methodParameterTypes.length - 1].getComponentType();
263             for (; i < parameterTypes.length; i++) {
264                 if (!ClassUtils.isAssignable(parameterTypes[i], varArgParameterType, true)) {
265                     return false;
266                 }
267             }
268             return true;
269         }
270         return false;
271     }
272 
273     static boolean isMatchingMethod(final Method method, final Class<?>[] parameterTypes) {
274       return isMatchingExecutable(Executable.of(method), parameterTypes);
275     }
276 
277     /**
278      * Tests whether a given set of modifiers implies package access.
279      *
280      * @param modifiers to test.
281      * @return {@code true} unless {@code package}/{@code protected}/{@code private} modifier detected
282      */
283     static boolean isPackage(final int modifiers) {
284         return (modifiers & ACCESS_TEST) == 0;
285     }
286 
287     /**
288      * Tests whether a {@link Member} is public.
289      *
290      * @param member Member to test, may be null.
291      * @return {@code true} if {@code m} is public.
292      */
293     static boolean isPublic(final Member member) {
294         return member != null && Modifier.isPublic(member.getModifiers());
295     }
296 
297     /**
298      * Tests whether a {@link Member} is static.
299      *
300      * @param member Member to test, may be null.
301      * @return {@code true} if {@code m} is static.
302      */
303     static boolean isStatic(final Member member) {
304         return member != null && Modifier.isStatic(member.getModifiers());
305     }
306 
307     /**
308      * Default access superclass workaround.
309      * <p>
310      * When a {@code public} class has a default access superclass with {@code public} members,
311      * these members are accessible. Calling them from compiled code works fine.
312      * Unfortunately, on some JVMs, using reflection to invoke these members
313      * seems to (wrongly) prevent access even when the modifier is {@code public}.
314      * Calling {@code setAccessible(true)} solves the problem but will only work from
315      * sufficiently privileged code. Better workarounds would be gratefully
316      * accepted.
317      * </p>
318      *
319      * @param obj the AccessibleObject to set as accessible, may be null.
320      * @return a boolean indicating whether the accessibility of the object was set to true.
321      */
322     static <T extends AccessibleObject> T setAccessibleWorkaround(final T obj) {
323         if (AccessibleObjects.isAccessible(obj)) {
324             return obj;
325         }
326         final Member m = (Member) obj;
327         if (isPublic(m) && isPackage(m.getDeclaringClass().getModifiers())) {
328             try {
329                 obj.setAccessible(true);
330                 return obj;
331             } catch (final SecurityException ignored) {
332                 // Ignore in favor of subsequent IllegalAccessException
333             }
334         }
335         return obj;
336     }
337 
338 }