Top Description Constructors Methods
org.apache.commons.lang3.reflect

public Class ConstructorUtils

extends Object
Class Inheritance
Imports
java.lang.reflect.Constructor, .InvocationTargetException, java.util.Objects, org.apache.commons.lang3.ArrayUtils, .ClassUtils
Utility reflection methods focused on constructors, modeled after MethodUtils.

Known Limitations

Accessing Public Constructors In A Default Access Superclass

There is an issue when invoking public constructors contained in a default access superclass. Reflection correctly locates these constructors and assigns them as public. However, an IllegalAccessException is thrown if the constructor is invoked.

ConstructorUtils contains a workaround for this situation: it will attempt to call java.lang.reflect.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.

Since
2.5

Constructor Summary

AccessConstructor and Description
public
ConstructorUtils()
Deprecated TODO Make private in 4.0.

ConstructorUtils instances should NOT be constructed in standard programming.

Method Summary

Modifier and TypeMethod and Description
public static <
the constructor type.
T> Constructor<T>

Returns:

the constructor, null if no matching accessible constructor found.
getAccessibleConstructor(final Class<T>
the class to find a constructor for, not null.
cls, final Class<?>...
the array of parameter types, null treated as empty.
parameterTypes)

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

public static <
the constructor type.
T> Constructor<T>

Returns:

the constructor, null if no matching accessible constructor found.
getAccessibleConstructor(final Constructor<T>
the prototype constructor object, not null.
ctor)

Checks if the specified constructor is accessible.

public static <
the constructor type.
T> Constructor<T>

Returns:

the constructor, null if no matching accessible constructor found.
getMatchingAccessibleConstructor(final Class<T>
the class to find a constructor for, not null.
cls, final Class<?>...
find method with compatible parameters.
parameterTypes)

Finds an accessible constructor with compatible parameters.

public static <
the type to be constructed.
T> T

Returns:

new instance of cls, not null.
invokeConstructor(final Class<T>
the class to be constructed, not null.
cls, final Object...
the array of arguments, null treated as empty.
args)

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

public static <
the type to be constructed.
T> T

Returns:

new instance of cls, not null
invokeConstructor(final Class<T>
the class to be constructed, not null.
cls, final Object[]
the array of arguments, null treated as empty.
args, final Class<?>[]
the array of parameter types, null treated as empty.
parameterTypes)

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

public static <
the type to be constructed.
T> T

Returns:

new instance of cls, not null.
invokeExactConstructor(final Class<T>
the class to be constructed, not null.
cls, final Object...
the array of arguments, null treated as empty.
args)

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

public static <
the type to construct.
T> T

Returns:

new instance of cls, not null.
invokeExactConstructor(final Class<T>
the class to construct, not null.
cls, final Object[]
the array of arguments, null treated as empty.
args, final Class<?>[]
the array of parameter types, null treated as empty.
parameterTypes)

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

private static boolean

Returns:

true if type and any enclosing classes are public.
isAccessible(final Class<?>
to check.
type)

Tests whether the specified class is generally accessible, i.e. is declared in an entirely public manner.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

ConstructorUtilsback to summary
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.

Annotations
@Deprecated

Method Detail

getAccessibleConstructorback to summary
public static <T> Constructor<T> getAccessibleConstructor(final Class<T> cls, final Class<?>... parameterTypes)

Finds 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.

Parameters
<T>
the constructor type.
cls:Class<T>

the class to find a constructor for, not null.

parameterTypes:Class<?>[]

the array of parameter types, null treated as empty.

Returns:Constructor<T>

the constructor, null if no matching accessible constructor found.

Exceptions
NullPointerException:
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, getAccessibleConstructor(java.lang.reflect.Constructor)
getAccessibleConstructorback to summary
public static <T> Constructor<T> getAccessibleConstructor(final Constructor<T> ctor)

Checks if the specified constructor is accessible.

This simply ensures that the constructor is accessible.

Parameters
<T>
the constructor type.
ctor:Constructor<T>

the prototype constructor object, not null.

Returns:Constructor<T>

the constructor, null if no matching accessible constructor found.

Exceptions
NullPointerException:
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
getMatchingAccessibleConstructorback to summary
public static <T> Constructor<T> getMatchingAccessibleConstructor(final Class<T> cls, final Class<?>... parameterTypes)

Finds 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.

Parameters
<T>
the constructor type.
cls:Class<T>

the class to find a constructor for, not null.

parameterTypes:Class<?>[]

find method with compatible parameters.

Returns:Constructor<T>

the constructor, null if no matching accessible constructor found.

Exceptions
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)
invokeConstructorback to summary
public static <T> T invokeConstructor(final Class<T> cls, final 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.

Parameters
<T>
the type to be constructed.
cls:Class<T>

the class to be constructed, not null.

args:Object[]

the array of arguments, null treated as empty.

Returns:T

new instance of cls, not null.

Exceptions
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.
InvocationTargetException:
Thrown if the underlying constructor throws an exception.
InstantiationException:
Thrown if the class that declares the underlying constructor represents an abstract class.
NullPointerException:
Thrown if cls is null.
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.
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[])
invokeConstructorback to summary
public static <T> T invokeConstructor(final Class<T> cls, final Object[] args, final 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.

Parameters
<T>
the type to be constructed.
cls:Class<T>

the class to be constructed, not null.

args:Object[]

the array of arguments, null treated as empty.

parameterTypes:Class<?>[]

the array of parameter types, null treated as empty.

Returns:T

new instance of cls, not null

Exceptions
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.
InvocationTargetException:
Thrown if the underlying constructor throws an exception.
InstantiationException:
Thrown if the class that declares the underlying constructor represents an abstract class.
NullPointerException:
Thrown if cls is null.
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.
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
invokeExactConstructorback to summary
public static <T> T invokeExactConstructor(final Class<T> cls, final 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.

Parameters
<T>
the type to be constructed.
cls:Class<T>

the class to be constructed, not null.

args:Object[]

the array of arguments, null treated as empty.

Returns:T

new instance of cls, not null.

Exceptions
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.
InvocationTargetException:
Thrown if the underlying constructor throws an exception.
InstantiationException:
Thrown if the class that declares the underlying constructor represents an abstract class.
NullPointerException:
Thrown if cls is null.
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.
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[])
invokeExactConstructorback to summary
public static <T> T invokeExactConstructor(final Class<T> cls, final Object[] args, final 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.

Parameters
<T>
the type to construct.
cls:Class<T>

the class to construct, not null.

args:Object[]

the array of arguments, null treated as empty.

parameterTypes:Class<?>[]

the array of parameter types, null treated as empty.

Returns:T

new instance of cls, not null.

Exceptions
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.
InvocationTargetException:
Thrown if the underlying constructor throws an exception.
InstantiationException:
Thrown if the class that declares the underlying constructor represents an abstract class.
NullPointerException:
Thrown if cls is null.
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.
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...)
isAccessibleback to summary
private static boolean isAccessible(final Class<?> type)

Tests whether the specified class is generally accessible, i.e. is declared in an entirely public manner.

Parameters
type:Class<?>

to check.

Returns:boolean

true if type and any enclosing classes are public.

Exceptions
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.