Class ConstructorUtils

java.lang.Object

org.apache.commons.lang3.reflect.ConstructorUtils

public class ConstructorUtils
extends Object

Utility reflection methods focused on constructors, modeled after MethodUtils.

Known Limitations

Accessing Constructors In A Non-Public Class

Constructors in non-public classes (such as package-private classes or classes enclosed in non-public classes) are not accessible. Methods such as getAccessibleConstructor(Class, Class[]) and getMatchingAccessibleConstructor(Class, Class[]) return null when invoked on non-public classes. Consequently, invocation methods such as invokeConstructor(Class, Object...) and invokeExactConstructor(Class, Object...) throw a NoSuchMethodException.

Since:

2.5

Constructor Summary

Constructors

Constructor	Description
ConstructorUtils()	Deprecated. TODO Make private in 4.0.

Method Summary

Modifier and Type	Method	Description
static <T> Constructor<T>	getAccessibleConstructor(Class<T> cls, Class<?>... parameterTypes)	Gets a constructor given a class and signature, checking accessibility.
static <T> Constructor<T>	getAccessibleConstructor(Constructor<T> ctor)	Gets the specified constructor if it is accessible; otherwise, returns null.
static <T> Constructor<T>	getMatchingAccessibleConstructor(Class<T> cls, Class<?>... parameterTypes)	Gets an accessible constructor with compatible parameters.
static <T> T	invokeConstructor(Class<T> cls, Object... args)	Returns a new instance of the specified class inferring the right constructor from the types of the arguments.
static <T> T	invokeConstructor(Class<T> cls, Object[] args, Class<?>[] parameterTypes)	Returns a new instance of the specified class choosing the right constructor from the list of parameter types.
static <T> T	invokeExactConstructor(Class<T> cls, Object... args)	Returns a new instance of the specified class inferring the right constructor from the types of the arguments.
static <T> T	invokeExactConstructor(Class<T> cls, Object[] args, Class<?>[] parameterTypes)	Returns a new instance of the specified class choosing the right constructor from the list of parameter types.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ConstructorUtils

@Deprecated
public ConstructorUtils()

Deprecated.

TODO Make private in 4.0.

ConstructorUtils instances should NOT be constructed in standard programming. Instead, the class should be used as ConstructorUtils.invokeConstructor(cls, args).

This constructor is public to permit tools that require a JavaBean instance to operate.

Method Details

getAccessibleConstructor

public static <T> Constructor<T> getAccessibleConstructor(Class<T> cls,
 Class<?>... parameterTypes)

Gets a constructor given a class and signature, checking accessibility.

This finds the constructor and ensures that it is accessible. The constructor signature must match the parameter types exactly.

Type Parameters:

T - the constructor type.

Parameters:

cls - The class to find a constructor for, not null.

parameterTypes - The array of parameter types, null treated as empty.

Returns:

The constructor, null if no matching accessible constructor found.

Throws:

NullPointerException - Thrown if cls is null.

SecurityException - Thrown if a security manager is present and the caller's class loader is not the same as or an ancestor of the class loader for the class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• Class.getConstructor(Class...)
• getAccessibleConstructor(java.lang.reflect.Constructor)

getAccessibleConstructor

public static <T> Constructor<T> getAccessibleConstructor(Constructor<T> ctor)

Gets the specified constructor if it is accessible; otherwise, returns null.

This simply ensures that the constructor is accessible.

Type Parameters:

T - the constructor type.

Parameters:

ctor - The prototype constructor object, not null.

Returns:

The constructor, null if no matching accessible constructor found.

Throws:

NullPointerException - Thrown if ctor is null.

SecurityException - Thrown if a security manager is present and a caller's class loader is not the same as or an ancestor of the class loader for a class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• SecurityManager

getMatchingAccessibleConstructor

public static <T> Constructor<T> getMatchingAccessibleConstructor(Class<T> cls,
 Class<?>... parameterTypes)

Gets an accessible constructor with compatible parameters.

This checks all the constructor and finds one with compatible parameters This requires that every parameter is assignable from the given parameter types. This is a more flexible search than the normal exact matching algorithm.

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.

Type Parameters:

T - the constructor type.

Parameters:

cls - The class to find a constructor for, not null.

parameterTypes - find method with compatible parameters.

Returns:

The constructor, null if no matching accessible constructor found.

Throws:

NullPointerException - Thrown if cls is null

SecurityException - Thrown if a security manager is present and the caller's class loader is not the same as or an ancestor of the class loader for the class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• SecurityManager.checkPackageAccess(String)

invokeConstructor

public static <T> T invokeConstructor(Class<T> cls,
 Object... args)
                               throws NoSuchMethodException,
IllegalAccessException,
InvocationTargetException,
InstantiationException

Returns a new instance of the specified class inferring the right constructor from the types of the arguments.

This locates and calls a constructor. The constructor signature must match the argument types by assignment compatibility.

Type Parameters:

T - the type to be constructed.

Parameters:

cls - The class to be constructed, not null.

args - The array of arguments, null treated as empty.

Returns:

new instance of cls, not null.

Throws:

NullPointerException - Thrown if cls is null.

NoSuchMethodException - Thrown if a matching constructor cannot be found.

IllegalAccessException - Thrown if the found Constructor is enforcing Java language access control and the underlying constructor is inaccessible.

IllegalArgumentException - Thrown if:

• the number of actual and formal parameters differ; or
• an unwrapping conversion for primitive arguments fails; or
• after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.

InstantiationException - Thrown if the class that declares the underlying constructor represents an abstract class.

InvocationTargetException - Thrown if the underlying constructor throws an exception.

ExceptionInInitializerError - Thrown if the initialization provoked by this method fails.

SecurityException - Thrown if a security manager is present and the caller's class loader is not the same as or an ancestor of the class loader for the class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• invokeConstructor(Class, Object[], Class[])

invokeConstructor

public static <T> T invokeConstructor(Class<T> cls,
 Object[] args,
 Class<?>[] parameterTypes)
                               throws NoSuchMethodException,
IllegalAccessException,
InvocationTargetException,
InstantiationException

Returns a new instance of the specified class choosing the right constructor from the list of parameter types.

This locates and calls a constructor. The constructor signature must match the parameter types by assignment compatibility.

Type Parameters:

T - the type to be constructed.

Parameters:

cls - The class to be constructed, not null.

args - The array of arguments, null treated as empty.

parameterTypes - The array of parameter types, null treated as empty.

Returns:

new instance of cls, not null

Throws:

NullPointerException - Thrown if cls is null.

NoSuchMethodException - Thrown if a matching constructor cannot be found.

IllegalAccessException - Thrown if the found Constructor is enforcing Java language access control and the underlying constructor is inaccessible.

IllegalArgumentException - Thrown if:

• the number of actual and formal parameters differ; or
• an unwrapping conversion for primitive arguments fails; or
• after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.

InstantiationException - Thrown if the class that declares the underlying constructor represents an abstract class.

InvocationTargetException - Thrown if the underlying constructor throws an exception.

ExceptionInInitializerError - Thrown if the initialization provoked by this method fails.

SecurityException - Thrown if a security manager is present and the caller's class loader is not the same as or an ancestor of the class loader for the class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• Constructor.newInstance(Object...)
• Constructor.newInstance(Object...)

invokeExactConstructor

public static <T> T invokeExactConstructor(Class<T> cls,
 Object... args)
                                    throws NoSuchMethodException,
IllegalAccessException,
InvocationTargetException,
InstantiationException

Returns a new instance of the specified class inferring the right constructor from the types of the arguments.

This locates and calls a constructor. The constructor signature must match the argument types exactly.

Type Parameters:

T - the type to be constructed.

Parameters:

cls - The class to be constructed, not null.

args - The array of arguments, null treated as empty.

Returns:

new instance of cls, not null.

Throws:

NullPointerException - Thrown if cls is null.

NoSuchMethodException - Thrown if a matching constructor cannot be found.

IllegalAccessException - Thrown if the found Constructor is enforcing Java language access control and the underlying constructor is inaccessible.

IllegalArgumentException - Thrown if:

• the number of actual and formal parameters differ; or
• an unwrapping conversion for primitive arguments fails; or
• after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.

InstantiationException - Thrown if the class that declares the underlying constructor represents an abstract class.

InvocationTargetException - Thrown if the underlying constructor throws an exception.

ExceptionInInitializerError - Thrown if the initialization provoked by this method fails.

SecurityException - Thrown if a security manager is present and the caller's class loader is not the same as or an ancestor of the class loader for the class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• Constructor.newInstance(Object...)
• invokeExactConstructor(Class, Object[], Class[])

invokeExactConstructor

public static <T> T invokeExactConstructor(Class<T> cls,
 Object[] args,
 Class<?>[] parameterTypes)
                                    throws NoSuchMethodException,
IllegalAccessException,
InvocationTargetException,
InstantiationException

Returns a new instance of the specified class choosing the right constructor from the list of parameter types.

This locates and calls a constructor. The constructor signature must match the parameter types exactly.

Type Parameters:

T - the type to construct.

Parameters:

cls - The class to construct, not null.

args - The array of arguments, null treated as empty.

parameterTypes - The array of parameter types, null treated as empty.

Returns:

new instance of cls, not null.

Throws:

NullPointerException - Thrown if cls is null.

NoSuchMethodException - Thrown if a matching constructor cannot be found.

IllegalAccessException - Thrown if the found Constructor is enforcing Java language access control and the underlying constructor is inaccessible.

IllegalArgumentException - Thrown if:

• the number of actual and formal parameters differ; or
• an unwrapping conversion for primitive arguments fails; or
• after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.

InstantiationException - Thrown if the class that declares the underlying constructor represents an abstract class.

InvocationTargetException - Thrown if the underlying constructor throws an exception.

ExceptionInInitializerError - Thrown if the initialization provoked by this method fails.

SecurityException - Thrown if a security manager is present and the caller's class loader is not the same as or an ancestor of the class loader for the class and invocation of SecurityManager.checkPackageAccess(String) denies access to the package of the class.

See Also:

• Constructor.newInstance(Object...)