Top Description Fields Constructors Methods
org.apache.tools.ant

public Class ComponentHelper

extends Object
Class Inheritance
Imports
java.io.File, .IOException, .InputStream, .PrintWriter, .StringWriter, java.lang.reflect.InvocationTargetException, .Modifier, java.util.ArrayList, .HashMap, .HashSet, .Hashtable, .Iterator, .List, .Map, .Properties, .Set, .Stack, java.util.stream.Collectors, org.apache.tools.ant.launch.Launcher, org.apache.tools.ant.taskdefs.Definer, .Property, .Typedef
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

Modifier and TypeField and Description
private static final String
ANT_PROPERTY_TASK

special name of ant's property task -property.

private String
antLibCurrentUri

current antlib uri

private Stack<String>
antLibStack

Stack of antlib contexts used to resolve definitions while processing antlib

private final Hashtable<String, AntTypeDefinition>
antTypeTable

Map from component name to anttypedefinition

private static final String
BUILD_SYSCLASSPATH_ONLY

string used to control build.syspath policy only

private final HashSet<String>
checkedNamespaces

Set of namespaces that have been checked for antlibs

public static final String
COMPONENT_HELPER_REFERENCE

reference under which we register ourselves with a project -ant.ComponentHelper

private static Properties[]
defaultDefinitions

private static final String
ERROR_NO_TASK_LIST_LOAD

Error string when the file taskdefs/defaults.properties cannot be found

private static final String
ERROR_NO_TYPE_LIST_LOAD

Error string when the typedefs/defaults.properties cannot be found

private ComponentHelper
next

this does not appear to be used anywhere in the Ant codebase even via its accessors

private Project
project

Project that owns a component helper

private boolean
rebuildTaskClassDefinitions

flag to rebuild taskClassDefinitions

private boolean
rebuildTypeClassDefinitions

flag to rebuild typeClassDefinitions

private final Map<String, List<AntTypeDefinition>>
restrictedDefinitions

Map of component name to lists of restricted definitions

private final Hashtable<String, Class<?>>
taskClassDefinitions

Map of tasks generated from antTypeTable

private final Hashtable<String, Class<?>>
typeClassDefinitions

Map of types generated from antTypeTable

Constructor Summary

AccessConstructor and Description
protected
ComponentHelper()

Creates a new ComponentHelper instance.

Method Summary

Modifier and TypeMethod and Description
public void
addDataTypeDefinition(String
The name of the datatype. Must not be null.
typeName, Class<?>
The full name of the class implementing the datatype. Must not be null.
typeClass)

Adds a new datatype definition.

public void
addDataTypeDefinition(AntTypeDefinition
an AntTypeDefinition value.
def)

Describe addDataTypeDefinition method here.

public void
addTaskDefinition(String
The name of the task to add. Must not be null.
taskName, Class<?>
The full name of the class implementing the task. Must not be null.
taskClass)

Adds a new task definition to the project.

private synchronized void
checkNamespace(String
the name of the component, which should include a URI prefix if it is in a namespace
componentName)

Called for each component name, check if the associated URI has been examined for antlibs.

public void
checkTaskClass(final Class<?>
The class to be checked. Must not be null.
taskClass)

Checks whether or not a class is suitable for serving as Ant task.

public Object

Returns:

the created component.
createComponent(UnknownElement
The Unknown Element creating this component.
ue, String
Namespace URI. Also available as ue.getNamespace().
ns, String
The component type, Also available as ue.getComponentName().
componentType)

Factory method to create the components.

public Object

Returns:

the class if found or null if not.
createComponent(String
the name of the component, if the component is in a namespace, the name is prefixed with the namespace uri and ":".
componentName)

Create an object for a component.

public Object

Returns:

an instance of the specified data type, or null if the data type name is not recognised.
createDataType(String
The name of the data type to create an instance of. Must not be null.
typeName)

Creates a new instance of a data type.

private Task

Returns:

an instance of the specified task, or null if the task name is not recognised.
createNewTask(String
The name of the task to create an instance of. Must not be null.
taskType)

Creates a new instance of a task.

public Task

Returns:

an instance of the specified task, or null if the task name is not recognised.
createTask(String
The name of the task to create an instance of. Must not be null.
taskType)

Creates a new instance of a task.

public String

Returns:

a string containing as much diagnostics info as possible.
diagnoseCreationFailure(String
component name.
componentName, String
component type, used in error messages
type)

Handler called to do decent diagnosis on instantiation failure.

public void
enterAntLib(String
the uri that is associated with this antlib.
uri)

Called at the start of processing an antlib.

public void
exitAntLib()

Called at the end of processing an antlib.

private List<AntTypeDefinition>

Returns:

the (possibly empty) list of definitions
findTypeMatches(String
prefix to match off
prefix)

Create a list of all definitions that match a prefix, usually the URI of a library

public Hashtable<String, AntTypeDefinition>

Returns:

a map of from datatype name to datatype definition (String to AntTypeDefinition).
getAntTypeTable()

Returns the current datatype definition hashtable.

private synchronized Set<String>

Returns:

A copy of the CheckedNamespace.
getCheckedNamespace()

private ClassLoader
getClassLoader(ClassLoader classLoader)

public Class<?>

Returns:

the class if found or null if not.
getComponentClass(String
the name of the component, if the component is in a namespace, the name is prefixed with the namespace uri and ":".
componentName)

Return the class of the component name.

public static ComponentHelper

Returns:

the project component for a specific project.
getComponentHelper(Project
the project.
project)

Find a project component for a specific project, creating it if it does not exist.

public String

Returns:

the current antlib uri.
getCurrentAntlibUri()

public Hashtable<String, Class<?>>

Returns:

a map of from type name to implementing class (String to Class).
getDataTypeDefinitions()

Returns the current type definition hashtable.

private static synchronized Properties

Returns:

a mapping from definition names to class names
getDefaultDefinitions(boolean
true for typedefs, false for taskdefs
type)

Load default task or type definitions - just the names, no class loading.

public AntTypeDefinition

Returns:

the ant definition or null if not present.
getDefinition(String
the name of the component.
componentName)

Return the antTypeDefinition for a componentName.

public String

Returns:

a description of the element type.
getElementName(Object
The element to describe. Must not be null.
element)

Returns a description of the type of the given element.

public String

Returns:

a description of the element type.
getElementName(Object
The element to describe. Must not be null.
o, boolean
whether to use a brief description.
brief)

Returns a description of the type of the given element.

public static String

Returns:

a description of the element type.
getElementName(Project
The optional Project instance.
p, Object
The element to describe. Must not be null.
o, boolean
whether to use a brief description.
brief)

Convenient way to get some element name even when you may not have a Project context.

public ComponentHelper

Returns:

the next chained component helper.
getNext()

Get the next chained component helper.

public Project

Returns:

the project owner of this helper.
getProject()

Get the project.

private Map<String, List<AntTypeDefinition>>

Returns:

A deep copy of the restrictedDefinition
getRestrictedDefinition()

public List<AntTypeDefinition>

Returns:

the list of restricted definitions for a particular name.
getRestrictedDefinitions(String
the name to use.
componentName)

This returns a list of restricted definitions for a name.

public Hashtable<String, Class<?>>

Returns:

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

Returns the current task definition hashtable.

private static String
getUnmappedElementName(Class<?> c, boolean brief)

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.

public void
initSubProject(ComponentHelper
the component helper of the parent project.
helper)

Used with creating child projects.

private void
initTasks()

Load ant's tasks.

private void
initTypes()

Load ant's datatypes.

private void
printClassNotFound(PrintWriter out, String classname, boolean optional, String dirListing)

Print class not found.

private void
printNotLoadDependentClass(PrintWriter out, boolean optional, NoClassDefFoundError ncdfe, String dirListing)

Print could not load dependent class.

private void
printUnknownDefinition(PrintWriter out, String componentName, String dirListing)

Print unknown definition.forking

private boolean

Returns:

true if the two definitions are the same.
sameDefinition(AntTypeDefinition
the new definition.
def, AntTypeDefinition
the old definition.
old)

Check if two definitions are the same.

public void
setNext(ComponentHelper
the next chained component helper.
next)

Set the next chained component helper.

public void
setProject(Project
the project for this helper.
project)

Sets the project for this component helper.

private void
updateDataTypeDefinition(AntTypeDefinition
the definition to update or insert.
def)

Update the component definition table with a new or modified definition.

private void
updateRestrictedDefinition(AntTypeDefinition def)

update the restricted definition table with a new or modified definition.

private boolean

Returns:

true if exposed type of definition is present.
validDefinition(AntTypeDefinition
the definition to test.
def)

Check if definition is a valid definition--it may be a definition of an optional task that does not exist.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ANT_PROPERTY_TASKback to summary
private static final String ANT_PROPERTY_TASK

special name of ant's property task -property. There is some contrived work here to enable this early.

antLibCurrentUriback to summary
private String antLibCurrentUri

current antlib uri

antLibStackback to summary
private Stack<String> antLibStack

Stack of antlib contexts used to resolve definitions while processing antlib

antTypeTableback to summary
private final Hashtable<String, AntTypeDefinition> antTypeTable

Map from component name to anttypedefinition

BUILD_SYSCLASSPATH_ONLYback to summary
private static final String BUILD_SYSCLASSPATH_ONLY

string used to control build.syspath policy only

checkedNamespacesback to summary
private final HashSet<String> checkedNamespaces

Set of namespaces that have been checked for antlibs

COMPONENT_HELPER_REFERENCEback to summary
public static final String COMPONENT_HELPER_REFERENCE

reference under which we register ourselves with a project -ant.ComponentHelper

defaultDefinitionsback to summary
private static Properties[] defaultDefinitions
ERROR_NO_TASK_LIST_LOADback to summary
private static final String ERROR_NO_TASK_LIST_LOAD

Error string when the file taskdefs/defaults.properties cannot be found

ERROR_NO_TYPE_LIST_LOADback to summary
private static final String ERROR_NO_TYPE_LIST_LOAD

Error string when the typedefs/defaults.properties cannot be found

nextback to summary
private ComponentHelper next

this does not appear to be used anywhere in the Ant codebase even via its accessors

projectback to summary
private Project project

Project that owns a component helper

rebuildTaskClassDefinitionsback to summary
private boolean rebuildTaskClassDefinitions

flag to rebuild taskClassDefinitions

rebuildTypeClassDefinitionsback to summary
private boolean rebuildTypeClassDefinitions

flag to rebuild typeClassDefinitions

restrictedDefinitionsback to summary
private final Map<String, List<AntTypeDefinition>> restrictedDefinitions

Map of component name to lists of restricted definitions

taskClassDefinitionsback to summary
private final Hashtable<String, Class<?>> taskClassDefinitions

Map of tasks generated from antTypeTable

typeClassDefinitionsback to summary
private final Hashtable<String, Class<?>> typeClassDefinitions

Map of types generated from antTypeTable

Constructor Detail

ComponentHelperback to summary
protected ComponentHelper()

Creates a new ComponentHelper instance.

Method Detail

addDataTypeDefinitionback to summary
public void addDataTypeDefinition(String typeName, 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:String

The name of the datatype. Must not be null.

typeClass:Class<?>

The full name of the class implementing the datatype. Must not be null.

addDataTypeDefinitionback to summary
public void addDataTypeDefinition(AntTypeDefinition def)

Describe addDataTypeDefinition method here.

Parameters
def:AntTypeDefinition

an AntTypeDefinition value.

addTaskDefinitionback to summary
public void addTaskDefinition(String taskName, 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:String

The name of the task to add. Must not be null.

taskClass:Class<?>

The full name of the class implementing the task. Must not be null.

Exceptions
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)
checkNamespaceback to summary
private synchronized void checkNamespace(String componentName)

Called for each component name, check if the associated URI has been examined for antlibs.

Parameters
componentName:String

the name of the component, which should include a URI prefix if it is in a namespace

checkTaskClassback to summary
public void checkTaskClass(final 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:Class<?>

The class to be checked. Must not be null.

Exceptions
BuildException:
if the class is unsuitable for being an Ant task. An error level message is logged before this exception is thrown.
createComponentback to summary
public Object createComponent(UnknownElement ue, String ns, String componentType) throws BuildException

Factory method to create the components. This should be called by UnknownElement.

Parameters
ue:UnknownElement

The Unknown Element creating this component.

ns:String

Namespace URI. Also available as ue.getNamespace().

componentType:String

The component type, Also available as ue.getComponentName().

Returns:Object

the created component.

Exceptions
BuildException:
if an error occurs.
createComponentback to summary
public Object createComponent(String componentName)

Create an object for a component.

Parameters
componentName:String

the name of the component, if the component is in a namespace, the name is prefixed with the namespace uri and ":".

Returns:Object

the class if found or null if not.

createDataTypeback to summary
public Object createDataType(String typeName) throws BuildException

Creates a new instance of a data type.

Parameters
typeName:String

The name of the data type to create an instance of. Must not be null.

Returns:Object

an instance of the specified data type, or null if the data type name is not recognised.

Exceptions
BuildException:
if the data type name is recognised but instance creation fails.
createNewTaskback to summary
private Task createNewTask(String taskType) throws BuildException

Creates a new instance of a task.

Parameters
taskType:String

The name of the task to create an instance of. Must not be null.

Returns:Task

an instance of the specified task, or null if the task name is not recognised.

Exceptions
BuildException:
if the task name is recognised but task creation fails.
Since
ant1.6
createTaskback to summary
public Task createTask(String taskType) throws BuildException

Creates a new instance of a task. Called from Project.createTask(), which can be called by tasks.

Parameters
taskType:String

The name of the task to create an instance of. Must not be null.

Returns:Task

an instance of the specified task, or null if the task name is not recognised.

Exceptions
BuildException:
if the task name is recognised but task creation fails.
diagnoseCreationFailureback to summary
public String diagnoseCreationFailure(String componentName, String type)

Handler called to do decent diagnosis on instantiation failure.

Parameters
componentName:String

component name.

type:String

component type, used in error messages

Returns:String

a string containing as much diagnostics info as possible.

enterAntLibback to summary
public void enterAntLib(String uri)

Called at the start of processing an antlib.

Parameters
uri:String

the uri that is associated with this antlib.

exitAntLibback to summary
public void exitAntLib()

Called at the end of processing an antlib.

findTypeMatchesback to summary
private List<AntTypeDefinition> findTypeMatches(String prefix)

Create a list of all definitions that match a prefix, usually the URI of a library

Parameters
prefix:String

prefix to match off

Returns:List<AntTypeDefinition>

the (possibly empty) list of definitions

getAntTypeTableback to summary
public Hashtable<String, AntTypeDefinition> getAntTypeTable()

Returns the current datatype definition hashtable. The returned hashtable is "live" and so should not be modified.

Returns:Hashtable<String, AntTypeDefinition>

a map of from datatype name to datatype definition (String to AntTypeDefinition).

getCheckedNamespaceback to summary
private synchronized Set<String> getCheckedNamespace()
Returns:Set<String>

A copy of the CheckedNamespace.

getClassLoaderback to summary
private ClassLoader getClassLoader(ClassLoader classLoader)
getComponentClassback to summary
public Class<?> getComponentClass(String componentName)

Return the class of the component name.

Parameters
componentName:String

the name of the component, if the component is in a namespace, the name is prefixed with the namespace uri and ":".

Returns:Class<?>

the class if found or null if not.

getComponentHelperback to summary
public static ComponentHelper getComponentHelper(Project project)

Find a project component for a specific project, creating it if it does not exist.

Parameters
project:Project

the project.

Returns:ComponentHelper

the project component for a specific project.

getCurrentAntlibUriback to summary
public String getCurrentAntlibUri()
Returns:String

the current antlib uri.

getDataTypeDefinitionsback to summary
public Hashtable<String, Class<?>> getDataTypeDefinitions()

Returns the current type definition hashtable. The returned hashtable is "live" and so should not be modified.

Returns:Hashtable<String, Class<?>>

a map of from type name to implementing class (String to Class).

getDefaultDefinitionsback to summary
private static synchronized Properties getDefaultDefinitions(boolean type) throws BuildException

Load default task or type definitions - just the names, no class loading. Caches results between calls to reduce overhead.

Parameters
type:boolean

true for typedefs, false for taskdefs

Returns:Properties

a mapping from definition names to class names

Exceptions
BuildException:
if there was some problem loading or parsing the definitions list
getDefinitionback to summary
public AntTypeDefinition getDefinition(String componentName)

Return the antTypeDefinition for a componentName.

Parameters
componentName:String

the name of the component.

Returns:AntTypeDefinition

the ant definition or null if not present.

getElementNameback to summary
public String getElementName(Object element)

Returns a description of the type of the given element.

This is useful for logging purposes.

Parameters
element:Object

The element to describe. Must not be null.

Returns:String

a description of the element type.

Since
Ant 1.6
getElementNameback to summary
public String getElementName(Object o, boolean brief)

Returns a description of the type of the given element.

This is useful for logging purposes.

Parameters
o:Object

The element to describe. Must not be null.

brief:boolean

whether to use a brief description.

Returns:String

a description of the element type.

Since
Ant 1.7
getElementNameback to summary
public static String getElementName(Project p, Object o, boolean brief)

Convenient way to get some element name even when you may not have a Project context.

Parameters
p:Project

The optional Project instance.

o:Object

The element to describe. Must not be null.

brief:boolean

whether to use a brief description.

Returns:String

a description of the element type.

Since
Ant 1.7
getNextback to summary
public ComponentHelper getNext()

Get the next chained component helper.

Returns:ComponentHelper

the next chained component helper.

getProjectback to summary
public Project getProject()

Get the project.

Returns:Project

the project owner of this helper.

getRestrictedDefinitionback to summary
private Map<String, List<AntTypeDefinition>> getRestrictedDefinition()
Returns:Map<String, List<AntTypeDefinition>>

A deep copy of the restrictedDefinition

getRestrictedDefinitionsback to summary
public List<AntTypeDefinition> getRestrictedDefinitions(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:String

the name to use.

Returns:List<AntTypeDefinition>

the list of restricted definitions for a particular name.

getTaskDefinitionsback to summary
public Hashtable<String, 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:Hashtable<String, Class<?>>

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

getUnmappedElementNameback to summary
private static String getUnmappedElementName(Class<?> c, boolean brief)
initDefaultDefinitionsback to summary
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.

initSubProjectback to summary
public void initSubProject(ComponentHelper helper)

Used with creating child projects. Each child project inherits the component definitions from its parent.

Parameters
helper:ComponentHelper

the component helper of the parent project.

initTasksback to summary
private void initTasks()

Load ant's tasks.

initTypesback to summary
private void initTypes()

Load ant's datatypes.

printClassNotFoundback to summary
private void printClassNotFound(PrintWriter out, String classname, boolean optional, String dirListing)

Print class not found.

printNotLoadDependentClassback to summary
private void printNotLoadDependentClass(PrintWriter out, boolean optional, NoClassDefFoundError ncdfe, String dirListing)

Print could not load dependent class.

printUnknownDefinitionback to summary
private void printUnknownDefinition(PrintWriter out, String componentName, String dirListing)

Print unknown definition.forking

sameDefinitionback to summary
private boolean sameDefinition(AntTypeDefinition def, AntTypeDefinition old)

Check if two definitions are the same.

Parameters
def:AntTypeDefinition

the new definition.

old:AntTypeDefinition

the old definition.

Returns:boolean

true if the two definitions are the same.

setNextback to summary
public void setNext(ComponentHelper next)

Set the next chained component helper.

Parameters
next:ComponentHelper

the next chained component helper.

setProjectback to summary
public void setProject(Project project)

Sets the project for this component helper.

Parameters
project:Project

the project for this helper.

updateDataTypeDefinitionback to summary
private void updateDataTypeDefinition(AntTypeDefinition def)

Update the component definition table with a new or modified definition.

Parameters
def:AntTypeDefinition

the definition to update or insert.

updateRestrictedDefinitionback to summary
private void updateRestrictedDefinition(AntTypeDefinition def)

update the restricted definition table with a new or modified definition.

validDefinitionback to summary
private boolean validDefinition(AntTypeDefinition def)

Check if definition is a valid definition--it may be a definition of an optional task that does not exist.

Parameters
def:AntTypeDefinition

the definition to test.

Returns:boolean

true if exposed type of definition is present.