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
`static java.lang.String` `COMPONENT_HELPER_REFERENCE` reference under which we register ourselves with a project -"ant.ComponentHelper"

### Constructor Summary

Constructors
`protected` `ComponentHelper()` Creates a new ComponentHelper instance.

### Method Summary

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