org.apache.tools.ant

Class IntrospectionHelper

public final class IntrospectionHelper extends Object implements BuildListener

Helper class that collects the methods a task or nested element holds to set attributes, create nested elements or hold PCDATA elements. The class is final as it has a private constructor.
Nested Class Summary
static classIntrospectionHelper.Creator
creator - allows use of create/store external to IntrospectionHelper.
Method Summary
voidaddText(Project project, Object element, String text)
Adds PCDATA to an element, using the element's void addText(String) method, if it has one.
voidbuildFinished(BuildEvent event)
Clears all storage used by this class, including the static cache of helpers.
voidbuildStarted(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.
ObjectcreateElement(Project project, Object parent, String elementName)
Creates a named nested element.
MethodgetAddTextMethod()
Returns the addText method when the introspected class supports nested text.
MapgetAttributeMap()
Returns a read-only map of attributes supported by the introspected class.
MethodgetAttributeMethod(String attributeName)
Returns the setter method of a named attribute.
EnumerationgetAttributes()
Returns an enumeration of the names of the attributes supported by the introspected class.
ClassgetAttributeType(String attributeName)
Returns the type of a named attribute.
IntrospectionHelper.CreatorgetElementCreator(Project project, String parentUri, Object parent, String elementName, UnknownElement ue)
returns an object that creates and stores an object for an element of a parent.
MethodgetElementMethod(String elementName)
Returns the adder or creator method of a named nested element.
protected StringgetElementName(Project project, Object element)
Returns a description of the type of the given element in relation to a given project.
ClassgetElementType(String elementName)
Returns the type of a named nested element.
ListgetExtensionPoints()
Returns a read-only list of extension points supported by the introspected class.
static IntrospectionHelpergetHelper(Class c)
Returns a helper for the given class, either from the cache or by creating a new instance.
static IntrospectionHelpergetHelper(Project p, Class c)
Returns a helper for the given class, either from the cache or by creating a new instance.
MapgetNestedElementMap()
Returns a read-only map of nested elements supported by the introspected class.
EnumerationgetNestedElements()
Returns an enumeration of the names of the nested elements supported by the introspected class.
booleanisContainer()
Indicates whether the introspected class is a task container, supporting arbitrary nested tasks/types.
booleanisDynamic()
Indicates whether the introspected class is a dynamic one, supporting arbitrary nested elements and/or attributes.
voidmessageLogged(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.
voidsetAttribute(Project p, Object element, String attributeName, String value)
Sets the named attribute in the given element, which is part of the given project.
voidstoreElement(Project project, Object parent, Object child, String elementName)
Stores a named nested element using a storage method determined by the initial introspection.
booleansupportsCharacters()
Returns whether or not the introspected class supports PCDATA.
booleansupportsNestedElement(String elementName)
Indicates if this element supports a nested element of the given name.
booleansupportsNestedElement(String parentUri, String elementName)
Indicate if this element supports a nested element of the given name.
voidtargetFinished(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.
voidtargetStarted(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.
voidtaskFinished(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.
voidtaskStarted(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.
voidthrowNotSupported(Project project, Object parent, String elementName)
Utility method to throw a NotSupported exception

Method Detail

addText

public void addText(Project project, Object element, String text)
Adds PCDATA to an element, using the element's void addText(String) method, if it has one. If no such method is present, a BuildException is thrown if the given text contains non-whitespace.

Parameters: project The project which the element is part of. Must not be null. element The element to add the text to. Must not be null. text The text to add. Must not be null.

Throws: BuildException if non-whitespace text is provided and no method is available to handle it, or if the handling method fails.

buildFinished

public void buildFinished(BuildEvent event)
Clears all storage used by this class, including the static cache of helpers.

Parameters: event Ignored in this implementation.

buildStarted

public void buildStarted(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.

Parameters: event Ignored in this implementation.

createElement

public Object createElement(Project project, Object parent, String elementName)

Deprecated: This is not a namespace aware method.

Creates a named nested element. Depending on the results of the initial introspection, either a method in the given parent instance or a simple no-arg constructor is used to create an instance of the specified element type.

Parameters: project Project to which the parent object belongs. Must not be null. If the resulting object is an instance of ProjectComponent, its Project reference is set to this parameter value. parent Parent object used to create the instance. Must not be null. elementName Name of the element to create an instance of. Must not be null.

Returns: an instance of the specified element type

Throws: BuildException if no method is available to create the element instance, or if the creating method fails.

getAddTextMethod

public Method getAddTextMethod()
Returns the addText method when the introspected class supports nested text.

Returns: the method on this introspected class that adds nested text. Cannot be null.

Throws: BuildException if the introspected class does not support the nested text.

Since: Ant 1.6.3

getAttributeMap

public Map getAttributeMap()
Returns a read-only map of attributes supported by the introspected class.

Returns: an attribute name to attribute Class unmodifiable map. Can be empty, but never null.

Since: Ant 1.6.3

getAttributeMethod

public Method getAttributeMethod(String attributeName)
Returns the setter method of a named attribute.

Parameters: attributeName The name of the attribute to find the setter method of. Must not be null.

Returns: the method on this introspected class that sets this attribute. This will never be null.

Throws: BuildException if the introspected class does not support the named attribute.

Since: Ant 1.6.3

getAttributes

public Enumeration getAttributes()
Returns an enumeration of the names of the attributes supported by the introspected class.

Returns: an enumeration of the names of the attributes supported by the introspected class.

See Also: IntrospectionHelper

getAttributeType

public Class getAttributeType(String attributeName)
Returns the type of a named attribute.

Parameters: attributeName The name of the attribute to find the type of. Must not be null.

Returns: the type of the attribute with the specified name. This will never be null.

Throws: BuildException if the introspected class does not support the named attribute.

getElementCreator

public IntrospectionHelper.Creator getElementCreator(Project project, String parentUri, Object parent, String elementName, UnknownElement ue)
returns an object that creates and stores an object for an element of a parent.

Parameters: project Project to which the parent object belongs. parentUri The namespace uri of the parent object. parent Parent object used to create the creator object to create and store and instance of a subelement. elementName Name of the element to create an instance of. ue The unknown element associated with the element.

Returns: a creator object to create and store the element instance.

getElementMethod

public Method getElementMethod(String elementName)
Returns the adder or creator method of a named nested element.

Parameters: elementName The name of the attribute to find the setter method of. Must not be null.

Returns: the method on this introspected class that adds or creates this nested element. Can be null when the introspected class is a dynamic configurator!

Throws: BuildException if the introspected class does not support the named nested element.

Since: Ant 1.6.3

getElementName

protected String getElementName(Project project, Object element)
Returns a description of the type of the given element in relation to a given project. This is used for logging purposes when the element is asked to cope with some data it has no way of handling.

Parameters: project The project the element is defined in. Must not be null. element The element to describe. Must not be null.

Returns: a description of the element type

getElementType

public Class getElementType(String elementName)
Returns the type of a named nested element.

Parameters: elementName The name of the element to find the type of. Must not be null.

Returns: the type of the nested element with the specified name. This will never be null.

Throws: BuildException if the introspected class does not support the named nested element.

getExtensionPoints

public List getExtensionPoints()
Returns a read-only list of extension points supported by the introspected class.

A task/type or nested element with void methods named add() or addConfigured(), taking a single class or interface argument, supports extensions point. This method returns the list of all these void add[Configured](type) methods.

Returns: a list of void, single argument add() or addConfigured() Methods of all supported extension points. These methods are sorted such that if the argument type of a method derives from another type also an argument of a method of this list, the method with the most derived argument will always appear first. Can be empty, but never null.

Since: Ant 1.6.3

getHelper

public static IntrospectionHelper getHelper(Class c)
Returns a helper for the given class, either from the cache or by creating a new instance.

Parameters: c The class for which a helper is required. Must not be null.

Returns: a helper for the specified class

getHelper

public static IntrospectionHelper getHelper(Project p, Class c)
Returns a helper for the given class, either from the cache or by creating a new instance. The method will make sure the helper will be cleaned up at the end of the project, and only one instance will be created for each class.

Parameters: p the project instance. c The class for which a helper is required. Must not be null.

Returns: a helper for the specified class

getNestedElementMap

public Map getNestedElementMap()
Returns a read-only map of nested elements supported by the introspected class.

Returns: a nested-element name to nested-element Class unmodifiable map. Can be empty, but never null.

Since: Ant 1.6.3

getNestedElements

public Enumeration getNestedElements()
Returns an enumeration of the names of the nested elements supported by the introspected class.

Returns: an enumeration of the names of the nested elements supported by the introspected class.

See Also: IntrospectionHelper

isContainer

public boolean isContainer()
Indicates whether the introspected class is a task container, supporting arbitrary nested tasks/types.

Returns: true if the introspected class is a container; false otherwise.

Since: Ant 1.6.3

See Also: TaskContainer

isDynamic

public boolean isDynamic()
Indicates whether the introspected class is a dynamic one, supporting arbitrary nested elements and/or attributes.

Returns: true if the introspected class is dynamic; false otherwise.

Since: Ant 1.6.3

See Also: DynamicElement DynamicElementNS

messageLogged

public void messageLogged(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.

Parameters: event Ignored in this implementation.

setAttribute

public void setAttribute(Project p, Object element, String attributeName, String value)
Sets the named attribute in the given element, which is part of the given project.

Parameters: p The project containing the element. This is used when files need to be resolved. Must not be null. element The element to set the attribute in. Must not be null. attributeName The name of the attribute to set. Must not be null. value The value to set the attribute to. This may be interpreted or converted to the necessary type if the setter method doesn't just take a string. Must not be null.

Throws: BuildException if the introspected class doesn't support the given attribute, or if the setting method fails.

storeElement

public void storeElement(Project project, Object parent, Object child, String elementName)
Stores a named nested element using a storage method determined by the initial introspection. If no appropriate storage method is available, this method returns immediately.

Parameters: project Ignored in this implementation. May be null. parent Parent instance to store the child in. Must not be null. child Child instance to store in the parent. Should not be null. elementName Name of the child element to store. May be null, in which case this method returns immediately.

Throws: BuildException if the storage method fails.

supportsCharacters

public boolean supportsCharacters()
Returns whether or not the introspected class supports PCDATA.

Returns: whether or not the introspected class supports PCDATA.

supportsNestedElement

public boolean supportsNestedElement(String elementName)
Indicates if this element supports a nested element of the given name.

Parameters: elementName the name of the nested element being checked

Returns: true if the given nested element is supported

supportsNestedElement

public boolean supportsNestedElement(String parentUri, String elementName)
Indicate if this element supports a nested element of the given name.

Parameters: parentUri the uri of the parent elementName the name of the nested element being checked

Returns: true if the given nested element is supported

targetFinished

public void targetFinished(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.

Parameters: event Ignored in this implementation.

targetStarted

public void targetStarted(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.

Parameters: event Ignored in this implementation.

taskFinished

public void taskFinished(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.

Parameters: event Ignored in this implementation.

taskStarted

public void taskStarted(BuildEvent event)
Empty implementation to satisfy the BuildListener interface.

Parameters: event Ignored in this implementation.

throwNotSupported

public void throwNotSupported(Project project, Object parent, String elementName)
Utility method to throw a NotSupported exception

Parameters: project the Project instance. parent the object which doesn't support a requested element elementName the name of the Element which is trying to be created.

Copyright