Author: niallp Date: Sun Jan 9 02:00:25 2011 New Revision: 1056863 URL: http://svn.apache.org/viewvc?rev=1056863&view=rev Log: port r983709 to LANG 2.x branch - Javadoc and formatting changes
Modified: commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/ConstructorUtils.java Modified: commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/ConstructorUtils.java URL: http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/ConstructorUtils.java?rev=1056863&r1=1056862&r2=1056863&view=diff ============================================================================== --- commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/ConstructorUtils.java (original) +++ commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/ConstructorUtils.java Sun Jan 9 02:00:25 2011 @@ -24,20 +24,22 @@ import org.apache.commons.lang.ArrayUtil import org.apache.commons.lang.ClassUtils; /** - * <p> Utility reflection methods focussed on constructors, modelled 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 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 call succeeds, then the method can be invoked as normal. - * This call will only succeed when the application has sufficient security privilages. - * If this call fails then a warning will be logged and the method may fail.</p> - * + * <p> Utility reflection methods focussed on constructors, modelled 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 + * 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 + * call succeeds, then the method can be invoked as normal. This call will only + * succeed when the application has sufficient security privilages. If this call + * fails then a warning will be logged and the method may fail.</p> + * * @author Apache Software Foundation * @author Craig R. McClanahan * @author Ralph Schaer @@ -53,10 +55,10 @@ import org.apache.commons.lang.ClassUtil public class ConstructorUtils { /** - * <p>ConstructorUtils instances should NOT be constructed in standard programming. - * Instead, the class should be used as + * <p>ConstructorUtils instances should NOT be constructed in standard + * programming. Instead, the class should be used as * <code>ConstructorUtils.invokeConstructor(cls, args)</code>.</p> - * + * * <p>This constructor is public to permit tools that require a JavaBean * instance to operate.</p> */ @@ -65,12 +67,14 @@ public class ConstructorUtils { } /** - * <p>Convenience method returning new instance of <code>klazz</code> using a single argument constructor. - * The formal parameter type is inferred from the actual values of <code>arg</code>. - * See {...@link #invokeExactConstructor(Class, Object[], Class[])} for more details.</p> - * + * <p>Returns new instance of <code>klazz</code> created using the actual + * arguments <code>args</code>. The formal parameter types are inferred from + * the actual values of <code>args</code>. See + * {...@link #invokeExactConstructor(Class, Object[], Class[])} for more + * details.</p> + * * <p>The signatures should be assignment compatible.</p> - * + * * @param cls the class to be constructed. * @param arg the actual argument * @return new instance of <code>klazz</code> @@ -89,26 +93,30 @@ public class ConstructorUtils { } /** - * <p>Returns new instance of <code>klazz</code> created using the actual arguments <code>args</code>. - * The formal parameter types are inferred from the actual values of <code>args</code>. - * See {...@link #invokeExactConstructor(Class, Object[], Class[])} for more details.</p> - * + * <p>Returns new instance of <code>klazz</code> created using the actual + * arguments <code>args</code>. The formal parameter types are inferred from + * the actual values of <code>args</code>. See + * {...@link #invokeExactConstructor(Class, Object[], Class[])} for more + * details.</p> * <p>The signatures should be assignment compatible.</p> * * @param cls the class to be constructed. * @param args actual argument array * @return new instance of <code>klazz</code> - * + * * @throws NoSuchMethodException If the constructor cannot be found - * @throws IllegalAccessException If an error occurs accessing the constructor - * @throws InvocationTargetException If an error occurs invoking the constructor + * @throws IllegalAccessException If an error occurs accessing the + * constructor + * @throws InvocationTargetException If an error occurs invoking the + * constructor * @throws InstantiationException If an error occurs instantiating the class - * - * @see #invokeConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[]) + * + * @see #invokeConstructor(java.lang.Class, java.lang.Object[], + * java.lang.Class[]) */ public static Object invokeConstructor(Class cls, Object[] args) - throws NoSuchMethodException, IllegalAccessException, - InvocationTargetException, InstantiationException { + throws NoSuchMethodException, IllegalAccessException, InvocationTargetException, + InstantiationException { if (null == args) { args = ArrayUtils.EMPTY_OBJECT_ARRAY; } @@ -121,24 +129,24 @@ public class ConstructorUtils { /** * <p>Returns new instance of <code>klazz</code> created using constructor - * with signature <code>parameterTypes</code> and actual arguments <code>args</code>.</p> - * + * with signature <code>parameterTypes</code> and actual arguments + * <code>args</code>.</p> + * * <p>The signatures should be assignment compatible.</p> - * + * * @param cls the class to be constructed. * @param args actual argument array * @param parameterTypes parameter types array * @return new instance of <code>klazz</code> - * + * * @throws NoSuchMethodException if matching constructor cannot be found * @throws IllegalAccessException thrown on the constructor's invocation * @throws InvocationTargetException thrown on the constructor's invocation * @throws InstantiationException thrown on the constructor's invocation * @see Constructor#newInstance */ - public static Object invokeConstructor(Class cls, Object[] args, - Class[] parameterTypes) throws NoSuchMethodException, - IllegalAccessException, InvocationTargetException, + public static Object invokeConstructor(Class cls, Object[] args, Class[] parameterTypes) + throws NoSuchMethodException, IllegalAccessException, InvocationTargetException, InstantiationException { if (parameterTypes == null) { parameterTypes = ArrayUtils.EMPTY_CLASS_ARRAY; @@ -148,20 +156,21 @@ public class ConstructorUtils { } Constructor ctor = getMatchingAccessibleConstructor(cls, parameterTypes); if (null == ctor) { - throw new NoSuchMethodException( - "No such accessible constructor on object: " - + cls.getName()); + throw new NoSuchMethodException("No such accessible constructor on object: " + + cls.getName()); } return ctor.newInstance(args); } /** - * <p>Convenience method returning new instance of <code>klazz</code> using a single argument constructor. - * The formal parameter type is inferred from the actual values of <code>arg</code>. - * See {...@link #invokeExactConstructor(Class, Object[], Class[])} for more details.</p> - * + * <p>Returns new instance of <code>klazz</code> created using the actual + * arguments <code>args</code>. The formal parameter types are inferred from + * the actual values of <code>args</code>. See + * {...@link #invokeExactConstructor(Class, Object[], Class[])} for more + * details.</p> + * * <p>The signatures should match exactly.</p> - * + * * @param cls the class to be constructed. * @param arg the actual argument * @return new instance of <code>klazz</code> @@ -180,26 +189,31 @@ public class ConstructorUtils { } /** - * <p>Returns new instance of <code>klazz</code> created using the actual arguments <code>args</code>. - * The formal parameter types are inferred from the actual values of <code>args</code>. - * See {...@link #invokeExactConstructor(Class, Object[], Class[])} for more details.</p> + * <p>Returns new instance of <code>klazz</code> created using the actual + * arguments <code>args</code>. The formal parameter types are inferred from + * the actual values of <code>args</code>. See + * {...@link #invokeExactConstructor(Class, Object[], Class[])} for more + * details.</p> * * <p>The signatures should match exactly.</p> * * @param cls the class to be constructed. * @param args actual argument array * @return new instance of <code>klazz</code> - * + * * @throws NoSuchMethodException If the constructor cannot be found - * @throws IllegalAccessException If an error occurs accessing the constructor - * @throws InvocationTargetException If an error occurs invoking the constructor + * @throws IllegalAccessException If an error occurs accessing the + * constructor + * @throws InvocationTargetException If an error occurs invoking the + * constructor * @throws InstantiationException If an error occurs instantiating the class - * - * @see #invokeExactConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[]) + * + * @see #invokeExactConstructor(java.lang.Class, java.lang.Object[], + * java.lang.Class[]) */ public static Object invokeExactConstructor(Class cls, Object[] args) - throws NoSuchMethodException, IllegalAccessException, - InvocationTargetException, InstantiationException { + throws NoSuchMethodException, IllegalAccessException, InvocationTargetException, + InstantiationException { if (null == args) { args = ArrayUtils.EMPTY_OBJECT_ARRAY; } @@ -215,14 +229,14 @@ public class ConstructorUtils { * <p>Returns new instance of <code>klazz</code> created using constructor * with signature <code>parameterTypes</code> and actual arguments * <code>args</code>.</p> - * + * * <p>The signatures should match exactly.</p> - * + * * @param cls the class to be constructed. * @param args actual argument array * @param parameterTypes parameter types array * @return new instance of <code>klazz</code> - * + * * @throws NoSuchMethodException if matching constructor cannot be found * @throws IllegalAccessException thrown on the constructor's invocation * @throws InvocationTargetException thrown on the constructor's invocation @@ -230,9 +244,8 @@ public class ConstructorUtils { * @see Constructor#newInstance */ public static Object invokeExactConstructor(Class cls, Object[] args, - Class[] parameterTypes) throws NoSuchMethodException, - IllegalAccessException, InvocationTargetException, - InstantiationException { + Class[] parameterTypes) throws NoSuchMethodException, IllegalAccessException, + InvocationTargetException, InstantiationException { if (args == null) { args = ArrayUtils.EMPTY_OBJECT_ARRAY; } @@ -241,9 +254,8 @@ public class ConstructorUtils { } Constructor ctor = getAccessibleConstructor(cls, parameterTypes); if (null == ctor) { - throw new NoSuchMethodException( - "No such accessible constructor on object: " - + cls.getName()); + throw new NoSuchMethodException("No such accessible constructor on object: " + + cls.getName()); } return ctor.newInstance(args); } @@ -286,24 +298,24 @@ public class ConstructorUtils { */ public static Constructor getAccessibleConstructor(Constructor ctor) { return MemberUtils.isAccessible(ctor) - && Modifier.isPublic(ctor.getDeclaringClass().getModifiers()) ? ctor - : null; + && Modifier.isPublic(ctor.getDeclaringClass().getModifiers()) ? ctor : null; } /** - * <p>Find an accessible constructor with compatible parameters. - * Compatible parameters mean that every method parameter is assignable from - * the given parameters. In other words, it finds constructor that will take - * the parameters given.</p> - * + * <p>Find an accessible constructor with compatible parameters. Compatible + * parameters mean that every method parameter is assignable from the given + * parameters. In other words, it finds constructor that will take the + * parameters given.</p> + * * <p>First it checks if there is constructor matching the exact signature. - * If no such, all the constructors of the class are tested if their signatures - * are assignment compatible with the parameter types. - * The first matching constructor is returned.</p> - * + * If no such, all the constructors of the class are tested if their + * signatures are assignment compatible with the parameter types. The first + * matching constructor is returned.</p> + * * @param cls find constructor for this class * @param parameterTypes find method with compatible parameters - * @return a valid Constructor object. If there's no matching constructor, returns <code>null</code>. + * @return a valid Constructor object. If there's no matching constructor, + * returns <code>null</code>. */ public static Constructor getMatchingAccessibleConstructor(Class cls, Class[] parameterTypes) { @@ -318,17 +330,17 @@ public class ConstructorUtils { Constructor result = null; // search through all constructors Constructor[] ctors = cls.getConstructors(); + // return best match: for (int i = 0; i < ctors.length; i++) { + // compare parameters - if (ClassUtils.isAssignable(parameterTypes, ctors[i] - .getParameterTypes(), true)) { - // get accessible version of method + if (ClassUtils.isAssignable(parameterTypes, ctors[i].getParameterTypes(), true)) { + // get accessible version of constructor Constructor ctor = getAccessibleConstructor(ctors[i]); if (ctor != null) { MemberUtils.setAccessibleWorkaround(ctor); if (result == null - || MemberUtils.compareParameterTypes(ctor - .getParameterTypes(), result + || MemberUtils.compareParameterTypes(ctor.getParameterTypes(), result .getParameterTypes(), parameterTypes) < 0) { result = ctor; }