Package org.apache.tools.ant
Class ComponentHelper
- java.lang.Object
-
- org.apache.tools.ant.ComponentHelper
-
public class ComponentHelper extends java.lang.ObjectComponent 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 Description static java.lang.StringCOMPONENT_HELPER_REFERENCEreference under which we register ourselves with a project -"ant.ComponentHelper"
-
Constructor Summary
Constructors Modifier Constructor Description protectedComponentHelper()Creates a new ComponentHelper instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddDataTypeDefinition(java.lang.String typeName, java.lang.Class<?> typeClass)Adds a new datatype definition.voidaddDataTypeDefinition(AntTypeDefinition def)DescribeaddDataTypeDefinitionmethod here.voidaddTaskDefinition(java.lang.String taskName, java.lang.Class<?> taskClass)Adds a new task definition to the project.voidcheckTaskClass(java.lang.Class<?> taskClass)Checks whether or not a class is suitable for serving as Ant task.java.lang.ObjectcreateComponent(java.lang.String componentName)Create an object for a component.java.lang.ObjectcreateComponent(UnknownElement ue, java.lang.String ns, java.lang.String componentType)Factory method to create the components.java.lang.ObjectcreateDataType(java.lang.String typeName)Creates a new instance of a data type.TaskcreateTask(java.lang.String taskType)Creates a new instance of a task.java.lang.StringdiagnoseCreationFailure(java.lang.String componentName, java.lang.String type)Handler called to do decent diagnosis on instantiation failure.voidenterAntLib(java.lang.String uri)Called at the start of processing an antlib.voidexitAntLib()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 ComponentHelpergetComponentHelper(Project project)Find a project component for a specific project, creating it if it does not exist.java.lang.StringgetCurrentAntlibUri()java.util.Hashtable<java.lang.String,java.lang.Class<?>>getDataTypeDefinitions()Returns the current type definition hashtable.AntTypeDefinitiongetDefinition(java.lang.String componentName)Return the antTypeDefinition for a componentName.java.lang.StringgetElementName(java.lang.Object element)Returns a description of the type of the given element.java.lang.StringgetElementName(java.lang.Object o, boolean brief)Returns a description of the type of the given element.static java.lang.StringgetElementName(Project p, java.lang.Object o, boolean brief)Convenient way to get some element name even when you may not have a Project context.ComponentHelpergetNext()Get the next chained component helper.ProjectgetProject()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.voidinitDefaultDefinitions()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.voidinitSubProject(ComponentHelper helper)Used with creating child projects.voidsetNext(ComponentHelper next)Set the next chained component helper.voidsetProject(Project project)Sets the project for this component helper.
-
-
-
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
-
-
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 benull.taskClass- The full name of the class implementing the task. Must not benull.- 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 BuildExceptionChecks 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 benull.- 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 benull.typeClass- The full name of the class implementing the datatype. Must not benull.
-
addDataTypeDefinition
public void addDataTypeDefinition(AntTypeDefinition def)
DescribeaddDataTypeDefinitionmethod here.- Parameters:
def- anAntTypeDefinitionvalue.
-
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 benull.- Returns:
- an instance of the specified task, or
nullif 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 BuildExceptionCreates a new instance of a data type.- Parameters:
typeName- The name of the data type to create an instance of. Must not benull.- Returns:
- an instance of the specified data type, or
nullif 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 benull.- 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 benull.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 benull.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.
-
-