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

org.apache.tools.ant

## Class ComponentHelper

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

-     public class ComponentHelper
      extends java.lang.Object

  Component creation and configuration. The class is based around handing component definitions in an AntTypeTable. The old task/type methods have been kept for backward compatibly. Project will just delegate its calls to this class. A very simple hook mechanism is provided that allows users to plug in custom code. It is also possible to replace the default behavior ( for example in an app embedding ant )
  Since:
    Ant1.6

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `COMPONENT_HELPER_REFERENCE` reference under which we register ourselves with a project -"ant.ComponentHelper"

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ComponentHelper()` Creates a new ComponentHelper instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDataTypeDefinition(AntTypeDefinition def)` Describe `addDataTypeDefinition` method here.
    `void` | `addDataTypeDefinition(java.lang.String typeName, java.lang.Class<?> typeClass)` Adds a new datatype definition.
    `void` | `addTaskDefinition(java.lang.String taskName, java.lang.Class<?> taskClass)` Adds a new task definition to the project.
    `void` | `checkTaskClass(java.lang.Class<?> taskClass)` Checks whether or not a class is suitable for serving as Ant task.
    `java.lang.Object` | `createComponent(java.lang.String componentName)` Create an object for a component.
    `java.lang.Object` | `createComponent(UnknownElement ue, java.lang.String ns, java.lang.String componentType)` Factory method to create the components.
    `java.lang.Object` | `createDataType(java.lang.String typeName)` Creates a new instance of a data type.
    `Task` | `createTask(java.lang.String taskType)` Creates a new instance of a task.
    `java.lang.String` | `diagnoseCreationFailure(java.lang.String componentName, java.lang.String type)` Handler called to do decent diagnosis on instantiation failure.
    `void` | `enterAntLib(java.lang.String uri)` Called at the start of processing an antlib.
    `void` | `exitAntLib()` Called at the end of processing an antlib.
    `java.util.Hashtable<java.lang.String,AntTypeDefinition>` | `getAntTypeTable()` Returns the current datatype definition hashtable.
    `java.lang.Class<?>` | `getComponentClass(java.lang.String componentName)` Return the class of the component name.
    `static ComponentHelper` | `getComponentHelper(Project project)` Find a project component for a specific project, creating it if it does not exist.
    `java.lang.String` | `getCurrentAntlibUri()`
    `java.util.Hashtable<java.lang.String,java.lang.Class<?>>` | `getDataTypeDefinitions()` Returns the current type definition hashtable.
    `AntTypeDefinition` | `getDefinition(java.lang.String componentName)` Return the antTypeDefinition for a componentName.
    `java.lang.String` | `getElementName(java.lang.Object element)` Returns a description of the type of the given element.
    `java.lang.String` | `getElementName(java.lang.Object o, boolean brief)` Returns a description of the type of the given element.
    `static java.lang.String` | `getElementName(Project p, java.lang.Object o, boolean brief)` Convenient way to get some element name even when you may not have a Project context.
    `ComponentHelper` | `getNext()` Get the next chained component helper.
    `Project` | `getProject()` Get the project.
    `java.util.List<AntTypeDefinition>` | `getRestrictedDefinitions(java.lang.String componentName)` This returns a list of restricted definitions for a name.
    `java.util.Hashtable<java.lang.String,java.lang.Class<?>>` | `getTaskDefinitions()` Returns the current task definition hashtable.
    `void` | `initDefaultDefinitions()` This method is initialization code implementing the original ant component loading from /org/apache/tools/ant/taskdefs/default.properties and /org/apache/tools/ant/types/default.properties.
    `void` | `initSubProject(ComponentHelper helper)` Used with creating child projects.
    `void` | `setNext(ComponentHelper next)` Set the next chained component helper.
    `void` | `setProject(Project project)` Sets the project for this component helper.

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

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

- - ### Field Detail

    - #### COMPONENT_HELPER_REFERENCE

          public static final java.lang.String COMPONENT_HELPER_REFERENCE

      reference under which we register ourselves with a project -"ant.ComponentHelper"
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ComponentHelper

          protected ComponentHelper()

      Creates a new ComponentHelper instance.

  - ### Method Detail

    - #### getProject

          public Project getProject()

      Get the project.
      Returns:
        the project owner of this helper.

    - #### getComponentHelper

          public static ComponentHelper getComponentHelper(Project project)

      Find a project component for a specific project, creating it if it does not exist.
      Parameters:
        `project` - the project.
      Returns:
        the project component for a specific project.

    - #### setNext

          public void setNext(ComponentHelper next)

      Set the next chained component helper.
      Parameters:
        `next` - the next chained component helper.

    - #### getNext

          public ComponentHelper getNext()

      Get the next chained component helper.
      Returns:
        the next chained component helper.

    - #### setProject

          public void setProject(Project project)

      Sets the project for this component helper.
      Parameters:
        `project` - the project for this helper.

    - #### initSubProject

          public void initSubProject(ComponentHelper helper)

      Used with creating child projects. Each child project inherits the component definitions from its parent.
      Parameters:
        `helper` - the component helper of the parent project.

    - #### createComponent

          public java.lang.Object createComponent(UnknownElement ue,
                                         java.lang.String ns,
                                         java.lang.String componentType)
                                           throws BuildException

      Factory method to create the components. This should be called by UnknownElement.
      Parameters:
        `ue` - The Unknown Element creating this component.
        `ns` - Namespace URI. Also available as ue.getNamespace().
        `componentType` - The component type, Also available as ue.getComponentName().
      Returns:
        the created component.
      Throws:
        `BuildException` - if an error occurs.

    - #### createComponent

          public java.lang.Object createComponent(java.lang.String componentName)

      Create an object for a component.
      Parameters:
        `componentName` - the name of the component, if the component is in a namespace, the name is prefixed with the namespace uri and ":".
      Returns:
        the class if found or null if not.

    - #### getComponentClass

          public java.lang.Class<?> getComponentClass(java.lang.String componentName)

      Return the class of the component name.
      Parameters:
        `componentName` - the name of the component, if the component is in a namespace, the name is prefixed with the namespace uri and ":".
      Returns:
        the class if found or null if not.

    - #### getDefinition

          public AntTypeDefinition getDefinition(java.lang.String componentName)

      Return the antTypeDefinition for a componentName.
      Parameters:
        `componentName` - the name of the component.
      Returns:
        the ant definition or null if not present.

    - #### initDefaultDefinitions

          public void initDefaultDefinitions()

      This method is initialization code implementing the original ant component loading from /org/apache/tools/ant/taskdefs/default.properties and /org/apache/tools/ant/types/default.properties.

    - #### addTaskDefinition

          public void addTaskDefinition(java.lang.String taskName,
                               java.lang.Class<?> taskClass)

      Adds a new task definition to the project. Attempting to override an existing definition with an equivalent one (i.e. with the same classname) results in a verbose log message. Attempting to override an existing definition with a different one results in a warning log message.
      Parameters:
        `taskName` - The name of the task to add. Must not be `null`.
        `taskClass` - The full name of the class implementing the task. Must not be `null`.
      Throws:
        `BuildException` - if the class is unsuitable for being an Ant task. An error level message is logged before this exception is thrown.
      See Also:
        `checkTaskClass(Class)`

    - #### checkTaskClass

          public void checkTaskClass(java.lang.Class<?> taskClass)
                              throws BuildException

      Checks whether or not a class is suitable for serving as Ant task. Ant task implementation classes must be public, concrete, and have a no-arg constructor.
      Parameters:
        `taskClass` - The class to be checked. Must not be `null`.
      Throws:
        `BuildException` - if the class is unsuitable for being an Ant task. An error level message is logged before this exception is thrown.

    - #### getTaskDefinitions

          public java.util.Hashtable<java.lang.String,java.lang.Class<?>> getTaskDefinitions()

      Returns the current task definition hashtable. The returned hashtable is "live" and so should not be modified. Also, the returned table may be modified asynchronously.
      Returns:
        a map of from task name to implementing class (String to Class).

    - #### getDataTypeDefinitions

          public java.util.Hashtable<java.lang.String,java.lang.Class<?>> getDataTypeDefinitions()

      Returns the current type definition hashtable. The returned hashtable is "live" and so should not be modified.
      Returns:
        a map of from type name to implementing class (String to Class).

    - #### getRestrictedDefinitions

          public java.util.List<AntTypeDefinition> getRestrictedDefinitions(java.lang.String componentName)

      This returns a list of restricted definitions for a name. The returned List is "live" and so should not be modified. Also, the returned list may be modified asynchronously. Any access must be guarded with a lock on the list itself.
      Parameters:
        `componentName` - the name to use.
      Returns:
        the list of restricted definitions for a particular name.

    - #### addDataTypeDefinition

          public void addDataTypeDefinition(java.lang.String typeName,
                                   java.lang.Class<?> typeClass)

      Adds a new datatype definition. Attempting to override an existing definition with an equivalent one (i.e. with the same classname) results in a verbose log message. Attempting to override an existing definition with a different one results in a warning log message, but the definition is changed.
      Parameters:
        `typeName` - The name of the datatype. Must not be `null`.
        `typeClass` - The full name of the class implementing the datatype. Must not be `null`.

    - #### addDataTypeDefinition

          public void addDataTypeDefinition(AntTypeDefinition def)

      Describe `addDataTypeDefinition` method here.
      Parameters:
        `def` - an `AntTypeDefinition` value.

    - #### getAntTypeTable

          public java.util.Hashtable<java.lang.String,AntTypeDefinition> getAntTypeTable()

      Returns the current datatype definition hashtable. The returned hashtable is "live" and so should not be modified.
      Returns:
        a map of from datatype name to datatype definition (String to `AntTypeDefinition`).

    - #### createTask

          public Task createTask(java.lang.String taskType)
                          throws BuildException

      Creates a new instance of a task. Called from Project.createTask(), which can be called by tasks.
      Parameters:
        `taskType` - The name of the task to create an instance of. Must not be `null`.
      Returns:
        an instance of the specified task, or `null` if the task name is not recognised.
      Throws:
        `BuildException` - if the task name is recognised but task creation fails.

    - #### createDataType

          public java.lang.Object createDataType(java.lang.String typeName)
                                          throws BuildException

      Creates a new instance of a data type.
      Parameters:
        `typeName` - The name of the data type to create an instance of. Must not be `null`.
      Returns:
        an instance of the specified data type, or `null` if the data type name is not recognised.
      Throws:
        `BuildException` - if the data type name is recognised but instance creation fails.

    - #### getElementName

          public java.lang.String getElementName(java.lang.Object element)

      Returns a description of the type of the given element.

      This is useful for logging purposes.

      Parameters:
        `element` - The element to describe. Must not be `null`.
      Returns:
        a description of the element type.
      Since:
        Ant 1.6

    - #### getElementName

          public java.lang.String getElementName(java.lang.Object o,
                                        boolean brief)

      Returns a description of the type of the given element.

      This is useful for logging purposes.

      Parameters:
        `o` - The element to describe. Must not be `null`.
        `brief` - whether to use a brief description.
      Returns:
        a description of the element type.
      Since:
        Ant 1.7

    - #### getElementName

          public static java.lang.String getElementName(Project p,
                                        java.lang.Object o,
                                        boolean brief)

      Convenient way to get some element name even when you may not have a Project context.
      Parameters:
        `p` - The optional Project instance.
        `o` - The element to describe. Must not be `null`.
        `brief` - whether to use a brief description.
      Returns:
        a description of the element type.
      Since:
        Ant 1.7

    - #### enterAntLib

          public void enterAntLib(java.lang.String uri)

      Called at the start of processing an antlib.
      Parameters:
        `uri` - the uri that is associated with this antlib.

    - #### getCurrentAntlibUri

          public java.lang.String getCurrentAntlibUri()

      Returns:
        the current antlib uri.

    - #### exitAntLib

          public void exitAntLib()

      Called at the end of processing an antlib.

    - #### diagnoseCreationFailure

          public java.lang.String diagnoseCreationFailure(java.lang.String componentName,
                                                 java.lang.String type)

      Handler called to do decent diagnosis on instantiation failure.
      Parameters:
        `componentName` - component name.
        `type` - component type, used in error messages
      Returns:
        a string containing as much diagnostics info as possible.