org.apache.tools.ant

Class ProjectHelper

public class ProjectHelper extends Object

Configures a Project (complete with Targets and Tasks) based on a build file. It'll rely on a plugin to do the actual processing of the file.

This class also provide static wrappers for common introspection.

Field Summary
static StringANTLIB_URI
The URI for defined types/tasks - the format is antlib:
static StringANT_CORE_URI
The URI for ant name space
static StringANT_CURRENT_URI
The URI for antlib current definitions
static StringANT_TYPE
Polymorphic attribute
static StringHELPER_PROPERTY
Name of JVM system property which provides the name of the ProjectHelper class to use.
static StringPROJECTHELPER_REFERENCE
name of project helper reference that we add to a project
static StringSERVICE_ID
The service identifier in jars which provide Project Helper implementations.
Constructor Summary
ProjectHelper()
Default constructor
Method Summary
static BuildExceptionaddLocationToBuildException(BuildException ex, Location newLocation)
Add location to build exception.
static voidaddText(Project project, Object target, char[] buf, int start, int count)
Adds the content of #PCDATA sections to an element.
static voidaddText(Project project, Object target, String text)
Adds the content of #PCDATA sections to an element.
booleancanParseAntlibDescriptor(Resource r)
Whether this instance of ProjectHelper can parse an Antlib descriptor given by the URL and return its content as an UnknownElement ready to be turned into an Antlib task.
booleancanParseBuildFile(Resource buildFile)
Check if the helper supports the kind of file.
static voidconfigure(Object target, AttributeList attrs, Project project)
Configures an object using an introspection handler.
static voidconfigureProject(Project project, File buildFile)
Configures the project with the contents of the specified build file.
static StringextractNameFromComponentName(String componentName)
extract the element name from a component name
static StringextractUriFromComponentName(String componentName)
extract a uri from a component name
static StringgenComponentName(String uri, String name)
Map a namespaced {uri,name} to an internal string format.
static ClassLoadergetContextClassLoader()
JDK1.1 compatible access to the context class loader.
static StringgetCurrentPrefixSeparator()
The separator between the prefix and the target name.
static StringgetCurrentTargetPrefix()
The prefix to prepend to imported target names.
StringgetDefaultBuildFile()
The file name of the build script to be parsed if none specified on the command line
ListgetExtensionStack()
Extension stack.
VectorgetImportStack()
Import stack.
static ProjectHelpergetProjectHelper()
Get the first project helper found in the classpath
static booleanisInIncludeMode()
Whether the current file should be read in include as opposed to import mode.
voidparse(Project project, Object source)
Parses the project file, configuring the project as it goes.
UnknownElementparseAntlibDescriptor(Project containingProject, Resource source)
Parse the given URL as an antlib descriptor and return the content as something that can be turned into an Antlib task.
static voidparsePropertyString(String value, Vector fragments, Vector propertyRefs)
Parses a string containing ${xxx} style property references into two lists.
static StringreplaceProperties(Project project, String value)
Replaces ${xxx} style constructions in the given value with the string value of the corresponding properties.
static StringreplaceProperties(Project project, String value, Hashtable keys)
Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.
static voidsetCurrentPrefixSeparator(String sep)
Sets the separator between the prefix and the target name.
static voidsetCurrentTargetPrefix(String prefix)
Sets the prefix to prepend to imported target names.
static voidsetInIncludeMode(boolean includeMode)
Sets whether the current file should be read in include as opposed to import mode.
static voidstoreChild(Project project, Object parent, Object child, String tag)
Stores a configured child element within its parent object.

Field Detail

ANTLIB_URI

public static final String ANTLIB_URI
The URI for defined types/tasks - the format is antlib:

ANT_CORE_URI

public static final String ANT_CORE_URI
The URI for ant name space

ANT_CURRENT_URI

public static final String ANT_CURRENT_URI
The URI for antlib current definitions

ANT_TYPE

public static final String ANT_TYPE
Polymorphic attribute

HELPER_PROPERTY

public static final String HELPER_PROPERTY
Name of JVM system property which provides the name of the ProjectHelper class to use.

PROJECTHELPER_REFERENCE

public static final String PROJECTHELPER_REFERENCE
name of project helper reference that we add to a project

SERVICE_ID

public static final String SERVICE_ID
The service identifier in jars which provide Project Helper implementations.

Constructor Detail

ProjectHelper

public ProjectHelper()
Default constructor

Method Detail

addLocationToBuildException

public static BuildException addLocationToBuildException(BuildException ex, Location newLocation)
Add location to build exception.

Parameters: ex the build exception, if the build exception does not include newLocation the location of the calling task (may be null)

Returns: a new build exception based in the build exception with location set to newLocation. If the original exception did not have a location, just return the build exception

addText

public static void addText(Project project, Object target, char[] buf, int start, int count)
Adds the content of #PCDATA sections to an element.

Parameters: project The project containing the target. Must not be null. target The target object to be configured. Must not be null. buf A character array of the text within the element. Will not be null. start The start element in the array. count The number of characters to read from the array.

Throws: BuildException if the target object doesn't accept text

addText

public static void addText(Project project, Object target, String text)
Adds the content of #PCDATA sections to an element.

Parameters: project The project containing the target. Must not be null. target The target object to be configured. Must not be null. text Text to add to the target. May be null, in which case this method call is a no-op.

Throws: BuildException if the target object doesn't accept text

canParseAntlibDescriptor

public boolean canParseAntlibDescriptor(Resource r)
Whether this instance of ProjectHelper can parse an Antlib descriptor given by the URL and return its content as an UnknownElement ready to be turned into an Antlib task.

This method should not try to parse the content of the descriptor, the URL is only given as an argument to allow subclasses to decide whether they can support a given URL scheme or not.

Subclasses that return true in this method must also override parseAntlibDescriptor.

This implementation returns false.

Since: Ant 1.8.0

canParseBuildFile

public boolean canParseBuildFile(Resource buildFile)
Check if the helper supports the kind of file. Some basic check on the extension's file should be done here.

Parameters: buildFile the file expected to be parsed (never null)

Returns: true if the helper supports it

Since: Ant 1.8.0

configure

public static void configure(Object target, AttributeList attrs, Project project)

Deprecated: since 1.6.x. Use IntrospectionHelper for each property.

Configures an object using an introspection handler.

Parameters: target The target object to be configured. Must not be null. attrs A list of attributes to configure within the target. Must not be null. project The project containing the target. Must not be null.

Throws: BuildException if any of the attributes can't be handled by the target

configureProject

public static void configureProject(Project project, File buildFile)
Configures the project with the contents of the specified build file.

Parameters: project The project to configure. Must not be null. buildFile A build file giving the project's configuration. Must not be null.

Throws: BuildException if the configuration is invalid or cannot be read

extractNameFromComponentName

public static String extractNameFromComponentName(String componentName)
extract the element name from a component name

Parameters: componentName The stringified form for {uri, name}

Returns: The element name of the component

extractUriFromComponentName

public static String extractUriFromComponentName(String componentName)
extract a uri from a component name

Parameters: componentName The stringified form for {uri, name}

Returns: The uri or "" if not present

genComponentName

public static String genComponentName(String uri, String name)
Map a namespaced {uri,name} to an internal string format. For BC purposes the names from the ant core uri will be mapped to "name", other names will be mapped to uri + ":" + name.

Parameters: uri The namepace URI name The localname

Returns: The stringified form of the ns name

getContextClassLoader

public static ClassLoader getContextClassLoader()

Deprecated: since 1.6.x. Use LoaderUtils.getContextClassLoader()

JDK1.1 compatible access to the context class loader. Cut & paste from JAXP.

Returns: the current context class loader, or null if the context class loader is unavailable.

getCurrentPrefixSeparator

public static String getCurrentPrefixSeparator()
The separator between the prefix and the target name.

May be set by <import>'s prefixSeperator attribute.

Since: Ant 1.8.0

getCurrentTargetPrefix

public static String getCurrentTargetPrefix()
The prefix to prepend to imported target names.

May be set by <import>'s as attribute.

Returns: the configured prefix or null

Since: Ant 1.8.0

getDefaultBuildFile

public String getDefaultBuildFile()
The file name of the build script to be parsed if none specified on the command line

Returns: the name of the default file (never null)

Since: Ant 1.8.0

getExtensionStack

public List getExtensionStack()
Extension stack. Used to keep track of targets that extend extension points.

Returns: a list of two element string arrays where the first element is the name of the extensionpoint and the second the name of the target

getImportStack

public Vector getImportStack()
Import stack. Used to keep track of imported files. Error reporting should display the import path.

Returns: the stack of import source objects.

getProjectHelper

public static ProjectHelper getProjectHelper()
Get the first project helper found in the classpath

Returns: an project helper, never null

See Also: getHelpers

isInIncludeMode

public static boolean isInIncludeMode()
Whether the current file should be read in include as opposed to import mode.

In include mode included targets are only known by their prefixed names and their depends lists get rewritten so that all dependencies get the prefix as well.

In import mode imported targets are known by an adorned as well as a prefixed name and the unadorned target may be overwritten in the importing build file. The depends list of the imported targets is not modified at all.

Since: Ant 1.8.0

parse

public void parse(Project project, Object source)
Parses the project file, configuring the project as it goes.

Parameters: project The project for the resulting ProjectHelper to configure. Must not be null. source The source for XML configuration. A helper must support at least File, for backward compatibility. Helpers may support URL, InputStream, etc or specialized types.

Throws: BuildException if the configuration is invalid or cannot be read

Since: Ant1.5

parseAntlibDescriptor

public UnknownElement parseAntlibDescriptor(Project containingProject, Resource source)
Parse the given URL as an antlib descriptor and return the content as something that can be turned into an Antlib task.

Since: ant 1.8.0

parsePropertyString

public static void parsePropertyString(String value, Vector fragments, Vector propertyRefs)

Deprecated: since 1.6.x. Use PropertyHelper.

Parses a string containing ${xxx} style property references into two lists. The first list is a collection of text fragments, while the other is a set of string property names. null entries in the first list indicate a property reference from the second list.

As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.

Parameters: value Text to parse. Must not be null. fragments List to add text fragments to. Must not be null. propertyRefs List to add property names to. Must not be null.

Throws: BuildException if the string contains an opening ${ without a closing }

replaceProperties

public static String replaceProperties(Project project, String value)

Deprecated: since 1.6.x. Use project.replaceProperties().

Replaces ${xxx} style constructions in the given value with the string value of the corresponding properties.

Parameters: project The project containing the properties to replace. Must not be null. value The string to be scanned for property references. May be null.

Returns: the original string with the properties replaced, or null if the original string is null.

Throws: BuildException if the string contains an opening ${ without a closing }

Since: 1.5

replaceProperties

public static String replaceProperties(Project project, String value, Hashtable keys)

Deprecated: since 1.6.x. Use PropertyHelper.

Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.

Parameters: project The container project. This is used solely for logging purposes. Must not be null. value The string to be scanned for property references. May be null, in which case this method returns immediately with no effect. keys Mapping (String to String) of property names to their values. Must not be null.

Returns: the original string with the properties replaced, or null if the original string is null.

Throws: BuildException if the string contains an opening ${ without a closing }

setCurrentPrefixSeparator

public static void setCurrentPrefixSeparator(String sep)
Sets the separator between the prefix and the target name.

Since: Ant 1.8.0

setCurrentTargetPrefix

public static void setCurrentTargetPrefix(String prefix)
Sets the prefix to prepend to imported target names.

Since: Ant 1.8.0

setInIncludeMode

public static void setInIncludeMode(boolean includeMode)
Sets whether the current file should be read in include as opposed to import mode.

Since: Ant 1.8.0

storeChild

public static void storeChild(Project project, Object parent, Object child, String tag)
Stores a configured child element within its parent object.

Parameters: project Project containing the objects. May be null. parent Parent object to add child to. Must not be null. child Child object to store in parent. Should not be null. tag Name of element which generated the child. May be null, in which case the child is not stored.