## org.apache.tools.ant
Class IntrospectionHelper

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

All Implemented Interfaces:
  BuildListener, java.util.EventListener

public final class IntrospectionHelper
extends java.lang.Object
implements BuildListener

Helper class that collects the methods a task or nested element holds to set attributes, create nested elements or hold PCDATA elements. The class is final as it has a private constructor.

Nested Class Summary
`static class` `IntrospectionHelper.Creator` creator - allows use of create/store external to IntrospectionHelper.

Method Summary
`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.
`void` `buildFinished(BuildEvent event)` Clears all storage used by this class, including the static cache of helpers.
`void` `buildStarted(BuildEvent event)` Empty implementation to satisfy the BuildListener interface.
`java.lang.Object` `createElement(Project project, java.lang.Object parent, java.lang.String elementName)` Deprecated. 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` `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` `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.
`protected java.lang.String` `getElementName(Project project, java.lang.Object element)` Returns a description of the type of the given element in relation to a given project.
`java.lang.Class` `getElementType(java.lang.String elementName)` Returns the type of a named nested element.
`java.util.List` `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` `getNestedElementMap()` Returns a read-only map of nested elements supported by the introspected class.
`java.util.Enumeration` `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` `messageLogged(BuildEvent event)` Empty implementation to satisfy the BuildListener interface.
`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.
`void` `targetFinished(BuildEvent event)` Empty implementation to satisfy the BuildListener interface.
`void` `targetStarted(BuildEvent event)` Empty implementation to satisfy the BuildListener interface.
`void` `taskFinished(BuildEvent event)` Empty implementation to satisfy the BuildListener interface.
`void` `taskStarted(BuildEvent event)` Empty implementation to satisfy the BuildListener interface.
`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`

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

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

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

  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

### 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 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 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 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 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 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

### getElementName

    protected java.lang.String getElementName(Project project,
                                              java.lang.Object element)

  Returns a description of the type of the given element in relation to a given project. This is used for logging purposes when the element is asked to cope with some data it has no way of handling.

  Parameters:
    `project` - The project the element is defined in. Must not be `null`.
    `element` - The element to describe. Must not be `null`.
  Returns:
    a description of the element type

### buildFinished

    public void buildFinished(BuildEvent event)

  Clears all storage used by this class, including the static cache of helpers.

  Specified by:
    `buildFinished` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.
  See Also:
    `BuildEvent.getException()`

### buildStarted

    public void buildStarted(BuildEvent event)

  Empty implementation to satisfy the BuildListener interface.

  Specified by:
    `buildStarted` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.

### targetStarted

    public void targetStarted(BuildEvent event)

  Empty implementation to satisfy the BuildListener interface.

  Specified by:
    `targetStarted` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.
  See Also:
    `BuildEvent.getTarget()`

### targetFinished

    public void targetFinished(BuildEvent event)

  Empty implementation to satisfy the BuildListener interface.

  Specified by:
    `targetFinished` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.
  See Also:
    `BuildEvent.getException()`

### taskStarted

    public void taskStarted(BuildEvent event)

  Empty implementation to satisfy the BuildListener interface.

  Specified by:
    `taskStarted` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.
  See Also:
    `BuildEvent.getTask()`

### taskFinished

    public void taskFinished(BuildEvent event)

  Empty implementation to satisfy the BuildListener interface.

  Specified by:
    `taskFinished` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.
  See Also:
    `BuildEvent.getException()`

### messageLogged

    public void messageLogged(BuildEvent event)

  Empty implementation to satisfy the BuildListener interface.

  Specified by:
    `messageLogged` in interface `BuildListener`
  Parameters:
    `event` - Ignored in this implementation.
  See Also:
    `BuildEvent.getMessage()`, `BuildEvent.getPriority()`

Copyright © 2000-2005 Apache Software Foundation. All Rights Reserved.