ComponentHelper (Apache Ant API)
Date: 2012-02-26

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Constructor Summary
`protected` | `ComponentHelper()` Creates a new ComponentHelper instance.

Method Summary
`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` | `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` | `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` | `getRestrictedDefinitions(java.lang.String componentName)` This returns a list of restricted definitions for a name.
`java.util.Hashtable` | `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 getTaskDefinitions()

  Returns the current task definition hashtable. The returned hashtable is "live" and so should not be modified. Also, the returned table may be modifed asynchronously.

  Returns:
    a map of from task name to implementing class (String to Class).

### getDataTypeDefinitions

    public java.util.Hashtable 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 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 modifed 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 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 implementing class (String to Class).

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD