Package org.apache.tools.ant

Class ProjectHelper

java.lang.Object

org.apache.tools.ant.ProjectHelper

Direct Known Subclasses:

ProjectHelper2, ProjectHelperImpl

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	ProjectHelper.OnMissingExtensionPoint	Possible value for target's onMissingExtensionPoint attribute.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ANT_ATTRIBUTE_URI	The URI for ant specific attributes
static final String	ANT_CORE_URI	The URI for ant name space
static final String	ANT_CURRENT_URI	The URI for antlib current definitions
static final String	ANT_TYPE	Polymorphic attribute
static final String	ANTLIB_URI	Deprecated. use MagicNames.ANTLIB_PREFIX
static final String	HELPER_PROPERTY	Deprecated. use MagicNames.PROJECT_HELPER_CLASS
static final String	PROJECTHELPER_REFERENCE	Deprecated. use MagicNames.REFID_PROJECT_HELPER
static final String	SERVICE_ID	Deprecated. use MagicNames.PROJECT_HELPER_SERVICE
static final String	USE_PROJECT_NAME_AS_TARGET_PREFIX	constant to denote use project name as target prefix

Constructor Summary

Constructors

Constructor	Description
ProjectHelper()

Method Summary

Modifier and Type	Method	Description
static BuildException	addLocationToBuildException(BuildException ex, Location newLocation)	Add location to build exception.
static void	addText(Project project, Object target, char[] buf, int start, int count)	Adds the content of #PCDATA sections to an element.
static void	addText(Project project, Object target, String text)	Adds the content of #PCDATA sections to an element.
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.
boolean	canParseBuildFile(Resource buildFile)	Check if the helper supports the kind of file.
static void	configure(Object target, AttributeList attrs, Project project)	Deprecated. since 1.6.x.
static void	configureProject(Project project, File buildFile)	Configures the project with the contents of the specified build file.
static String	extractNameFromComponentName(String componentName)	extract the element name from a component name
static String	extractUriFromComponentName(String componentName)	extract a uri from a component name
static String	genComponentName(String uri, String name)	Map a namespaced {uri,name} to an internal string format.
static ClassLoader	getContextClassLoader()	Deprecated. since 1.6.x.
static String	getCurrentPrefixSeparator()	The separator between the prefix and the target name.
static String	getCurrentTargetPrefix()	The prefix to prepend to imported target names.
String	getDefaultBuildFile()	The file name of the build script to be parsed if none specified on the command line
List<String[]>	getExtensionStack()	Extension stack.
Vector<Object>	getImportStack()	Import stack.
static ProjectHelper	getProjectHelper()	Get the first project helper found in the classpath
static boolean	isInIncludeMode()	Whether the current file should be read in include as opposed to import mode.
static String	nsToComponentName(String ns)	Convert an attribute namespace to a "component name".
void	parse(Project project, Object source)	Parses the project file, configuring the project as it goes.
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.
static void	parsePropertyString(String value, Vector<String> fragments, Vector<String> propertyRefs)	Deprecated. since 1.6.x.
static String	replaceProperties(Project project, String value)	Deprecated. since 1.6.x.
static String	replaceProperties(Project project, String value, Hashtable<String,Object> keys)	Deprecated. since 1.6.x.
void	resolveExtensionOfAttributes(Project project)	Check extensionStack and inject all targets having extensionOf attributes into extensionPoint.
static void	setCurrentPrefixSeparator(String sep)	Sets the separator between the prefix and the target name.
static void	setCurrentTargetPrefix(String prefix)	Sets the prefix to prepend to imported target names.
static void	setInIncludeMode(boolean includeMode)	Sets whether the current file should be read in include as opposed to import mode.
static void	storeChild(Project project, Object parent, Object child, String tag)	Stores a configured child element within its parent object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

ANT_CORE_URI

public static final String ANT_CORE_URI

The URI for ant name space

See Also:

• Constant Field Values

ANT_CURRENT_URI

public static final String ANT_CURRENT_URI

The URI for antlib current definitions

See Also:

• Constant Field Values

ANT_ATTRIBUTE_URI

public static final String ANT_ATTRIBUTE_URI

The URI for ant specific attributes

Since:

Ant 1.9.1

See Also:

• Constant Field Values

ANTLIB_URI

@Deprecated
public static final String ANTLIB_URI

Deprecated.

use MagicNames.ANTLIB_PREFIX

The URI for defined types/tasks - the format is antlib:<package>

See Also:

• Constant Field Values

ANT_TYPE

public static final String ANT_TYPE

Polymorphic attribute

See Also:

• Constant Field Values

HELPER_PROPERTY

@Deprecated
public static final String HELPER_PROPERTY

Deprecated.

use MagicNames.PROJECT_HELPER_CLASS

Name of JVM system property which provides the name of the ProjectHelper class to use.

See Also:

• Constant Field Values

SERVICE_ID

@Deprecated
public static final String SERVICE_ID

Deprecated.

use MagicNames.PROJECT_HELPER_SERVICE

The service identifier in jars which provide Project Helper implementations.

See Also:

• Constant Field Values

PROJECTHELPER_REFERENCE

@Deprecated
public static final String PROJECTHELPER_REFERENCE

Deprecated.

use MagicNames.REFID_PROJECT_HELPER

name of project helper reference that we add to a project

See Also:

• Constant Field Values

USE_PROJECT_NAME_AS_TARGET_PREFIX

public static final String USE_PROJECT_NAME_AS_TARGET_PREFIX

constant to denote use project name as target prefix

Since:

Ant 1.9.1

See Also:

• Constant Field Values

Constructor Details

ProjectHelper

public ProjectHelper()

Method Details

configureProject

public static void configureProject(Project project,
 File buildFile)
                             throws BuildException

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

getImportStack

public Vector<Object> getImportStack()

Import stack. Used to keep track of imported files. Error reporting should display the import path.

Returns:

the stack of import source objects.

getExtensionStack

public List<String[]> getExtensionStack()

Extension stack. Used to keep track of targets that extend extension points.

Returns:

a list of three element string arrays where the first element is the name of the extensionpoint, the second the name of the target and the third the name of the enum like class ProjectHelper.OnMissingExtensionPoint.

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

setCurrentTargetPrefix

public static void setCurrentTargetPrefix(String prefix)

Sets the prefix to prepend to imported target names.

Parameters:

prefix - String

Since:

Ant 1.8.0

getCurrentPrefixSeparator

public static String getCurrentPrefixSeparator()

The separator between the prefix and the target name.

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

Returns:

String

Since:

Ant 1.8.0

setCurrentPrefixSeparator

public static void setCurrentPrefixSeparator(String sep)

Sets the separator between the prefix and the target name.

Parameters:

sep - String

Since:

Ant 1.8.0

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.

Returns:

boolean

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.

Parameters:

includeMode - boolean

Since:

Ant 1.8.0

parse

public void parse(Project project,
 Object source)
           throws BuildException

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

getProjectHelper

public static ProjectHelper getProjectHelper()

Get the first project helper found in the classpath

Returns:

an project helper, never null

See Also:

• ProjectHelperRepository.getHelpers()

getContextClassLoader

@Deprecated
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.

configure

@Deprecated
public static void configure(Object target,
 AttributeList attrs,
 Project project)
                      throws BuildException

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

addText

public static void addText(Project project,
 Object target,
 char[] buf,
 int start,
 int count)
                    throws BuildException

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)
                    throws BuildException

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

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.

replaceProperties

@Deprecated
public static String replaceProperties(Project project,
 String value)
                                throws BuildException

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

@Deprecated
public static String replaceProperties(Project project,
 String value,
 Hashtable<String,Object> keys)
                                throws BuildException

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 Object) 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 }

parsePropertyString

@Deprecated
public static void parsePropertyString(String value,
 Vector<String> fragments,
 Vector<String> propertyRefs)
                                throws BuildException

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 }

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 namespace URI

name - The localname

Returns:

The stringified form of the ns name

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

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

nsToComponentName

public static String nsToComponentName(String ns)

Convert an attribute namespace to a "component name".

Parameters:

ns - the xml namespace uri.

Returns:

the converted value.

Since:

Ant 1.9.1

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

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.

Parameters:

r - Resource

Returns:

boolean

Since:

Ant 1.8.0

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.

Parameters:

containingProject - Project

source - Resource

Returns:

UnknownElement

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

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

resolveExtensionOfAttributes

public void resolveExtensionOfAttributes(Project project)
                                  throws BuildException

Check extensionStack and inject all targets having extensionOf attributes into extensionPoint.

This method allow you to defer injection and have a powerful control of extensionPoint wiring.

This should be invoked by each concrete implementation of ProjectHelper when the root "buildfile" and all imported/included buildfile are loaded.

Parameters:

project - The project containing the target. Must not be null.

Throws:

BuildException - if OnMissingExtensionPoint.FAIL and extensionPoint does not exist

Since:

1.9

See Also:

• ProjectHelper.OnMissingExtensionPoint