IntrospectionHelper (Apache Ant API)
Date: 2015-06-29

org.apache.tools.ant

## Class IntrospectionHelper

- java.lang.Object
- - org.apache.tools.ant.IntrospectionHelper

-     public final class IntrospectionHelper
      extends java.lang.Object

  Helper class that collects the methods a task or nested element holds to set attributes, create nested elements or hold PCDATA elements. It contains hashtables containing classes that use introspection to handle all the invocation of the project-component specific methods. This class is somewhat complex, as it implements the O/X mapping between Ant XML and Java class instances. This is not the best place for someone new to Ant to start contributing to the codebase, as a change here can break the entire system in interesting ways. Always run a full test of Ant before checking in/submitting changes to this file. The class is final and has a private constructor. To get an instance for a specific (class,project) combination, use `getHelper(Project,Class)`. This may return an existing version, or a new one ...do not make any assumptions about its uniqueness, or its validity after the Project instance has finished its build.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `IntrospectionHelper.Creator` creator - allows use of create/store external to IntrospectionHelper.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.lang.String` | `NOT_SUPPORTED_CHILD_POSTFIX` part of the error message created by `throwNotSupported`.
    `protected static java.lang.String` | `NOT_SUPPORTED_CHILD_PREFIX` part of the error message created by `throwNotSupported`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addText(Project project, java.lang.Object element, java.lang.String text)` Adds PCDATA to an element, using the element's `void addText(String)` method, if it has one.
    `static void` | `clearCache()` Clears the static cache of on build finished.
    `java.lang.Object` | `createElement(Project project, java.lang.Object parent, java.lang.String elementName)` Deprecated. since 1.6.x. This is not a namespace aware method.
    `java.lang.reflect.Method` | `getAddTextMethod()` Returns the addText method when the introspected class supports nested text.
    `java.util.Map<java.lang.String,java.lang.Class<?>>` | `getAttributeMap()` Returns a read-only map of attributes supported by the introspected class.
    `java.lang.reflect.Method` | `getAttributeMethod(java.lang.String attributeName)` Returns the setter method of a named attribute.
    `java.util.Enumeration<java.lang.String>` | `getAttributes()` Returns an enumeration of the names of the attributes supported by the introspected class.
    `java.lang.Class<?>` | `getAttributeType(java.lang.String attributeName)` Returns the type of a named attribute.
    `IntrospectionHelper.Creator` | `getElementCreator(Project project, java.lang.String parentUri, java.lang.Object parent, java.lang.String elementName, UnknownElement ue)` returns an object that creates and stores an object for an element of a parent.
    `java.lang.reflect.Method` | `getElementMethod(java.lang.String elementName)` Returns the adder or creator method of a named nested element.
    `java.lang.Class<?>` | `getElementType(java.lang.String elementName)` Returns the type of a named nested element.
    `java.util.List<java.lang.reflect.Method>` | `getExtensionPoints()` Returns a read-only list of extension points supported by the introspected class.
    `static IntrospectionHelper` | `getHelper(java.lang.Class<?> c)` Returns a helper for the given class, either from the cache or by creating a new instance.
    `static IntrospectionHelper` | `getHelper(Project p, java.lang.Class<?> c)` Returns a helper for the given class, either from the cache or by creating a new instance.
    `java.util.Map<java.lang.String,java.lang.Class<?>>` | `getNestedElementMap()` Returns a read-only map of nested elements supported by the introspected class.
    `java.util.Enumeration<java.lang.String>` | `getNestedElements()` Returns an enumeration of the names of the nested elements supported by the introspected class.
    `boolean` | `isContainer()` Indicates whether the introspected class is a task container, supporting arbitrary nested tasks/types.
    `boolean` | `isDynamic()` Indicates whether the introspected class is a dynamic one, supporting arbitrary nested elements and/or attributes.
    `void` | `setAttribute(Project p, java.lang.Object element, java.lang.String attributeName, java.lang.Object value)` Sets the named attribute in the given element, which is part of the given project.
    `void` | `setAttribute(Project p, java.lang.Object element, java.lang.String attributeName, java.lang.String value)` Sets the named attribute in the given element, which is part of the given project.
    `void` | `storeElement(Project project, java.lang.Object parent, java.lang.Object child, java.lang.String elementName)` Stores a named nested element using a storage method determined by the initial introspection.
    `boolean` | `supportsCharacters()` Returns whether or not the introspected class supports PCDATA.
    `boolean` | `supportsNestedElement(java.lang.String elementName)` Indicates if this element supports a nested element of the given name.
    `boolean` | `supportsNestedElement(java.lang.String parentUri, java.lang.String elementName)` Indicate if this element supports a nested element of the given name.
    `boolean` | `supportsNestedElement(java.lang.String parentUri, java.lang.String elementName, Project project, java.lang.Object parent)` Indicate if this element supports a nested element of the given name.
    `boolean` | `supportsReflectElement(java.lang.String parentUri, java.lang.String elementName)` Check if this element supports a nested element from reflection.
    `void` | `throwNotSupported(Project project, java.lang.Object parent, java.lang.String elementName)` Utility method to throw a NotSupported exception

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

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

- - ### Field Detail

    - #### NOT_SUPPORTED_CHILD_PREFIX

          protected static final java.lang.String NOT_SUPPORTED_CHILD_PREFIX

      part of the error message created by `throwNotSupported`.
      Since:
        Ant 1.8.0
      See Also:
        Constant Field Values

    - #### NOT_SUPPORTED_CHILD_POSTFIX

          protected static final java.lang.String NOT_SUPPORTED_CHILD_POSTFIX

      part of the error message created by `throwNotSupported`.
      Since:
        Ant 1.8.0
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getHelper

          public static IntrospectionHelper getHelper(java.lang.Class<?> c)

      Returns a helper for the given class, either from the cache or by creating a new instance.
      Parameters:
        `c` - The class for which a helper is required. Must not be `null`.
      Returns:
        a helper for the specified class

    - #### getHelper

          public static IntrospectionHelper getHelper(Project p,
                                      java.lang.Class<?> c)

      Returns a helper for the given class, either from the cache or by creating a new instance. The method will make sure the helper will be cleaned up at the end of the project, and only one instance will be created for each class.
      Parameters:
        `p` - the project instance. Can be null, in which case the helper is not cached.
        `c` - The class for which a helper is required. Must not be `null`.
      Returns:
        a helper for the specified class

    - #### setAttribute

          public void setAttribute(Project p,
                          java.lang.Object element,
                          java.lang.String attributeName,
                          java.lang.Object value)
                            throws BuildException

      Sets the named attribute in the given element, which is part of the given project.
      Parameters:
        `p` - The project containing the element. This is used when files need to be resolved. Must not be `null`.
        `element` - The element to set the attribute in. Must not be `null`.
        `attributeName` - The name of the attribute to set. Must not be `null`.
        `value` - The value to set the attribute to. This may be interpreted or converted to the necessary type if the setter method doesn't accept an object of the supplied type.
      Throws:
        `BuildException` - if the introspected class doesn't support the given attribute, or if the setting method fails.

    - #### setAttribute

          public void setAttribute(Project p,
                          java.lang.Object element,
                          java.lang.String attributeName,
                          java.lang.String value)
                            throws BuildException

      Sets the named attribute in the given element, which is part of the given project.
      Parameters:
        `p` - The project containing the element. This is used when files need to be resolved. Must not be `null`.
        `element` - The element to set the attribute in. Must not be `null`.
        `attributeName` - The name of the attribute to set. Must not be `null`.
        `value` - The value to set the attribute to. This may be interpreted or converted to the necessary type if the setter method doesn't just take a string. Must not be `null`.
      Throws:
        `BuildException` - if the introspected class doesn't support the given attribute, or if the setting method fails.

    - #### addText

          public void addText(Project project,
                     java.lang.Object element,
                     java.lang.String text)
                       throws BuildException

      Adds PCDATA to an element, using the element's `void addText(String)` method, if it has one. If no such method is present, a BuildException is thrown if the given text contains non-whitespace.
      Parameters:
        `project` - The project which the element is part of. Must not be `null`.
        `element` - The element to add the text to. Must not be `null`.
        `text` - The text to add. Must not be `null`.
      Throws:
        `BuildException` - if non-whitespace text is provided and no method is available to handle it, or if the handling method fails.

    - #### throwNotSupported

          public void throwNotSupported(Project project,
                               java.lang.Object parent,
                               java.lang.String elementName)

      Utility method to throw a NotSupported exception
      Parameters:
        `project` - the Project instance.
        `parent` - the object which doesn't support a requested element
        `elementName` - the name of the Element which is trying to be created.

    - #### createElement

          @Deprecated
          public java.lang.Object createElement(Project project,
                                                  java.lang.Object parent,
                                                  java.lang.String elementName)
                                         throws BuildException

      Deprecated. since 1.6.x. This is not a namespace aware method.
      Creates a named nested element. Depending on the results of the initial introspection, either a method in the given parent instance or a simple no-arg constructor is used to create an instance of the specified element type.
      Parameters:
        `project` - Project to which the parent object belongs. Must not be `null`. If the resulting object is an instance of ProjectComponent, its Project reference is set to this parameter value.
        `parent` - Parent object used to create the instance. Must not be `null`.
        `elementName` - Name of the element to create an instance of. Must not be `null`.
      Returns:
        an instance of the specified element type
      Throws:
        `BuildException` - if no method is available to create the element instance, or if the creating method fails.

    - #### getElementCreator

          public IntrospectionHelper.Creator getElementCreator(Project project,
                                                      java.lang.String parentUri,
                                                      java.lang.Object parent,
                                                      java.lang.String elementName,
                                                      UnknownElement ue)

      returns an object that creates and stores an object for an element of a parent.
      Parameters:
        `project` - Project to which the parent object belongs.
        `parentUri` - The namespace uri of the parent object.
        `parent` - Parent object used to create the creator object to create and store and instance of a subelement.
        `elementName` - Name of the element to create an instance of.
        `ue` - The unknown element associated with the element.
      Returns:
        a creator object to create and store the element instance.

    - #### isDynamic

          public boolean isDynamic()

      Indicates whether the introspected class is a dynamic one, supporting arbitrary nested elements and/or attributes.
      Returns:
        `true` if the introspected class is dynamic; `false` otherwise.
      Since:
        Ant 1.6.3
      See Also:
        `DynamicElement`, `DynamicElementNS`

    - #### isContainer

          public boolean isContainer()

      Indicates whether the introspected class is a task container, supporting arbitrary nested tasks/types.
      Returns:
        `true` if the introspected class is a container; `false` otherwise.
      Since:
        Ant 1.6.3
      See Also:
        `TaskContainer`

    - #### supportsNestedElement

          public boolean supportsNestedElement(java.lang.String elementName)

      Indicates if this element supports a nested element of the given name.
      Parameters:
        `elementName` - the name of the nested element being checked
      Returns:
        true if the given nested element is supported

    - #### supportsNestedElement

          public boolean supportsNestedElement(java.lang.String parentUri,
                                      java.lang.String elementName)

      Indicate if this element supports a nested element of the given name.

      Note that this method will always return true if the introspected class is `dynamic` or contains a method named "add" with void return type and a single argument. To ge a more thorough answer, use the four-arg version of this method instead.

      Parameters:
        `parentUri` - the uri of the parent
        `elementName` - the name of the nested element being checked
      Returns:
        true if the given nested element is supported

    - #### supportsNestedElement

          public boolean supportsNestedElement(java.lang.String parentUri,
                                      java.lang.String elementName,
                                      Project project,
                                      java.lang.Object parent)

      Indicate if this element supports a nested element of the given name.

      Note that this method will always return true if the introspected class is `dynamic`, so be prepared to catch an exception about unsupported children when calling `getElementCreator`.

      Parameters:
        `parentUri` - the uri of the parent
        `elementName` - the name of the nested element being checked
        `project` - currently executing project instance
        `parent` - the parent element
      Returns:
        true if the given nested element is supported
      Since:
        Ant 1.8.0.

    - #### supportsReflectElement

          public boolean supportsReflectElement(java.lang.String parentUri,
                                       java.lang.String elementName)

      Check if this element supports a nested element from reflection.
      Parameters:
        `parentUri` - the uri of the parent
        `elementName` - the name of the nested element being checked
      Returns:
        true if the given nested element is supported
      Since:
        Ant 1.8.0

    - #### storeElement

          public void storeElement(Project project,
                          java.lang.Object parent,
                          java.lang.Object child,
                          java.lang.String elementName)
                            throws BuildException

      Stores a named nested element using a storage method determined by the initial introspection. If no appropriate storage method is available, this method returns immediately.
      Parameters:
        `project` - Ignored in this implementation. May be `null`.
        `parent` - Parent instance to store the child in. Must not be `null`.
        `child` - Child instance to store in the parent. Should not be `null`.
        `elementName` - Name of the child element to store. May be `null`, in which case this method returns immediately.
      Throws:
        `BuildException` - if the storage method fails.

    - #### getElementType

          public java.lang.Class<?> getElementType(java.lang.String elementName)
                                            throws BuildException

      Returns the type of a named nested element.
      Parameters:
        `elementName` - The name of the element to find the type of. Must not be `null`.
      Returns:
        the type of the nested element with the specified name. This will never be `null`.
      Throws:
        `BuildException` - if the introspected class does not support the named nested element.

    - #### getAttributeType

          public java.lang.Class<?> getAttributeType(java.lang.String attributeName)
                                              throws BuildException

      Returns the type of a named attribute.
      Parameters:
        `attributeName` - The name of the attribute to find the type of. Must not be `null`.
      Returns:
        the type of the attribute with the specified name. This will never be `null`.
      Throws:
        `BuildException` - if the introspected class does not support the named attribute.

    - #### getAddTextMethod

          public java.lang.reflect.Method getAddTextMethod()
                                                    throws BuildException

      Returns the addText method when the introspected class supports nested text.
      Returns:
        the method on this introspected class that adds nested text. Cannot be `null`.
      Throws:
        `BuildException` - if the introspected class does not support the nested text.
      Since:
        Ant 1.6.3

    - #### getElementMethod

          public java.lang.reflect.Method getElementMethod(java.lang.String elementName)
                                                    throws BuildException

      Returns the adder or creator method of a named nested element.
      Parameters:
        `elementName` - The name of the attribute to find the setter method of. Must not be `null`.
      Returns:
        the method on this introspected class that adds or creates this nested element. Can be `null` when the introspected class is a dynamic configurator!
      Throws:
        `BuildException` - if the introspected class does not support the named nested element.
      Since:
        Ant 1.6.3

    - #### getAttributeMethod

          public java.lang.reflect.Method getAttributeMethod(java.lang.String attributeName)
                                                      throws BuildException

      Returns the setter method of a named attribute.
      Parameters:
        `attributeName` - The name of the attribute to find the setter method of. Must not be `null`.
      Returns:
        the method on this introspected class that sets this attribute. This will never be `null`.
      Throws:
        `BuildException` - if the introspected class does not support the named attribute.
      Since:
        Ant 1.6.3

    - #### supportsCharacters

          public boolean supportsCharacters()

      Returns whether or not the introspected class supports PCDATA.
      Returns:
        whether or not the introspected class supports PCDATA.

    - #### getAttributes

          public java.util.Enumeration<java.lang.String> getAttributes()

      Returns an enumeration of the names of the attributes supported by the introspected class.
      Returns:
        an enumeration of the names of the attributes supported by the introspected class.
      See Also:
        `getAttributeMap()`

    - #### getAttributeMap

          public java.util.Map<java.lang.String,java.lang.Class<?>> getAttributeMap()

      Returns a read-only map of attributes supported by the introspected class.
      Returns:
        an attribute name to attribute `Class` unmodifiable map. Can be empty, but never `null`.
      Since:
        Ant 1.6.3

    - #### getNestedElements

          public java.util.Enumeration<java.lang.String> getNestedElements()

      Returns an enumeration of the names of the nested elements supported by the introspected class.
      Returns:
        an enumeration of the names of the nested elements supported by the introspected class.
      See Also:
        `getNestedElementMap()`

    - #### getNestedElementMap

          public java.util.Map<java.lang.String,java.lang.Class<?>> getNestedElementMap()

      Returns a read-only map of nested elements supported by the introspected class.
      Returns:
        a nested-element name to nested-element `Class` unmodifiable map. Can be empty, but never `null`.
      Since:
        Ant 1.6.3

    - #### getExtensionPoints

          public java.util.List<java.lang.reflect.Method> getExtensionPoints()

      Returns a read-only list of extension points supported by the introspected class.

      A task/type or nested element with void methods named `add()` or `addConfigured()`, taking a single class or interface argument, supports extensions point. This method returns the list of all these void add[Configured](type) methods.

      Returns:
        a list of void, single argument add() or addConfigured() `Method`s of all supported extension points. These methods are sorted such that if the argument type of a method derives from another type also an argument of a method of this list, the method with the most derived argument will always appear first. Can be empty, but never `null`.
      Since:
        Ant 1.6.3

    - #### clearCache

          public static void clearCache()

      Clears the static cache of on build finished.