Package org.apache.commons.lang.reflect

## Class ConstructorUtils

- java.lang.Object
- - org.apache.commons.lang.reflect.ConstructorUtils

-     public class ConstructorUtils
      extends Object

  Utility reflection methods focussed on constructors, modelled 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 locates these constructors fine and correctly assigns them as public. However, an `IllegalAccessException` is thrown if the constructors is invoked.

  `ConstructorUtils` contains a workaround for this situation. It will attempt to call `setAccessible` 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.

  Since:
    2.5
  Version:
    $Id: ConstructorUtils.java 1056863 2011-01-09 02:00:25Z niallp $

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ConstructorUtils()` | ConstructorUtils instances should NOT be constructed in standard programming.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static Constructor` | `getAccessibleConstructor​(Class cls, Class parameterType)` | Returns a constructor with single argument.
    `static Constructor` | `getAccessibleConstructor​(Class cls, Class[] parameterTypes)` | Returns a constructor given a class and signature.
    `static Constructor` | `getAccessibleConstructor​(Constructor ctor)` | Returns accessible version of the given constructor.
    `static Constructor` | `getMatchingAccessibleConstructor​(Class cls, Class[] parameterTypes)` | Find an accessible constructor with compatible parameters.
    `static Object` | `invokeConstructor​(Class cls, Object arg)` | Returns new instance of `klazz` created using the actual arguments `args`.
    `static Object` | `invokeConstructor​(Class cls, Object[] args)` | Returns new instance of `klazz` created using the actual arguments `args`.
    `static Object` | `invokeConstructor​(Class cls, Object[] args, Class[] parameterTypes)` | Returns new instance of `klazz` created using constructor with signature `parameterTypes` and actual arguments `args`.
    `static Object` | `invokeExactConstructor​(Class cls, Object arg)` | Returns new instance of `klazz` created using the actual arguments `args`.
    `static Object` | `invokeExactConstructor​(Class cls, Object[] args)` | Returns new instance of `klazz` created using the actual arguments `args`.
    `static Object` | `invokeExactConstructor​(Class cls, Object[] args, Class[] parameterTypes)` | Returns new instance of `klazz` created using constructor with signature `parameterTypes` and actual arguments `args`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ConstructorUtils

          public ConstructorUtils()

      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 Detail

    - #### invokeConstructor

          public static Object invokeConstructor​(Class cls,
                                                 Object arg)
                                          throws NoSuchMethodException,
                                                 IllegalAccessException,
                                                 InvocationTargetException,
                                                 InstantiationException

      Returns new instance of `klazz` created using the actual arguments `args`. The formal parameter types are inferred from the actual values of `args`. See `invokeExactConstructor(Class, Object[], Class[])` for more details.

      The signatures should be assignment compatible.

      Parameters:
        `cls` - the class to be constructed.
        `arg` - the actual argument
      Returns:
        new instance of `klazz`
      Throws:
        `NoSuchMethodException` - If the constructor cannot be found
        `IllegalAccessException` - If an error occurs accessing the constructor
        `InvocationTargetException` - If an error occurs invoking the constructor
        `InstantiationException` - If an error occurs instantiating the class
      See Also:
        `invokeConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[])`

    - #### invokeConstructor

          public static Object invokeConstructor​(Class cls,
                                                 Object[] args)
                                          throws NoSuchMethodException,
                                                 IllegalAccessException,
                                                 InvocationTargetException,
                                                 InstantiationException

      Returns new instance of `klazz` created using the actual arguments `args`. The formal parameter types are inferred from the actual values of `args`. See `invokeExactConstructor(Class, Object[], Class[])` for more details.

      The signatures should be assignment compatible.

      Parameters:
        `cls` - the class to be constructed.
        `args` - actual argument array
      Returns:
        new instance of `klazz`
      Throws:
        `NoSuchMethodException` - If the constructor cannot be found
        `IllegalAccessException` - If an error occurs accessing the constructor
        `InvocationTargetException` - If an error occurs invoking the constructor
        `InstantiationException` - If an error occurs instantiating the class
      See Also:
        `invokeConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[])`

    - #### invokeConstructor

          public static Object invokeConstructor​(Class cls,
                                                 Object[] args,
                                                 Class[] parameterTypes)
                                          throws NoSuchMethodException,
                                                 IllegalAccessException,
                                                 InvocationTargetException,
                                                 InstantiationException

      Returns new instance of `klazz` created using constructor with signature `parameterTypes` and actual arguments `args`.

      The signatures should be assignment compatible.

      Parameters:
        `cls` - the class to be constructed.
        `args` - actual argument array
        `parameterTypes` - parameter types array
      Returns:
        new instance of `klazz`
      Throws:
        `NoSuchMethodException` - if matching constructor cannot be found
        `IllegalAccessException` - thrown on the constructor's invocation
        `InvocationTargetException` - thrown on the constructor's invocation
        `InstantiationException` - thrown on the constructor's invocation
      See Also:
        `Constructor.newInstance(java.lang.Object...)`

    - #### invokeExactConstructor

          public static Object invokeExactConstructor​(Class cls,
                                                      Object arg)
                                               throws NoSuchMethodException,
                                                      IllegalAccessException,
                                                      InvocationTargetException,
                                                      InstantiationException

      Returns new instance of `klazz` created using the actual arguments `args`. The formal parameter types are inferred from the actual values of `args`. See `invokeExactConstructor(Class, Object[], Class[])` for more details.

      The signatures should match exactly.

      Parameters:
        `cls` - the class to be constructed.
        `arg` - the actual argument
      Returns:
        new instance of `klazz`
      Throws:
        `NoSuchMethodException` - If the constructor cannot be found
        `IllegalAccessException` - If an error occurs accessing the constructor
        `InvocationTargetException` - If an error occurs invoking the constructor
        `InstantiationException` - If an error occurs instantiating the class
      See Also:
        `invokeExactConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[])`

    - #### invokeExactConstructor

          public static Object invokeExactConstructor​(Class cls,
                                                      Object[] args)
                                               throws NoSuchMethodException,
                                                      IllegalAccessException,
                                                      InvocationTargetException,
                                                      InstantiationException

      Returns new instance of `klazz` created using the actual arguments `args`. The formal parameter types are inferred from the actual values of `args`. See `invokeExactConstructor(Class, Object[], Class[])` for more details.

      The signatures should match exactly.

      Parameters:
        `cls` - the class to be constructed.
        `args` - actual argument array
      Returns:
        new instance of `klazz`
      Throws:
        `NoSuchMethodException` - If the constructor cannot be found
        `IllegalAccessException` - If an error occurs accessing the constructor
        `InvocationTargetException` - If an error occurs invoking the constructor
        `InstantiationException` - If an error occurs instantiating the class
      See Also:
        `invokeExactConstructor(java.lang.Class, java.lang.Object[], java.lang.Class[])`

    - #### invokeExactConstructor

          public static Object invokeExactConstructor​(Class cls,
                                                      Object[] args,
                                                      Class[] parameterTypes)
                                               throws NoSuchMethodException,
                                                      IllegalAccessException,
                                                      InvocationTargetException,
                                                      InstantiationException

      Returns new instance of `klazz` created using constructor with signature `parameterTypes` and actual arguments `args`.

      The signatures should match exactly.

      Parameters:
        `cls` - the class to be constructed.
        `args` - actual argument array
        `parameterTypes` - parameter types array
      Returns:
        new instance of `klazz`
      Throws:
        `NoSuchMethodException` - if matching constructor cannot be found
        `IllegalAccessException` - thrown on the constructor's invocation
        `InvocationTargetException` - thrown on the constructor's invocation
        `InstantiationException` - thrown on the constructor's invocation
      See Also:
        `Constructor.newInstance(java.lang.Object...)`

    - #### getAccessibleConstructor

          public static Constructor getAccessibleConstructor​(Class cls,
                                                             Class parameterType)

      Returns a constructor with single argument.
      Parameters:
        `cls` - the class to be constructed
        `parameterType` - The constructor parameter type
      Returns:
        null if matching accessible constructor can not be found.
      See Also:
        `Class.getConstructor(java.lang.Class<?>...)`, `getAccessibleConstructor(java.lang.reflect.Constructor)`

    - #### getAccessibleConstructor

          public static Constructor getAccessibleConstructor​(Class cls,
                                                             Class[] parameterTypes)

      Returns a constructor given a class and signature.
      Parameters:
        `cls` - the class to be constructed
        `parameterTypes` - the parameter array
      Returns:
        null if matching accessible constructor can not be found
      See Also:
        `Class.getConstructor(java.lang.Class<?>...)`, `getAccessibleConstructor(java.lang.reflect.Constructor)`

    - #### getAccessibleConstructor

          public static Constructor getAccessibleConstructor​(Constructor ctor)

      Returns accessible version of the given constructor.
      Parameters:
        `ctor` - prototype constructor object.
      Returns:
        `null` if accessible constructor can not be found.
      See Also:
        `SecurityManager`

    - #### getMatchingAccessibleConstructor

          public static Constructor getMatchingAccessibleConstructor​(Class cls,
                                                                     Class[] parameterTypes)

      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.

      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.

      Parameters:
        `cls` - find constructor for this class
        `parameterTypes` - find method with compatible parameters
      Returns:
        a valid Constructor object. If there's no matching constructor, returns `null`.