You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by mb...@apache.org on 2013/10/11 21:38:49 UTC
svn commit: r1531403 - in
/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect:
ConstructorUtils.java FieldUtils.java MemberUtils.java MethodUtils.java
Author: mbenson
Date: Fri Oct 11 19:38:49 2013
New Revision: 1531403
URL: http://svn.apache.org/r1531403
Log:
a bit of dog food and a lot of javadoc tweakage
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/ConstructorUtils.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MemberUtils.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java
Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/ConstructorUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/ConstructorUtils.java?rev=1531403&r1=1531402&r2=1531403&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/ConstructorUtils.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/ConstructorUtils.java Fri Oct 11 19:38:49 2013
@@ -16,26 +16,28 @@
*/
package org.apache.commons.lang3.reflect;
+import java.lang.reflect.AccessibleObject;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Modifier;
import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.lang3.ClassUtils;
+import org.apache.commons.lang3.Validate;
/**
* <p> Utility reflection methods focused on constructors, modeled after
* {@link MethodUtils}. </p>
*
* <h3>Known Limitations</h3> <h4>Accessing Public Constructors In A Default
- * Access Superclass</h4> <p>There is an issue when invoking public constructors
- * contained in a default access superclass. Reflection locates these
- * constructors fine and correctly assigns them as public. However, an
- * <code>IllegalAccessException</code> is thrown if the constructors is
+ * Access Superclass</h4> <p>There is an issue when invoking {@code public} constructors
+ * contained in a default access superclass. Reflection correctly locates these
+ * constructors and assigns them as {@code public}. However, an
+ * {@link IllegalAccessException} is thrown if the constructor is
* invoked.</p>
*
- * <p><code>ConstructorUtils</code> contains a workaround for this situation. It
- * will attempt to call <code>setAccessible</code> on this constructor. If this
+ * <p>{@link ConstructorUtils} contains a workaround for this situation: it
+ * will attempt to call {@link AccessibleObject#setAccessible(boolean)} on this constructor. If this
* call succeeds, then the method can be invoked as normal. This call will only
* succeed when the application has sufficient security privileges. If this call
* fails then a warning will be logged and the method may fail.</p>
@@ -48,9 +50,9 @@ public class ConstructorUtils {
/**
* <p>ConstructorUtils instances should NOT be constructed in standard
* programming. Instead, the class should be used as
- * <code>ConstructorUtils.invokeConstructor(cls, args)</code>.</p>
+ * {@code ConstructorUtils.invokeConstructor(cls, args)}.</p>
*
- * <p>This constructor is public to permit tools that require a JavaBean
+ * <p>This constructor is {@code public} to permit tools that require a JavaBean
* instance to operate.</p>
*/
public ConstructorUtils() {
@@ -65,10 +67,11 @@ public class ConstructorUtils {
* The constructor signature must match the argument types by assignment compatibility.</p>
*
* @param <T> the type to be constructed
- * @param cls the class to be constructed, not null
- * @param args the array of arguments, null treated as empty
- * @return new instance of <code>cls</code>, not null
+ * @param cls the class to be constructed, not {@code null}
+ * @param args the array of arguments, {@code null treated as empty
+ * @return new instance of {@code cls}, not {@code null}
*
+ * @throws NullPointerException if {@code cls} is {@code null}
* @throws NoSuchMethodException if a matching constructor cannot be found
* @throws IllegalAccessException if invocation is not permitted by security
* @throws InvocationTargetException if an error occurs on invocation
@@ -78,9 +81,7 @@ public class ConstructorUtils {
public static <T> T invokeConstructor(final Class<T> cls, Object... args)
throws NoSuchMethodException, IllegalAccessException, InvocationTargetException,
InstantiationException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
final Class<?> parameterTypes[] = ClassUtils.toClass(args);
return invokeConstructor(cls, args, parameterTypes);
}
@@ -93,11 +94,12 @@ public class ConstructorUtils {
* The constructor signature must match the parameter types by assignment compatibility.</p>
*
* @param <T> the type to be constructed
- * @param cls the class to be constructed, not null
- * @param args the array of arguments, null treated as empty
- * @param parameterTypes the array of parameter types, null treated as empty
- * @return new instance of <code>cls</code>, not null
+ * @param cls the class to be constructed, not {@code null}
+ * @param args the array of arguments, {@code null} treated as empty
+ * @param parameterTypes the array of parameter types, {@code null} treated as empty
+ * @return new instance of {@code cls}, not {@code null}
*
+ * @throws NullPointerException if {@code cls} is {@code null}
* @throws NoSuchMethodException if a matching constructor cannot be found
* @throws IllegalAccessException if invocation is not permitted by security
* @throws InvocationTargetException if an error occurs on invocation
@@ -107,12 +109,8 @@ public class ConstructorUtils {
public static <T> T invokeConstructor(final Class<T> cls, Object[] args, Class<?>[] parameterTypes)
throws NoSuchMethodException, IllegalAccessException, InvocationTargetException,
InstantiationException {
- if (parameterTypes == null) {
- parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY;
- }
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
+ parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
final Constructor<T> ctor = getMatchingAccessibleConstructor(cls, parameterTypes);
if (ctor == null) {
throw new NoSuchMethodException(
@@ -129,10 +127,11 @@ public class ConstructorUtils {
* The constructor signature must match the argument types exactly.</p>
*
* @param <T> the type to be constructed
- * @param cls the class to be constructed, not null
- * @param args the array of arguments, null treated as empty
- * @return new instance of <code>cls</code>, not null
+ * @param cls the class to be constructed, not {@code null}
+ * @param args the array of arguments, {@code null treated as empty
+ * @return new instance of {@code cls}, not {@code null
*
+ * @throws NullPointerException if {@code cls} is {@code null}
* @throws NoSuchMethodException if a matching constructor cannot be found
* @throws IllegalAccessException if invocation is not permitted by security
* @throws InvocationTargetException if an error occurs on invocation
@@ -142,9 +141,7 @@ public class ConstructorUtils {
public static <T> T invokeExactConstructor(final Class<T> cls, Object... args)
throws NoSuchMethodException, IllegalAccessException, InvocationTargetException,
InstantiationException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
final Class<?> parameterTypes[] = ClassUtils.toClass(args);
return invokeExactConstructor(cls, args, parameterTypes);
}
@@ -157,11 +154,12 @@ public class ConstructorUtils {
* The constructor signature must match the parameter types exactly.</p>
*
* @param <T> the type to be constructed
- * @param cls the class to be constructed, not null
- * @param args the array of arguments, null treated as empty
- * @param parameterTypes the array of parameter types, null treated as empty
- * @return new instance of <code>cls</code>, not null
+ * @param cls the class to be constructed, not {@code null}
+ * @param args the array of arguments, {@code null} treated as empty
+ * @param parameterTypes the array of parameter types, {@code null} treated as empty
+ * @return new instance of <code>cls</code>, not {@code null}
*
+ * @throws NullPointerException if {@code cls} is {@code null}
* @throws NoSuchMethodException if a matching constructor cannot be found
* @throws IllegalAccessException if invocation is not permitted by security
* @throws InvocationTargetException if an error occurs on invocation
@@ -171,12 +169,8 @@ public class ConstructorUtils {
public static <T> T invokeExactConstructor(final Class<T> cls, Object[] args,
Class<?>[] parameterTypes) throws NoSuchMethodException, IllegalAccessException,
InvocationTargetException, InstantiationException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
- if (parameterTypes == null) {
- parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
+ parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
final Constructor<T> ctor = getAccessibleConstructor(cls, parameterTypes);
if (ctor == null) {
throw new NoSuchMethodException(
@@ -193,14 +187,16 @@ public class ConstructorUtils {
* The constructor signature must match the parameter types exactly.</p>
*
* @param <T> the constructor type
- * @param cls the class to find a constructor for, not null
- * @param parameterTypes the array of parameter types, null treated as empty
- * @return the constructor, null if no matching accessible constructor found
+ * @param cls the class to find a constructor for, not {@code null}
+ * @param parameterTypes the array of parameter types, {@code null} treated as empty
+ * @return the constructor, {@code null} if no matching accessible constructor found
* @see Class#getConstructor
* @see #getAccessibleConstructor(java.lang.reflect.Constructor)
+ * @throws NullPointerException if {@code cls} is {@code null}
*/
public static <T> Constructor<T> getAccessibleConstructor(final Class<T> cls,
final Class<?>... parameterTypes) {
+ Validate.notNull(cls, "class cannot be null");
try {
return getAccessibleConstructor(cls.getConstructor(parameterTypes));
} catch (final NoSuchMethodException e) {
@@ -214,11 +210,13 @@ public class ConstructorUtils {
* <p>This simply ensures that the constructor is accessible.</p>
*
* @param <T> the constructor type
- * @param ctor the prototype constructor object, not null
- * @return the constructor, null if no matching accessible constructor found
+ * @param ctor the prototype constructor object, not {@code null}
+ * @return the constructor, {@code null} if no matching accessible constructor found
* @see java.lang.SecurityManager
+ * @throws NullPointerException if {@code ctor} is {@code null}
*/
public static <T> Constructor<T> getAccessibleConstructor(final Constructor<T> ctor) {
+ Validate.notNull(ctor, "constructor cannot be null");
return MemberUtils.isAccessible(ctor)
&& Modifier.isPublic(ctor.getDeclaringClass().getModifiers()) ? ctor : null;
}
@@ -232,16 +230,18 @@ public class ConstructorUtils {
*
* <p>First it checks if there is a constructor matching the exact signature.
* If not then all the constructors of the class are checked to see if their
- * signatures are assignment compatible with the parameter types.
- * The first assignment compatible matching constructor is returned.</p>
+ * signatures are assignment-compatible with the parameter types.
+ * The first assignment-compatible matching constructor is returned.</p>
*
* @param <T> the constructor type
- * @param cls the class to find a constructor for, not null
+ * @param cls the class to find a constructor for, not {@code null}
* @param parameterTypes find method with compatible parameters
* @return the constructor, null if no matching accessible constructor found
+ * @throws NullPointerException if {@code cls} is {@code null}
*/
public static <T> Constructor<T> getMatchingAccessibleConstructor(final Class<T> cls,
final Class<?>... parameterTypes) {
+ Validate.notNull(cls, "class cannot be null");
// see if we can find the constructor directly
// most of the time this works and it's much faster
try {
Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java?rev=1531403&r1=1531402&r2=1531403&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java Fri Oct 11 19:38:49 2013
@@ -16,15 +16,18 @@
*/
package org.apache.commons.lang3.reflect;
+import java.lang.reflect.AccessibleObject;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.ArrayList;
import java.util.List;
import org.apache.commons.lang3.ClassUtils;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.commons.lang3.Validate;
/**
- * Utilities for working with fields by reflection. Adapted and refactored from the dormant [reflect] Commons sandbox
+ * Utilities for working with {@link Field}s by reflection. Adapted and refactored from the dormant [reflect] Commons sandbox
* component.
* <p>
* The ability is provided to break the scoping restrictions coded by the programmer. This can allow fields to be
@@ -36,24 +39,24 @@ import org.apache.commons.lang3.ClassUti
public class FieldUtils {
/**
- * FieldUtils instances should NOT be constructed in standard programming.
+ * {@link FieldUtils} instances should NOT be constructed in standard programming.
* <p>
- * This constructor is public to permit tools that require a JavaBean instance to operate.
+ * This constructor is {@code public} to permit tools that require a JavaBean instance to operate.</p>
*/
public FieldUtils() {
super();
}
/**
- * Gets an accessible <code>Field</code> by name respecting scope. Superclasses/interfaces will be considered.
+ * Gets an accessible {@link Field} by name respecting scope. Superclasses/interfaces will be considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @return the Field object
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if the class is {@code null}, or the field name is blank or empty
*/
public static Field getField(final Class<?> cls, final String fieldName) {
final Field field = getField(cls, fieldName, false);
@@ -62,27 +65,24 @@ public class FieldUtils {
}
/**
- * Gets an accessible <code>Field</code> by name breaking scope if requested. Superclasses/interfaces will be
+ * Gets an accessible {@link Field} by name, breaking scope if requested. Superclasses/interfaces will be
* considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @return the Field object
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if the class is {@code null}, or the field name is blank or empty or is matched at
+ * multiple places in the inheritance hierarchy
*/
public static Field getField(final Class<?> cls, final String fieldName, final boolean forceAccess) {
- if (cls == null) {
- throw new IllegalArgumentException("The class must not be null");
- }
- if (fieldName == null) {
- throw new IllegalArgumentException("The field name must not be null");
- }
+ Validate.isTrue(cls != null, "The class must not be null");
+ Validate.isTrue(StringUtils.isNotBlank(fieldName), "The field name must not be blank/empty");
// Sun Java 1.3 has a bugged implementation of getField hence we write the
// code ourselves
@@ -120,11 +120,9 @@ public class FieldUtils {
Field match = null;
for (final Class<?> class1 : ClassUtils.getAllInterfaces(cls)) {
try {
- final Field test = ((Class<?>) class1).getField(fieldName);
- if (match != null) {
- throw new IllegalArgumentException("Reference to field " + fieldName + " is ambiguous relative to " + cls +
- "; a matching field exists on two or more implemented interfaces.");
- }
+ final Field test = class1.getField(fieldName);
+ Validate.isTrue(match == null, "Reference to field %s is ambiguous relative to %s"
+ + "; a matching field exists on two or more implemented interfaces.", fieldName, cls);
match = test;
} catch (final NoSuchFieldException ex) { // NOPMD
// ignore
@@ -134,42 +132,38 @@ public class FieldUtils {
}
/**
- * Gets an accessible <code>Field</code> by name respecting scope. Only the specified class will be considered.
+ * Gets an accessible {@link Field} by name respecting scope. Only the specified class will be considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @return the Field object
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if the class is {@code null}, or the field name is blank or empty
*/
public static Field getDeclaredField(final Class<?> cls, final String fieldName) {
return getDeclaredField(cls, fieldName, false);
}
/**
- * Gets an accessible <code>Field</code> by name breaking scope if requested. Only the specified class will be
+ * Gets an accessible {@link Field} by name, breaking scope if requested. Only the specified class will be
* considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. False will only
- * match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @return the Field object
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if the class is {@code null}, or the field name is blank or empty
*/
public static Field getDeclaredField(final Class<?> cls, final String fieldName, final boolean forceAccess) {
- if (cls == null) {
- throw new IllegalArgumentException("The class must not be null");
- }
- if (fieldName == null) {
- throw new IllegalArgumentException("The field name must not be null");
- }
+ Validate.isTrue(cls != null, "The class must not be null");
+ Validate.isTrue(StringUtils.isNotBlank(fieldName), "The field name must not be blank/empty");
try {
// only consider the specified class by using getDeclaredField()
final Field field = cls.getDeclaredField(fieldName);
@@ -191,8 +185,10 @@ public class FieldUtils {
* Gets all fields of the given class and its parents (if any).
*
* @param cls
- * the class to query
- * @return an array of Fields (maybe an empty array).
+ * the {@link Class} to query
+ * @return an array of Fields (possibly empty).
+ * @throws IllegalArgumentException
+ * if the class is {@code null}
* @since 3.2
*/
public static Field[] getAllFields(Class<?> cls) {
@@ -204,15 +200,15 @@ public class FieldUtils {
* Gets all fields of the given class and its parents (if any).
*
* @param cls
- * the class to query
- * @return an array of Fields (maybe an empty array).
+ * the {@link Class} to query
+ * @return an array of Fields (possibly empty).
+ * @throws IllegalArgumentException
+ * if the class is {@code null}
* @since 3.2
*/
public static List<Field> getAllFieldsList(Class<?> cls) {
- if (cls == null) {
- throw new IllegalArgumentException("The class must not be null");
- }
- List<Field> allFields = new ArrayList<Field>();
+ Validate.isTrue(cls != null, "The class must not be null");
+ final List<Field> allFields = new ArrayList<Field>();
Class<?> currentClass = cls;
while (currentClass != null) {
final Field[] declaredFields = currentClass.getDeclaredFields();
@@ -225,13 +221,13 @@ public class FieldUtils {
}
/**
- * Reads an accessible static Field.
+ * Reads an accessible {@code static} {@link Field}.
*
* @param field
* to read
* @return the field value
* @throws IllegalArgumentException
- * if the field is null or not static
+ * if the field is {@code null}, or not {@code static}
* @throws IllegalAccessException
* if the field is not accessible
*/
@@ -240,38 +236,35 @@ public class FieldUtils {
}
/**
- * Reads a static Field.
+ * Reads a static {@link Field}.
*
* @param field
* to read
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
* @return the field value
* @throws IllegalArgumentException
- * if the field is null or not static
+ * if the field is {@code null} or not {@code static}
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static Object readStaticField(final Field field, final boolean forceAccess) throws IllegalAccessException {
- if (field == null) {
- throw new IllegalArgumentException("The field must not be null");
- }
- if (!Modifier.isStatic(field.getModifiers())) {
- throw new IllegalArgumentException("The field '" + field.getName() + "' is not static");
- }
+ Validate.isTrue(field != null, "The field must not be null");
+ Validate.isTrue(Modifier.isStatic(field.getModifiers()), "The field '%s' is not static", field.getName());
return readField(field, (Object) null, forceAccess);
}
/**
- * Reads the named public static field. Superclasses will be considered.
+ * Reads the named {@code public static} {@link Field}. Superclasses will be considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @return the value of the field
* @throws IllegalArgumentException
- * if the class is null, the field name is null or if the field could not be found
+ * if the class is {@code null}, or the field name is blank or empty,
+ * is not {@code static}, or could not be found
* @throws IllegalAccessException
* if the field is not accessible
*/
@@ -280,40 +273,41 @@ public class FieldUtils {
}
/**
- * Reads the named static field. Superclasses will be considered.
+ * Reads the named {@code static} {@link Field}. Superclasses will be considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(false)} method.
+ * {@code false} will only match {@code public} fields.
* @return the Field object
* @throws IllegalArgumentException
- * if the class is null, the field name is null or if the field could not be found
+ * if the class is {@code null}, or the field name is blank or empty,
+ * is not {@code static}, or could not be found
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static Object readStaticField(final Class<?> cls, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
final Field field = getField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate field " + fieldName + " on " + cls);
- }
+ Validate.isTrue(field != null, "Cannot locate field '%s' on %s", fieldName, cls);
// already forced access above, don't repeat it here:
return readStaticField(field, false);
}
/**
- * Gets a static Field value by name. The field must be public. Only the specified class will be considered.
+ * Gets the value of a {@code static} {@link Field} by name. The field must be {@code public}.
+ * Only the specified class will be considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @return the value of the field
* @throws IllegalArgumentException
- * if the class is null, the field name is null or if the field could not be found
+ * if the class is {@code null}, or the field name is blank or empty,
+ * is not {@code static}, or could not be found
* @throws IllegalAccessException
* if the field is not accessible
*/
@@ -322,40 +316,40 @@ public class FieldUtils {
}
/**
- * Gets a static Field value by name. Only the specified class will be considered.
+ * Gets the value of a {@code static} {@link Field} by name.
+ * Only the specified class will be considered.
*
* @param cls
- * the class to reflect, must not be null
+ * the {@link Class} to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @return the Field object
* @throws IllegalArgumentException
- * if the class is null, the field name is null or if the field could not be found
+ * if the class is {@code null}, or the field name is blank or empty,
+ * is not {@code static}, or could not be found
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static Object readDeclaredStaticField(final Class<?> cls, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
final Field field = getDeclaredField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate declared field " + cls.getName() + "." + fieldName);
- }
+ Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
// already forced access above, don't repeat it here:
return readStaticField(field, false);
}
/**
- * Reads an accessible Field.
+ * Reads an accessible {@link Field}.
*
* @param field
* the field to use
* @param target
- * the object to call on, may be null for static fields
+ * the object to call on, may be {@code null} for {@code static} fields
* @return the field value
* @throws IllegalArgumentException
- * if the field is null
+ * if the field is {@code null}
* @throws IllegalAccessException
* if the field is not accessible
*/
@@ -364,24 +358,22 @@ public class FieldUtils {
}
/**
- * Reads a Field.
+ * Reads a {@link Field}.
*
* @param field
* the field to use
* @param target
- * the object to call on, may be null for static fields
+ * the object to call on, may be {@code null} for {@code static} fields
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
* @return the field value
* @throws IllegalArgumentException
- * if the field is null
+ * if the field is {@code null}
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static Object readField(final Field field, final Object target, final boolean forceAccess) throws IllegalAccessException {
- if (field == null) {
- throw new IllegalArgumentException("The field must not be null");
- }
+ Validate.isTrue(field != null, "The field must not be null");
if (forceAccess && !field.isAccessible()) {
field.setAccessible(true);
} else {
@@ -391,268 +383,270 @@ public class FieldUtils {
}
/**
- * Reads the named public field. Superclasses will be considered.
+ * Reads the named {@code public} {@link Field}. Superclasses will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @return the value of the field
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if the class is {@code null}, or
+ * the field name is blank or empty or could not be found
* @throws IllegalAccessException
- * if the named field is not public
+ * if the named field is not {@code public}
*/
public static Object readField(final Object target, final String fieldName) throws IllegalAccessException {
return readField(target, fieldName, false);
}
/**
- * Reads the named field. Superclasses will be considered.
+ * Reads the named {@link Field}. Superclasses will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @return the field value
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if {@code target} is {@code null}, or
+ * the field name is blank or empty or could not be found
* @throws IllegalAccessException
* if the named field is not made accessible
*/
public static Object readField(final Object target, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
- if (target == null) {
- throw new IllegalArgumentException("target object must not be null");
- }
+ Validate.isTrue(target != null, "target object must not be null");
final Class<?> cls = target.getClass();
final Field field = getField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate field " + fieldName + " on " + cls);
- }
+ Validate.isTrue(field != null, "Cannot locate field %s on %s" , fieldName, cls);
// already forced access above, don't repeat it here:
return readField(field, target);
}
/**
- * Reads the named public field. Only the class of the specified object will be considered.
+ * Reads the named {@code public} {@link Field}. Only the class of the specified object will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @return the value of the field
* @throws IllegalArgumentException
- * if the class or field name is null
+ * if {@code target} is {@code null}, or
+ * the field name is blank or empty or could not be found
* @throws IllegalAccessException
- * if the named field is not public
+ * if the named field is not {@code public}
*/
public static Object readDeclaredField(final Object target, final String fieldName) throws IllegalAccessException {
return readDeclaredField(target, fieldName, false);
}
/**
- * <p<>Gets a Field value by name. Only the class of the specified object will be considered.
+ * <p<>Gets a {@link Field} value by name. Only the class of the specified object will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match public fields.
* @return the Field object
* @throws IllegalArgumentException
- * if <code>target</code> or <code>fieldName</code> is null
+ * if {@code target} is {@code null}, or
+ * the field name is blank or empty or could not be found
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static Object readDeclaredField(final Object target, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
- if (target == null) {
- throw new IllegalArgumentException("target object must not be null");
- }
+ Validate.isTrue(target != null, "target object must not be null");
final Class<?> cls = target.getClass();
final Field field = getDeclaredField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate declared field " + cls.getName() + "." + fieldName);
- }
+ Validate.isTrue(field != null, "Cannot locate declared field %s.%s" , cls, fieldName);
// already forced access above, don't repeat it here:
return readField(field, target);
}
/**
- * Writes a public static Field.
+ * Writes a {@code public static} {@link Field}.
*
* @param field
* to write
* @param value
* to set
* @throws IllegalArgumentException
- * if the field is null or not static
+ * if the field is {@code null} or not {@code static},
+ * or {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not public or is final
+ * if the field is not {@code public} or is {@code final}
*/
public static void writeStaticField(final Field field, final Object value) throws IllegalAccessException {
writeStaticField(field, value, false);
}
/**
- * Writes a static Field.
+ * Writes a static {@link Field}.
*
* @param field
* to write
* @param value
* to set
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method. {@code false}
+ * will only match {@code public} fields.
* @throws IllegalArgumentException
- * if the field is null or not static
+ * if the field is {@code null} or not {@code static},
+ * or {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not made accessible or is final
+ * if the field is not made accessible or is {@code final}
*/
public static void writeStaticField(final Field field, final Object value, final boolean forceAccess) throws IllegalAccessException {
- if (field == null) {
- throw new IllegalArgumentException("The field must not be null");
- }
- if (!Modifier.isStatic(field.getModifiers())) {
- throw new IllegalArgumentException("The field '" + field.getName() + "' is not static");
- }
+ Validate.isTrue(field != null, "The field must not be null");
+ Validate.isTrue(Modifier.isStatic(field.getModifiers()), "The field %s.%s is not static",
+ field.getDeclaringClass().getName(), field.getName());
writeField(field, (Object) null, value, forceAccess);
}
/**
- * Writes a named public static Field. Superclasses will be considered.
+ * Writes a named {@code public static} {@link Field}. Superclasses will be considered.
*
* @param cls
- * Class on which the Field is to be found
+ * {@link Class} on which the field is to be found
* @param fieldName
* to write
* @param value
* to set
* @throws IllegalArgumentException
- * if the field cannot be located or is not static
+ * if {@code cls} is {@code null},
+ * the field name is blank or empty,
+ * the field cannot be located or is not {@code static}, or
+ * {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not public or is final
+ * if the field is not {@code public} or is {@code final}
*/
public static void writeStaticField(final Class<?> cls, final String fieldName, final Object value) throws IllegalAccessException {
writeStaticField(cls, fieldName, value, false);
}
/**
- * Writes a named static Field. Superclasses will be considered.
+ * Writes a named {@code static} {@link Field}. Superclasses will be considered.
*
* @param cls
- * Class on which the Field is to be found
+ * {@link Class} on which the field is to be found
* @param fieldName
* to write
* @param value
* to set
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @throws IllegalArgumentException
- * if the field cannot be located or is not static
+ * if {@code cls} is {@code null},
+ * the field name is blank or empty,
+ * the field cannot be located or is not {@code static}, or
+ * {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not made accessible or is final
+ * if the field is not made accessible or is {@code final}
*/
public static void writeStaticField(final Class<?> cls, final String fieldName, final Object value, final boolean forceAccess)
throws IllegalAccessException {
final Field field = getField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate field " + fieldName + " on " + cls);
- }
+ Validate.isTrue(field != null, "Cannot locate field %s on %s", fieldName, cls);
// already forced access above, don't repeat it here:
writeStaticField(field, value);
}
/**
- * Writes a named public static Field. Only the specified class will be considered.
+ * Writes a named {@code public static} {@link Field}. Only the specified class will be considered.
*
* @param cls
- * Class on which the Field is to be found
+ * {@link Class} on which the field is to be found
* @param fieldName
* to write
* @param value
* to set
* @throws IllegalArgumentException
- * if the field cannot be located or is not static
+ * if {@code cls} is {@code null},
+ * the field name is blank or empty,
+ * the field cannot be located or is not {@code static}, or
+ * {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not public or is final
+ * if the field is not {@code public} or is {@code final}
*/
public static void writeDeclaredStaticField(final Class<?> cls, final String fieldName, final Object value) throws IllegalAccessException {
writeDeclaredStaticField(cls, fieldName, value, false);
}
/**
- * Writes a named static Field. Only the specified class will be considered.
+ * Writes a named {@code static} {@link Field}. Only the specified class will be considered.
*
* @param cls
- * Class on which the Field is to be found
+ * {@link Class} on which the field is to be found
* @param fieldName
* to write
* @param value
* to set
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@code AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @throws IllegalArgumentException
- * if the field cannot be located or is not static
+ * if {@code cls} is {@code null},
+ * the field name is blank or empty,
+ * the field cannot be located or is not {@code static}, or
+ * {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not made accessible or is final
+ * if the field is not made accessible or is {@code final}
*/
public static void writeDeclaredStaticField(final Class<?> cls, final String fieldName, final Object value, final boolean forceAccess)
throws IllegalAccessException {
final Field field = getDeclaredField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate declared field " + cls.getName() + "." + fieldName);
- }
+ Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
// already forced access above, don't repeat it here:
writeField(field, (Object) null, value);
}
/**
- * Writes an accessible field.
+ * Writes an accessible {@link Field}.
*
* @param field
* to write
* @param target
- * the object to call on, may be null for static fields
+ * the object to call on, may be {@code null} for {@code static} fields
* @param value
* to set
- * @throws IllegalArgumentException
- * if the field is null
* @throws IllegalAccessException
- * if the field is not accessible or is final
+ * if the field or target is {@code null},
+ * the field is not accessible or is {@code final}, or
+ * {@code value} is not assignable
*/
public static void writeField(final Field field, final Object target, final Object value) throws IllegalAccessException {
writeField(field, target, value, false);
}
/**
- * Writes a field.
+ * Writes a {@link Field}.
*
* @param field
* to write
* @param target
- * the object to call on, may be null for static fields
+ * the object to call on, may be {@code null} for {@code static} fields
* @param value
* to set
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @throws IllegalArgumentException
- * if the field is null
+ * if the field is {@code null} or
+ * {@code value} is not assignable
* @throws IllegalAccessException
- * if the field is not made accessible or is final
+ * if the field is not made accessible or is {@code final}
*/
public static void writeField(final Field field, final Object target, final Object value, final boolean forceAccess)
throws IllegalAccessException {
- if (field == null) {
- throw new IllegalArgumentException("The field must not be null");
- }
+ Validate.isTrue(field != null, "The field must not be null");
if (forceAccess && !field.isAccessible()) {
field.setAccessible(true);
} else {
@@ -662,16 +656,18 @@ public class FieldUtils {
}
/**
- * Writes a public field. Superclasses will be considered.
+ * Writes a {@code public} {@link Field}. Superclasses will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param value
* to set
* @throws IllegalArgumentException
- * if <code>target</code> or <code>fieldName</code> is null
+ * if {@code target} is {@code null},
+ * {@code fieldName} is blank or empty or could not be found,
+ * or {@code value} is not assignable
* @throws IllegalAccessException
* if the field is not accessible
*/
@@ -680,47 +676,47 @@ public class FieldUtils {
}
/**
- * Writes a field. Superclasses will be considered.
+ * Writes a {@link Field}. Superclasses will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param value
* to set
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method. {@code false}
+ * will only match {@code public} fields.
* @throws IllegalArgumentException
- * if <code>target</code> or <code>fieldName</code> is null
+ * if {@code target} is {@code null},
+ * {@code fieldName} is blank or empty or could not be found,
+ * or {@code value} is not assignable
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static void writeField(final Object target, final String fieldName, final Object value, final boolean forceAccess)
throws IllegalAccessException {
- if (target == null) {
- throw new IllegalArgumentException("target object must not be null");
- }
+ Validate.isTrue(target != null, "target object must not be null");
final Class<?> cls = target.getClass();
final Field field = getField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate declared field " + cls.getName() + "." + fieldName);
- }
+ Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
// already forced access above, don't repeat it here:
writeField(field, target, value);
}
/**
- * Writes a public field. Only the specified class will be considered.
+ * Writes a {@code public} {@link Field}. Only the specified class will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param value
* to set
* @throws IllegalArgumentException
- * if <code>target</code> or <code>fieldName</code> is null
+ * if {@code target} is {@code null},
+ * {@code fieldName} is blank or empty or could not be found,
+ * or {@code value} is not assignable
* @throws IllegalAccessException
* if the field is not made accessible
*/
@@ -729,32 +725,30 @@ public class FieldUtils {
}
/**
- * Writes a public field. Only the specified class will be considered.
+ * Writes a {@code public} {@link Field}. Only the specified class will be considered.
*
* @param target
- * the object to reflect, must not be null
+ * the object to reflect, must not be {@code null}
* @param fieldName
* the field name to obtain
* @param value
* to set
* @param forceAccess
- * whether to break scope restrictions using the <code>setAccessible</code> method. <code>False</code>
- * will only match public fields.
+ * whether to break scope restrictions using the {@link AccessibleObject#setAccessible(boolean)} method.
+ * {@code false} will only match {@code public} fields.
* @throws IllegalArgumentException
- * if <code>target</code> or <code>fieldName</code> is null
+ * if {@code target} is {@code null},
+ * {@code fieldName} is blank or empty or could not be found,
+ * or {@code value} is not assignable
* @throws IllegalAccessException
* if the field is not made accessible
*/
public static void writeDeclaredField(final Object target, final String fieldName, final Object value, final boolean forceAccess)
throws IllegalAccessException {
- if (target == null) {
- throw new IllegalArgumentException("target object must not be null");
- }
+ Validate.isTrue(target != null, "target object must not be null");
final Class<?> cls = target.getClass();
final Field field = getDeclaredField(cls, fieldName, forceAccess);
- if (field == null) {
- throw new IllegalArgumentException("Cannot locate declared field " + cls.getName() + "." + fieldName);
- }
+ Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
// already forced access above, don't repeat it here:
writeField(field, target, value);
}
Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MemberUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MemberUtils.java?rev=1531403&r1=1531402&r2=1531403&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MemberUtils.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MemberUtils.java Fri Oct 11 19:38:49 2013
@@ -23,8 +23,8 @@ import java.lang.reflect.Modifier;
import org.apache.commons.lang3.ClassUtils;
/**
- * Contains common code for working with Methods/Constructors, extracted and
- * refactored from <code>MethodUtils</code> when it was imported from Commons
+ * Contains common code for working with {@link Method}s/{@link Constructor}s, extracted and
+ * refactored from {@link MethodUtils} when it was imported from Commons
* BeanUtils.
*
* @since 2.5
@@ -42,11 +42,11 @@ abstract class MemberUtils {
/**
* XXX Default access superclass workaround
*
- * When a public class has a default access superclass with public members,
+ * When a {@code public} class has a default access superclass with {@code public} members,
* these members are accessible. Calling them from compiled code works fine.
* Unfortunately, on some JVMs, using reflection to invoke these members
- * seems to (wrongly) prevent access even when the modifier is public.
- * Calling setAccessible(true) solves the problem but will only work from
+ * seems to (wrongly) prevent access even when the modifier is {@code public}.
+ * Calling {@code setAccessible(true)} solves the problem but will only work from
* sufficiently privileged code. Better workarounds would be gratefully
* accepted.
* @param o the AccessibleObject to set as accessible
@@ -69,16 +69,16 @@ abstract class MemberUtils {
/**
* Returns whether a given set of modifiers implies package access.
* @param modifiers to test
- * @return true unless package/protected/private modifier detected
+ * @return {@code true} unless {@code package}/{@code protected}/{@code private} modifier detected
*/
static boolean isPackageAccess(final int modifiers) {
return (modifiers & ACCESS_TEST) == 0;
}
/**
- * Returns whether a Member is accessible.
+ * Returns whether a {@link Member} is accessible.
* @param m Member to check
- * @return true if <code>m</code> is accessible
+ * @return {@code true} if <code>m</code> is accessible
*/
static boolean isAccessible(final Member m) {
return m != null && Modifier.isPublic(m.getModifiers()) && !m.isSynthetic();
@@ -93,8 +93,8 @@ abstract class MemberUtils {
* @param left the "left" parameter set
* @param right the "right" parameter set
* @param actual the runtime parameter types to match against
- * <code>left</code>/<code>right</code>
- * @return int consistent with <code>compare</code> semantics
+ * {@code left}/{@code right}
+ * @return int consistent with {@code compare} semantics
*/
static int compareParameterTypes(final Class<?>[] left, final Class<?>[] right, final Class<?>[] actual) {
final float leftCost = getTotalTransformationCost(actual, left);
Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java?rev=1531403&r1=1531402&r2=1531403&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java Fri Oct 11 19:38:49 2013
@@ -16,6 +16,7 @@
*/
package org.apache.commons.lang3.reflect;
+import java.lang.reflect.AccessibleObject;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
@@ -33,19 +34,19 @@ import org.apache.commons.lang3.Validate
import org.apache.commons.lang3.ClassUtils.Interfaces;
/**
- * <p>Utility reflection methods focused on methods, originally from Commons BeanUtils.
+ * <p>Utility reflection methods focused on {@link Method}s, originally from Commons BeanUtils.
* Differences from the BeanUtils version may be noted, especially where similar functionality
* already existed within Lang.
* </p>
*
* <h3>Known Limitations</h3>
* <h4>Accessing Public Methods In A Default Access Superclass</h4>
- * <p>There is an issue when invoking public methods contained in a default access superclass on JREs prior to 1.4.
- * Reflection locates these methods fine and correctly assigns them as public.
- * However, an <code>IllegalAccessException</code> is thrown if the method is invoked.</p>
+ * <p>There is an issue when invoking {@code public} methods contained in a default access superclass on JREs prior to 1.4.
+ * Reflection locates these methods fine and correctly assigns them as {@code public}.
+ * However, an {@link IllegalAccessException} is thrown if the method is invoked.</p>
*
- * <p><code>MethodUtils</code> contains a workaround for this situation.
- * It will attempt to call <code>setAccessible</code> on this method.
+ * <p>{@link MethodUtils} contains a workaround for this situation.
+ * It will attempt to call {@link AccessibleObject#setAccessible(boolean)} on this method.
* If this call succeeds, then the method can be invoked as normal.
* This call will only succeed when the application has sufficient security privileges.
* If this call fails then the method may fail.</p>
@@ -56,11 +57,11 @@ import org.apache.commons.lang3.ClassUti
public class MethodUtils {
/**
- * <p>MethodUtils instances should NOT be constructed in standard programming.
+ * <p>{@link MethodUtils} instances should NOT be constructed in standard programming.
* Instead, the class should be used as
- * <code>MethodUtils.getAccessibleMethod(method)</code>.</p>
+ * {@code MethodUtils.getAccessibleMethod(method)}.</p>
*
- * <p>This constructor is public to permit tools that require a JavaBean
+ * <p>This constructor is {@code public} to permit tools that require a JavaBean
* instance to operate.</p>
*/
public MethodUtils() {
@@ -73,8 +74,8 @@ public class MethodUtils {
* <p>This method delegates the method search to {@link #getMatchingAccessibleMethod(Class, String, Class[])}.</p>
*
* <p>This method supports calls to methods taking primitive parameters
- * via passing in wrapping classes. So, for example, a <code>Boolean</code> object
- * would match a <code>boolean</code> primitive.</p>
+ * via passing in wrapping classes. So, for example, a {@code Boolean} object
+ * would match a {@code boolean} primitive.</p>
*
* <p>This is a convenient wrapper for
* {@link #invokeMethod(Object object,String methodName, Object[] args, Class[] parameterTypes)}.
@@ -92,9 +93,7 @@ public class MethodUtils {
public static Object invokeMethod(final Object object, final String methodName,
Object... args) throws NoSuchMethodException,
IllegalAccessException, InvocationTargetException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
final Class<?>[] parameterTypes = ClassUtils.toClass(args);
return invokeMethod(object, methodName, args, parameterTypes);
}
@@ -105,8 +104,8 @@ public class MethodUtils {
* <p>This method delegates the method search to {@link #getMatchingAccessibleMethod(Class, String, Class[])}.</p>
*
* <p>This method supports calls to methods taking primitive parameters
- * via passing in wrapping classes. So, for example, a <code>Boolean</code> object
- * would match a <code>boolean</code> primitive.</p>
+ * via passing in wrapping classes. So, for example, a {@code Boolean} object
+ * would match a {@code boolean} primitive.</p>
*
* @param object invoke method on this object
* @param methodName get method with this name
@@ -122,12 +121,8 @@ public class MethodUtils {
Object[] args, Class<?>[] parameterTypes)
throws NoSuchMethodException, IllegalAccessException,
InvocationTargetException {
- if (parameterTypes == null) {
- parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY;
- }
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
+ args = ArrayUtils.nullToEmpty(args);
final Method method = getMatchingAccessibleMethod(object.getClass(),
methodName, parameterTypes);
if (method == null) {
@@ -143,11 +138,11 @@ public class MethodUtils {
* types.</p>
*
* <p>This uses reflection to invoke the method obtained from a call to
- * <code>getAccessibleMethod()</code>.</p>
+ * {@link #getAccessibleMethod}(Class,String,Class[])}.</p>
*
* @param object invoke method on this object
* @param methodName get method with this name
- * @param args use these arguments - treat null as empty array
+ * @param args use these arguments - treat {@code null} as empty array
* @return The value returned by the invoked method
*
* @throws NoSuchMethodException if there is no such accessible method
@@ -159,9 +154,7 @@ public class MethodUtils {
public static Object invokeExactMethod(final Object object, final String methodName,
Object... args) throws NoSuchMethodException,
IllegalAccessException, InvocationTargetException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
final Class<?>[] parameterTypes = ClassUtils.toClass(args);
return invokeExactMethod(object, methodName, args, parameterTypes);
}
@@ -171,12 +164,12 @@ public class MethodUtils {
* types given.</p>
*
* <p>This uses reflection to invoke the method obtained from a call to
- * <code>getAccessibleMethod()</code>.</p>
+ * {@link #getAccessibleMethod(Class,String,Class[])}.</p>
*
* @param object invoke method on this object
* @param methodName get method with this name
* @param args use these arguments - treat null as empty array
- * @param parameterTypes match these parameters - treat null as empty array
+ * @param parameterTypes match these parameters - treat {@code null} as empty array
* @return The value returned by the invoked method
*
* @throws NoSuchMethodException if there is no such accessible method
@@ -189,12 +182,8 @@ public class MethodUtils {
Object[] args, Class<?>[] parameterTypes)
throws NoSuchMethodException, IllegalAccessException,
InvocationTargetException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
- if (parameterTypes == null) {
- parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
+ parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
final Method method = getAccessibleMethod(object.getClass(), methodName,
parameterTypes);
if (method == null) {
@@ -206,7 +195,7 @@ public class MethodUtils {
}
/**
- * <p>Invokes a static method whose parameter types match exactly the parameter
+ * <p>Invokes a {@code static} method whose parameter types match exactly the parameter
* types given.</p>
*
* <p>This uses reflection to invoke the method obtained from a call to
@@ -214,8 +203,8 @@ public class MethodUtils {
*
* @param cls invoke static method on this class
* @param methodName get method with this name
- * @param args use these arguments - treat null as empty array
- * @param parameterTypes match these parameters - treat null as empty array
+ * @param args use these arguments - treat {@code null} as empty array
+ * @param parameterTypes match these parameters - treat {@code null as empty array
* @return The value returned by the invoked method
*
* @throws NoSuchMethodException if there is no such accessible method
@@ -228,12 +217,8 @@ public class MethodUtils {
Object[] args, Class<?>[] parameterTypes)
throws NoSuchMethodException, IllegalAccessException,
InvocationTargetException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
- if (parameterTypes == null) {
- parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
+ parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
final Method method = getAccessibleMethod(cls, methodName, parameterTypes);
if (method == null) {
throw new NoSuchMethodException("No such accessible method: "
@@ -243,13 +228,13 @@ public class MethodUtils {
}
/**
- * <p>Invokes a named static method whose parameter type matches the object type.</p>
+ * <p>Invokes a named {@code static} method whose parameter type matches the object type.</p>
*
* <p>This method delegates the method search to {@link #getMatchingAccessibleMethod(Class, String, Class[])}.</p>
*
* <p>This method supports calls to methods taking primitive parameters
- * via passing in wrapping classes. So, for example, a <code>Boolean</code> class
- * would match a <code>boolean</code> primitive.</p>
+ * via passing in wrapping classes. So, for example, a {@code Boolean} class
+ * would match a {@code boolean} primitive.</p>
*
* <p>This is a convenient wrapper for
* {@link #invokeStaticMethod(Class objectClass,String methodName,Object [] args,Class[] parameterTypes)}.
@@ -257,7 +242,7 @@ public class MethodUtils {
*
* @param cls invoke static method on this class
* @param methodName get method with this name
- * @param args use these arguments - treat null as empty array
+ * @param args use these arguments - treat {@code null} as empty array
* @return The value returned by the invoked method
*
* @throws NoSuchMethodException if there is no such accessible method
@@ -269,27 +254,25 @@ public class MethodUtils {
public static Object invokeStaticMethod(final Class<?> cls, final String methodName,
Object... args) throws NoSuchMethodException,
IllegalAccessException, InvocationTargetException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
final Class<?>[] parameterTypes = ClassUtils.toClass(args);
return invokeStaticMethod(cls, methodName, args, parameterTypes);
}
/**
- * <p>Invokes a named static method whose parameter type matches the object type.</p>
+ * <p>Invokes a named {@code static} method whose parameter type matches the object type.</p>
*
* <p>This method delegates the method search to {@link #getMatchingAccessibleMethod(Class, String, Class[])}.</p>
*
* <p>This method supports calls to methods taking primitive parameters
- * via passing in wrapping classes. So, for example, a <code>Boolean</code> class
- * would match a <code>boolean</code> primitive.</p>
+ * via passing in wrapping classes. So, for example, a {@code Boolean} class
+ * would match a {@code boolean} primitive.</p>
*
*
* @param cls invoke static method on this class
* @param methodName get method with this name
- * @param args use these arguments - treat null as empty array
- * @param parameterTypes match these parameters - treat null as empty array
+ * @param args use these arguments - treat {@code null} as empty array
+ * @param parameterTypes match these parameters - treat {@code null} as empty array
* @return The value returned by the invoked method
*
* @throws NoSuchMethodException if there is no such accessible method
@@ -302,12 +285,8 @@ public class MethodUtils {
Object[] args, Class<?>[] parameterTypes)
throws NoSuchMethodException, IllegalAccessException,
InvocationTargetException {
- if (parameterTypes == null) {
- parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY;
- }
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
+ parameterTypes = ArrayUtils.nullToEmpty(parameterTypes);
final Method method = getMatchingAccessibleMethod(cls, methodName,
parameterTypes);
if (method == null) {
@@ -318,7 +297,7 @@ public class MethodUtils {
}
/**
- * <p>Invokes a static method whose parameter types match exactly the object
+ * <p>Invokes a {@code static} method whose parameter types match exactly the object
* types.</p>
*
* <p>This uses reflection to invoke the method obtained from a call to
@@ -326,7 +305,7 @@ public class MethodUtils {
*
* @param cls invoke static method on this class
* @param methodName get method with this name
- * @param args use these arguments - treat null as empty array
+ * @param args use these arguments - treat {@code null} as empty array
* @return The value returned by the invoked method
*
* @throws NoSuchMethodException if there is no such accessible method
@@ -338,19 +317,17 @@ public class MethodUtils {
public static Object invokeExactStaticMethod(final Class<?> cls, final String methodName,
Object... args) throws NoSuchMethodException,
IllegalAccessException, InvocationTargetException {
- if (args == null) {
- args = ArrayUtils.EMPTY_OBJECT_ARRAY;
- }
+ args = ArrayUtils.nullToEmpty(args);
final Class<?>[] parameterTypes = ClassUtils.toClass(args);
return invokeExactStaticMethod(cls, methodName, args, parameterTypes);
}
/**
* <p>Returns an accessible method (that is, one that can be invoked via
- * reflection) with given name and parameters. If no such method
- * can be found, return <code>null</code>.
- * This is just a convenient wrapper for
- * {@link #getAccessibleMethod(Method method)}.</p>
+ * reflection) with given name and parameters. If no such method
+ * can be found, return {@code null}.
+ * This is just a convenience wrapper for
+ * {@link #getAccessibleMethod(Method)}.</p>
*
* @param cls get method from this class
* @param methodName get method with this name
@@ -369,8 +346,8 @@ public class MethodUtils {
/**
* <p>Returns an accessible method (that is, one that can be invoked via
- * reflection) that implements the specified Method. If no such method
- * can be found, return <code>null</code>.</p>
+ * reflection) that implements the specified Method. If no such method
+ * can be found, return {@code null}.</p>
*
* @param method The method that we wish to call
* @return The accessible method
@@ -402,12 +379,12 @@ public class MethodUtils {
/**
* <p>Returns an accessible method (that is, one that can be invoked via
* reflection) by scanning through the superclasses. If no such method
- * can be found, return <code>null</code>.</p>
+ * can be found, return {@code null}.</p>
*
* @param cls Class to be checked
* @param methodName Method name of the method we wish to call
* @param parameterTypes The parameter type signatures
- * @return the accessible method or <code>null</code> if not found
+ * @return the accessible method or {@code null} if not found
*/
private static Method getAccessibleMethodFromSuperclass(final Class<?> cls,
final String methodName, final Class<?>... parameterTypes) {
@@ -428,22 +405,20 @@ public class MethodUtils {
/**
* <p>Returns an accessible method (that is, one that can be invoked via
* reflection) that implements the specified method, by scanning through
- * all implemented interfaces and subinterfaces. If no such method
- * can be found, return <code>null</code>.</p>
+ * all implemented interfaces and subinterfaces. If no such method
+ * can be found, return {@code null}.</p>
*
- * <p>There isn't any good reason why this method must be private.
+ * <p>There isn't any good reason why this method must be {@code private}.
* It is because there doesn't seem any reason why other classes should
* call this rather than the higher level methods.</p>
*
* @param cls Parent class for the interfaces to be checked
* @param methodName Method name of the method we wish to call
* @param parameterTypes The parameter type signatures
- * @return the accessible method or <code>null</code> if not found
+ * @return the accessible method or {@code null} if not found
*/
private static Method getAccessibleMethodFromInterfaceNest(Class<?> cls,
final String methodName, final Class<?>... parameterTypes) {
- Method method = null;
-
// Search up the superclass chain
for (; cls != null; cls = cls.getSuperclass()) {
@@ -456,7 +431,7 @@ public class MethodUtils {
}
// Does the method exist on this interface?
try {
- method = interfaces[i].getDeclaredMethod(methodName,
+ return interfaces[i].getDeclaredMethod(methodName,
parameterTypes);
} catch (final NoSuchMethodException e) { // NOPMD
/*
@@ -464,18 +439,15 @@ public class MethodUtils {
* method returns null.
*/
}
- if (method != null) {
- break;
- }
// Recursively check our parent interfaces
- method = getAccessibleMethodFromInterfaceNest(interfaces[i],
+ Method method = getAccessibleMethodFromInterfaceNest(interfaces[i],
methodName, parameterTypes);
if (method != null) {
- break;
+ return method;
}
}
}
- return method;
+ return null;
}
/**
@@ -490,7 +462,7 @@ public class MethodUtils {
* #invokeMethod(Object object, String methodName, Object[] args, Class[] parameterTypes)}.
*
* <p>This method can match primitive parameter by passing in wrapper classes.
- * For example, a <code>Boolean</code> will match a primitive <code>boolean</code>
+ * For example, a {@code Boolean} will match a primitive {@code boolean}
* parameter.
*
* @param cls find method in this class
@@ -531,8 +503,10 @@ public class MethodUtils {
/**
* Get the hierarchy of overridden methods down to {@code result} respecting generics.
* @param method lowest to consider
- * @param interfacesBehavior whether to search interfaces
- * @return Collection<Method> in ascending order from sub- to superclass
+ * @param interfacesBehavior whether to search interfaces, {@code null} {@code implies} false
+ * @return Set<Method> in ascending order from sub- to superclass
+ * @throws NullPointerException if the specified method is {@code null}
+ * @since 3.2
*/
public static Set<Method> getOverrideHierarchy(final Method method, Interfaces interfacesBehavior) {
Validate.notNull(method);
@@ -568,7 +542,6 @@ public class MethodUtils {
}
result.add(m);
}
-
return result;
}