org.apache.tools.ant

Class Project

public class Project extends Object implements ResourceFactory

Central representation of an Ant project. This class defines an Ant project with all of its targets, tasks and various other properties. It also provides the mechanism to kick off a build using a particular target name.

This class also encapsulates methods which allow files to be referred to using abstract path names which are translated to native system file paths at runtime.

Field Summary
static StringJAVA_1_0
Version constant for Java 1.0 .
static StringJAVA_1_1
Version constant for Java 1.1 .
static StringJAVA_1_2
Version constant for Java 1.2 .
static StringJAVA_1_3
Version constant for Java 1.3 .
static StringJAVA_1_4
Version constant for Java 1.4 .
static intMSG_DEBUG
Message priority of "debug".
static intMSG_ERR
Message priority of "error".
static intMSG_INFO
Message priority of "information".
static intMSG_VERBOSE
Message priority of "verbose".
static intMSG_WARN
Message priority of "warning".
static StringTOKEN_END
Default filter end token.
static StringTOKEN_START
Default filter start token.
Constructor Summary
Project()
Create a new Ant project.
Method Summary
voidaddBuildListener(BuildListener listener)
Add a build listener to the list.
voidaddDataTypeDefinition(String typeName, Class typeClass)
Add a new datatype definition.
voidaddFilter(String token, String value)
Add a filter to the set of global filters.
voidaddIdReference(String id, Object value)
Add an id reference.
voidaddOrReplaceTarget(Target target)
Add a target to the project, or replaces one with the same name.
voidaddOrReplaceTarget(String targetName, Target target)
Add a target to the project, or replaces one with the same name.
voidaddReference(String referenceName, Object value)
Add a reference to the project.
voidaddTarget(Target target)
Add a new target to the project.
voidaddTarget(String targetName, Target target)
Add a new target to the project.
voidaddTaskDefinition(String taskName, Class taskClass)
Add a new task definition to the project.
voidcheckTaskClass(Class taskClass)
Check whether or not a class is suitable for serving as Ant task.
voidcopyFile(String sourceFile, String destFile)
Convenience method to copy a file from a source to a destination.
voidcopyFile(String sourceFile, String destFile, boolean filtering)
Convenience method to copy a file from a source to a destination specifying if token filtering should be used.
voidcopyFile(String sourceFile, String destFile, boolean filtering, boolean overwrite)
Convenience method to copy a file from a source to a destination specifying if token filtering should be used and if source files may overwrite newer destination files.
voidcopyFile(String sourceFile, String destFile, boolean filtering, boolean overwrite, boolean preserveLastModified)
Convenience method to copy a file from a source to a destination specifying if token filtering should be used, if source files may overwrite newer destination files, and if the last modified time of the resulting file should be set to that of the source file.
voidcopyFile(File sourceFile, File destFile)
Convenience method to copy a file from a source to a destination.
voidcopyFile(File sourceFile, File destFile, boolean filtering)
Convenience method to copy a file from a source to a destination specifying if token filtering should be used.
voidcopyFile(File sourceFile, File destFile, boolean filtering, boolean overwrite)
Convenience method to copy a file from a source to a destination specifying if token filtering should be used and if source files may overwrite newer destination files.
voidcopyFile(File sourceFile, File destFile, boolean filtering, boolean overwrite, boolean preserveLastModified)
Convenience method to copy a file from a source to a destination specifying if token filtering should be used, if source files may overwrite newer destination files, and if the last modified time of the resulting file should be set to that of the source file.
voidcopyInheritedProperties(Project other)
Copy all user properties that have not been set on the command line or a GUI tool from this instance to the Project instance given as the argument.
voidcopyUserProperties(Project other)
Copy all user properties that have been set on the command line or a GUI tool from this instance to the Project instance given as the argument.
AntClassLoadercreateClassLoader(Path path)
Factory method to create a class loader for loading classes from a given path.
AntClassLoadercreateClassLoader(ClassLoader parent, Path path)
Factory method to create a class loader for loading classes from a given path.
ObjectcreateDataType(String typeName)
Create a new instance of a data type.
ProjectcreateSubProject()
Create and initialize a subproject.
TaskcreateTask(String taskType)
Create a new instance of a task, adding it to a list of created tasks for later invalidation.
intdefaultInput(byte[] buffer, int offset, int length)
Read data from the default input stream.
voiddemuxFlush(String output, boolean isError)
Demultiplex flush operations so that each task receives the appropriate messages.
intdemuxInput(byte[] buffer, int offset, int length)
Demux an input request to the correct task.
voiddemuxOutput(String output, boolean isWarning)
Demultiplex output so that each task receives the appropriate messages.
voidexecuteSortedTargets(Vector sortedTargets)
Execute a Vector of sorted targets.
voidexecuteTarget(String targetName)
Execute the specified target and any targets it depends on.
voidexecuteTargets(Vector names)
Execute the specified sequence of targets, and the targets they depend on.
voidfireBuildFinished(Throwable exception)
Send a "build finished" event to the build listeners for this project.
voidfireBuildStarted()
Send a "build started" event to the build listeners for this project.
protected voidfireMessageLogged(Project project, String message, int priority)
Send a "message logged" project level event to the build listeners for this project.
protected voidfireMessageLogged(Project project, String message, Throwable throwable, int priority)
Send a "message logged" project level event to the build listeners for this project.
protected voidfireMessageLogged(Target target, String message, int priority)
Send a "message logged" target level event to the build listeners for this project.
protected voidfireMessageLogged(Target target, String message, Throwable throwable, int priority)
Send a "message logged" target level event to the build listeners for this project.
protected voidfireMessageLogged(Task task, String message, int priority)
Send a "message logged" task level event to the build listeners for this project.
protected voidfireMessageLogged(Task task, String message, Throwable throwable, int priority)
Send a "message logged" task level event to the build listeners for this project.
voidfireSubBuildFinished(Throwable exception)
Send a "subbuild finished" event to the build listeners for this project.
voidfireSubBuildStarted()
Send a "subbuild started" event to the build listeners for this project.
protected voidfireTargetFinished(Target target, Throwable exception)
Send a "target finished" event to the build listeners for this project.
protected voidfireTargetStarted(Target target)
Send a "target started" event to the build listeners for this project.
protected voidfireTaskFinished(Task task, Throwable exception)
Send a "task finished" event to the build listeners for this project.
protected voidfireTaskStarted(Task task)
Send a "task started" event to the build listeners for this project.
FilegetBaseDir()
Return the base directory of the project as a file object.
VectorgetBuildListeners()
Return a copy of the list of build listeners for the project.
ClassLoadergetCoreLoader()
Return the core classloader to use for this project.
HashtablegetDataTypeDefinitions()
Return the current datatype definition hashtable.
InputStreamgetDefaultInputStream()
Get this project's input stream.
StringgetDefaultTarget()
Return the name of the default target of the project.
StringgetDescription()
Return the project description, if one has been set.
StringgetElementName(Object element)
Return a description of the type of the given element, with special handling for instances of tasks and data types.
ExecutorgetExecutor()
Get this Project's Executor (setting it if necessary).
HashtablegetFilters()
Return a hashtable of global filters, mapping tokens to values.
FilterSetgetGlobalFilterSet()
Return the set of global filters.
InputHandlergetInputHandler()
Retrieve the current input handler.
static StringgetJavaVersion()
Return the version of Java this class is running under.
StringgetName()
Return the project name, if one has been set.
HashtablegetProperties()
Return a copy of the properties table.
StringgetProperty(String propertyName)
Return the value of a property, if it is set.
ObjectgetReference(String key)
Look up a reference by its key (ID).
HashtablegetReferences()
Return a map of the references in the project (String to Object).
ResourcegetResource(String name)
Resolve the file relative to the project's basedir and return it as a FileResource.
HashtablegetTargets()
Return the hashtable of targets.
HashtablegetTaskDefinitions()
Return the current task definition hashtable.
TaskgetThreadTask(Thread thread)
Get the current task associated with a thread, if any.
HashtablegetUserProperties()
Return a copy of the user property hashtable.
StringgetUserProperty(String propertyName)
Return the value of a user property, if it is set.
voidinheritIDReferences(Project parent)
Inherit the id references.
voidinit()
Initialise the project.
voidinitProperties()
Initializes the properties.
voidinitSubProject(Project subProject)
Initialize a subproject.
booleanisKeepGoingMode()
Return the keep-going mode.
voidlog(String message)
Write a message to the log with the default log level of MSG_INFO .
voidlog(String message, int msgLevel)
Write a project level message to the log with the given log level.
voidlog(String message, Throwable throwable, int msgLevel)
Write a project level message to the log with the given log level.
voidlog(Task task, String message, int msgLevel)
Write a task level message to the log with the given log level.
voidlog(Task task, String message, Throwable throwable, int msgLevel)
Write a task level message to the log with the given log level.
voidlog(Target target, String message, int msgLevel)
Write a target level message to the log with the given log level.
voidlog(Target target, String message, Throwable throwable, int msgLevel)
Write a target level message to the log with the given log level.
voidregisterThreadTask(Thread thread, Task task)
Register a task as the current task for a thread.
voidremoveBuildListener(BuildListener listener)
Remove a build listener from the list.
StringreplaceProperties(String value)
Replace ${} style constructions in the given value with the string value of the corresponding data types.
FileresolveFile(String fileName, File rootDir)
Return the canonical form of a filename.
FileresolveFile(String fileName)
Return the canonical form of a filename.
voidsetBasedir(String baseD)
Set the base directory for the project, checking that the given filename exists and is a directory.
voidsetBaseDir(File baseDir)
Set the base directory for the project, checking that the given file exists and is a directory.
voidsetCoreLoader(ClassLoader coreLoader)
Set the core classloader for the project.
voidsetDefault(String defaultTarget)
Set the default target of the project.
voidsetDefaultInputStream(InputStream defaultInputStream)
Set the default System input stream.
voidsetDefaultTarget(String defaultTarget)
Set the default target of the project.
voidsetDescription(String description)
Set the project description.
voidsetExecutor(Executor e)
Set the Executor instance for this Project.
voidsetFileLastModified(File file, long time)
Call File.setLastModified(long time) on Java above 1.1, and logs a warning on Java 1.1.
voidsetInheritedProperty(String name, String value)
Set a user property, which cannot be overwritten by set/unset property calls.
voidsetInputHandler(InputHandler handler)
Set the input handler.
voidsetJavaVersionProperty()
Set the ant.java.version property and tests for unsupported JVM versions.
voidsetKeepGoingMode(boolean keepGoingMode)
Set "keep-going" mode.
voidsetName(String name)
Set the name of the project, also setting the user property ant.project.name.
voidsetNewProperty(String name, String value)
Set a property if no value currently exists.
voidsetProjectReference(Object obj)
Set a reference to this Project on the parameterized object.
voidsetProperty(String name, String value)
Set a property.
voidsetSystemProperties()
Add all system properties which aren't already defined as user properties to the project properties.
voidsetUserProperty(String name, String value)
Set a user property, which cannot be overwritten by set/unset property calls.
static booleantoBoolean(String s)
Return the boolean equivalent of a string, which is considered true if either "on", "true", or "yes" is found, ignoring case.
VectortopoSort(String root, Hashtable targetTable)
Topologically sort a set of targets.
VectortopoSort(String root, Hashtable targetTable, boolean returnAll)
Topologically sort a set of targets.
VectortopoSort(String[] root, Hashtable targetTable, boolean returnAll)
Topologically sort a set of targets.
static StringtranslatePath(String toProcess)
Translate a path into its native (platform specific) format.

Field Detail

JAVA_1_0

public static final String JAVA_1_0

Deprecated: since 1.5.x. Use JAVA_1_0 instead.

Version constant for Java 1.0 .

JAVA_1_1

public static final String JAVA_1_1

Deprecated: since 1.5.x. Use JAVA_1_1 instead.

Version constant for Java 1.1 .

JAVA_1_2

public static final String JAVA_1_2

Deprecated: since 1.5.x. Use JAVA_1_2 instead.

Version constant for Java 1.2 .

JAVA_1_3

public static final String JAVA_1_3

Deprecated: since 1.5.x. Use JAVA_1_3 instead.

Version constant for Java 1.3 .

JAVA_1_4

public static final String JAVA_1_4

Deprecated: since 1.5.x. Use JAVA_1_4 instead.

Version constant for Java 1.4 .

MSG_DEBUG

public static final int MSG_DEBUG
Message priority of "debug".

MSG_ERR

public static final int MSG_ERR
Message priority of "error".

MSG_INFO

public static final int MSG_INFO
Message priority of "information".

MSG_VERBOSE

public static final int MSG_VERBOSE
Message priority of "verbose".

MSG_WARN

public static final int MSG_WARN
Message priority of "warning".

TOKEN_END

public static final String TOKEN_END
Default filter end token.

TOKEN_START

public static final String TOKEN_START
Default filter start token.

Constructor Detail

Project

public Project()
Create a new Ant project.

Method Detail

addBuildListener

public void addBuildListener(BuildListener listener)
Add a build listener to the list. This listener will be notified of build events for this project.

Parameters: listener The listener to add to the list. Must not be null.

addDataTypeDefinition

public void addDataTypeDefinition(String typeName, Class typeClass)
Add 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 be null. typeClass The full name of the class implementing the datatype. Must not be null.

addFilter

public void addFilter(String token, String value)

Deprecated: since 1.4.x. Use getGlobalFilterSet().addFilter(token,value)

Add a filter to the set of global filters.

Parameters: token The token to filter. Must not be null. value The replacement value. Must not be null.

See Also: getGlobalFilterSet addFilter

addIdReference

public void addIdReference(String id, Object value)
Add an id reference. Used for broken build files.

Parameters: id the id to set. value the value to set it to (Unknown element in this case.

addOrReplaceTarget

public void addOrReplaceTarget(Target target)
Add a target to the project, or replaces one with the same name.

Parameters: target The target to be added or replaced in the project. Must not be null.

addOrReplaceTarget

public void addOrReplaceTarget(String targetName, Target target)
Add a target to the project, or replaces one with the same name.

Parameters: targetName The name to use for the target. Must not be null. target The target to be added or replaced in the project. Must not be null.

addReference

public void addReference(String referenceName, Object value)
Add a reference to the project.

Parameters: referenceName The name of the reference. Must not be null. value The value of the reference.

addTarget

public void addTarget(Target target)
Add a new target to the project.

Parameters: target The target to be added to the project. Must not be null.

Throws: BuildException if the target already exists in the project

See Also: addOrReplaceTarget

addTarget

public void addTarget(String targetName, Target target)
Add a new target to the project.

Parameters: targetName The name to use for the target. Must not be null. target The target to be added to the project. Must not be null.

Throws: BuildException if the target already exists in the project.

See Also: Project

addTaskDefinition

public void addTaskDefinition(String taskName, Class taskClass)
Add 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 and invalidates any tasks which have already been created with the old definition.

Parameters: taskName The name of the task to add. Must not be null. taskClass The full name of the class implementing the task. Must not be null.

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

checkTaskClass

public void checkTaskClass(Class taskClass)
Check 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 be null.

Throws: BuildException if the class is unsuitable for being an Ant task. An error level message is logged before this exception is thrown.

copyFile

public void copyFile(String sourceFile, String destFile)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination. No filtering is performed.

Parameters: sourceFile Name of file to copy from. Must not be null. destFile Name of file to copy to. Must not be null.

Throws: IOException if the copying fails.

copyFile

public void copyFile(String sourceFile, String destFile, boolean filtering)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination specifying if token filtering should be used.

Parameters: sourceFile Name of file to copy from. Must not be null. destFile Name of file to copy to. Must not be null. filtering Whether or not token filtering should be used during the copy.

Throws: IOException if the copying fails.

copyFile

public void copyFile(String sourceFile, String destFile, boolean filtering, boolean overwrite)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination specifying if token filtering should be used and if source files may overwrite newer destination files.

Parameters: sourceFile Name of file to copy from. Must not be null. destFile Name of file to copy to. Must not be null. filtering Whether or not token filtering should be used during the copy. overwrite Whether or not the destination file should be overwritten if it already exists.

Throws: IOException if the copying fails.

copyFile

public void copyFile(String sourceFile, String destFile, boolean filtering, boolean overwrite, boolean preserveLastModified)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination specifying if token filtering should be used, if source files may overwrite newer destination files, and if the last modified time of the resulting file should be set to that of the source file.

Parameters: sourceFile Name of file to copy from. Must not be null. destFile Name of file to copy to. Must not be null. filtering Whether or not token filtering should be used during the copy. overwrite Whether or not the destination file should be overwritten if it already exists. preserveLastModified Whether or not the last modified time of the resulting file should be set to that of the source file.

Throws: IOException if the copying fails.

copyFile

public void copyFile(File sourceFile, File destFile)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination. No filtering is performed.

Parameters: sourceFile File to copy from. Must not be null. destFile File to copy to. Must not be null.

Throws: IOException if the copying fails.

copyFile

public void copyFile(File sourceFile, File destFile, boolean filtering)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination specifying if token filtering should be used.

Parameters: sourceFile File to copy from. Must not be null. destFile File to copy to. Must not be null. filtering Whether or not token filtering should be used during the copy.

Throws: IOException if the copying fails.

copyFile

public void copyFile(File sourceFile, File destFile, boolean filtering, boolean overwrite)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination specifying if token filtering should be used and if source files may overwrite newer destination files.

Parameters: sourceFile File to copy from. Must not be null. destFile File to copy to. Must not be null. filtering Whether or not token filtering should be used during the copy. overwrite Whether or not the destination file should be overwritten if it already exists.

Throws: IOException if the file cannot be copied.

copyFile

public void copyFile(File sourceFile, File destFile, boolean filtering, boolean overwrite, boolean preserveLastModified)

Deprecated: since 1.4.x

Convenience method to copy a file from a source to a destination specifying if token filtering should be used, if source files may overwrite newer destination files, and if the last modified time of the resulting file should be set to that of the source file.

Parameters: sourceFile File to copy from. Must not be null. destFile File to copy to. Must not be null. filtering Whether or not token filtering should be used during the copy. overwrite Whether or not the destination file should be overwritten if it already exists. preserveLastModified Whether or not the last modified time of the resulting file should be set to that of the source file.

Throws: IOException if the file cannot be copied.

copyInheritedProperties

public void copyInheritedProperties(Project other)
Copy all user properties that have not been set on the command line or a GUI tool from this instance to the Project instance given as the argument.

To copy all "user" properties, you will also have to call copyUserProperties.

Parameters: other the project to copy the properties to. Must not be null.

Since: Ant 1.5

copyUserProperties

public void copyUserProperties(Project other)
Copy all user properties that have been set on the command line or a GUI tool from this instance to the Project instance given as the argument.

To copy all "user" properties, you will also have to call copyInheritedProperties.

Parameters: other the project to copy the properties to. Must not be null.

Since: Ant 1.5

createClassLoader

public AntClassLoader createClassLoader(Path path)
Factory method to create a class loader for loading classes from a given path.

Parameters: path the path from which classes are to be loaded.

Returns: an appropriate classloader.

createClassLoader

public AntClassLoader createClassLoader(ClassLoader parent, Path path)
Factory method to create a class loader for loading classes from a given path.

Parameters: parent the parent classloader for the new loader. path the path from which classes are to be loaded.

Returns: an appropriate classloader.

createDataType

public Object createDataType(String typeName)
Create a new instance of a data type.

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

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

Throws: BuildException if the data type name is recognised but instance creation fails.

createSubProject

public Project createSubProject()
Create and initialize a subproject. By default the subproject will be of the same type as its parent. If a no-arg constructor is unavailable, the Project class will be used.

Returns: a Project instance configured as a subproject of this Project.

Since: Ant 1.7

createTask

public Task createTask(String taskType)
Create a new instance of a task, adding it to a list of created tasks for later invalidation. This causes all tasks to be remembered until the containing project is removed

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

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

Throws: BuildException if the task name is recognised but task creation fails.

defaultInput

public int defaultInput(byte[] buffer, int offset, int length)
Read data from the default input stream. If no default has been specified, System.in is used.

Parameters: buffer the buffer into which data is to be read. offset the offset into the buffer at which data is stored. length the amount of data to read.

Returns: the number of bytes read.

Throws: IOException if the data cannot be read.

Since: Ant 1.6

demuxFlush

public void demuxFlush(String output, boolean isError)
Demultiplex flush operations so that each task receives the appropriate messages. If the current thread is not currently executing a task, the message is logged directly.

Parameters: output Message to handle. Should not be null. isError Whether the text represents an error (true) or information (false).

Since: Ant 1.5.2

demuxInput

public int demuxInput(byte[] buffer, int offset, int length)
Demux an input request to the correct task.

Parameters: buffer the buffer into which data is to be read. offset the offset into the buffer at which data is stored. length the amount of data to read.

Returns: the number of bytes read.

Throws: IOException if the data cannot be read.

Since: Ant 1.6

demuxOutput

public void demuxOutput(String output, boolean isWarning)
Demultiplex output so that each task receives the appropriate messages. If the current thread is not currently executing a task, the message is logged directly.

Parameters: output Message to handle. Should not be null. isWarning Whether the text represents an warning (true) or information (false).

executeSortedTargets

public void executeSortedTargets(Vector sortedTargets)
Execute a Vector of sorted targets.

Parameters: sortedTargets the aforementioned Vector.

Throws: BuildException on error.

executeTarget

public void executeTarget(String targetName)
Execute the specified target and any targets it depends on.

Parameters: targetName The name of the target to execute. Must not be null.

Throws: BuildException if the build failed.

executeTargets

public void executeTargets(Vector names)
Execute the specified sequence of targets, and the targets they depend on.

Parameters: names A vector of target name strings to execute. Must not be null.

Throws: BuildException if the build failed.

fireBuildFinished

public void fireBuildFinished(Throwable exception)
Send a "build finished" event to the build listeners for this project.

Parameters: exception an exception indicating a reason for a build failure. May be null, indicating a successful build.

fireBuildStarted

public void fireBuildStarted()
Send a "build started" event to the build listeners for this project.

fireMessageLogged

protected void fireMessageLogged(Project project, String message, int priority)
Send a "message logged" project level event to the build listeners for this project.

Parameters: project The project generating the event. Should not be null. message The message to send. Should not be null. priority The priority of the message.

fireMessageLogged

protected void fireMessageLogged(Project project, String message, Throwable throwable, int priority)
Send a "message logged" project level event to the build listeners for this project.

Parameters: project The project generating the event. Should not be null. message The message to send. Should not be null. throwable The exception that caused this message. May be null. priority The priority of the message.

Since: 1.7

fireMessageLogged

protected void fireMessageLogged(Target target, String message, int priority)
Send a "message logged" target level event to the build listeners for this project.

Parameters: target The target generating the event. Must not be null. message The message to send. Should not be null. priority The priority of the message.

fireMessageLogged

protected void fireMessageLogged(Target target, String message, Throwable throwable, int priority)
Send a "message logged" target level event to the build listeners for this project.

Parameters: target The target generating the event. Must not be null. message The message to send. Should not be null. throwable The exception that caused this message. May be null. priority The priority of the message.

Since: 1.7

fireMessageLogged

protected void fireMessageLogged(Task task, String message, int priority)
Send a "message logged" task level event to the build listeners for this project.

Parameters: task The task generating the event. Must not be null. message The message to send. Should not be null. priority The priority of the message.

fireMessageLogged

protected void fireMessageLogged(Task task, String message, Throwable throwable, int priority)
Send a "message logged" task level event to the build listeners for this project.

Parameters: task The task generating the event. Must not be null. message The message to send. Should not be null. throwable The exception that caused this message. May be null. priority The priority of the message.

Since: 1.7

fireSubBuildFinished

public void fireSubBuildFinished(Throwable exception)
Send a "subbuild finished" event to the build listeners for this project.

Parameters: exception an exception indicating a reason for a build failure. May be null, indicating a successful build.

Since: Ant 1.6.2

fireSubBuildStarted

public void fireSubBuildStarted()
Send a "subbuild started" event to the build listeners for this project.

Since: Ant 1.6.2

fireTargetFinished

protected void fireTargetFinished(Target target, Throwable exception)
Send a "target finished" event to the build listeners for this project.

Parameters: target The target which has finished building. Must not be null. exception an exception indicating a reason for a build failure. May be null, indicating a successful build.

fireTargetStarted

protected void fireTargetStarted(Target target)
Send a "target started" event to the build listeners for this project.

Parameters: target The target which is starting to build. Must not be null.

fireTaskFinished

protected void fireTaskFinished(Task task, Throwable exception)
Send a "task finished" event to the build listeners for this project.

Parameters: task The task which has finished executing. Must not be null. exception an exception indicating a reason for a build failure. May be null, indicating a successful build.

fireTaskStarted

protected void fireTaskStarted(Task task)
Send a "task started" event to the build listeners for this project.

Parameters: task The target which is starting to execute. Must not be null.

getBaseDir

public File getBaseDir()
Return the base directory of the project as a file object.

Returns: the project base directory, or null if the base directory has not been successfully set to a valid value.

getBuildListeners

public Vector getBuildListeners()
Return a copy of the list of build listeners for the project.

Returns: a list of build listeners for the project

getCoreLoader

public ClassLoader getCoreLoader()
Return the core classloader to use for this project. This may be null, indicating that the parent classloader should be used.

Returns: the core classloader to use for this project.

getDataTypeDefinitions

public Hashtable getDataTypeDefinitions()
Return the current datatype definition hashtable. The returned hashtable is "live" and so should not be modified.

Returns: a map of from datatype name to implementing class (String to Class).

getDefaultInputStream

public InputStream getDefaultInputStream()
Get this project's input stream.

Returns: the InputStream instance in use by this Project instance to read input.

getDefaultTarget

public String getDefaultTarget()
Return the name of the default target of the project.

Returns: name of the default target or null if no default has been set.

getDescription

public String getDescription()
Return the project description, if one has been set.

Returns: the project description, or null if it hasn't been set.

getElementName

public String getElementName(Object element)
Return a description of the type of the given element, with special handling for instances of tasks and data types.

This is useful for logging purposes.

Parameters: element The element to describe. Must not be null.

Returns: a description of the element type.

Since: 1.95, Ant 1.5

getExecutor

public Executor getExecutor()
Get this Project's Executor (setting it if necessary).

Returns: an Executor instance.

getFilters

public Hashtable getFilters()

Deprecated: since 1.4.x Use getGlobalFilterSet().getFilterHash().

Return a hashtable of global filters, mapping tokens to values.

Returns: a hashtable of global filters, mapping tokens to values (String to String).

See Also: getGlobalFilterSet getFilterHash

getGlobalFilterSet

public FilterSet getGlobalFilterSet()
Return the set of global filters.

Returns: the set of global filters.

getInputHandler

public InputHandler getInputHandler()
Retrieve the current input handler.

Returns: the InputHandler instance currently in place for the project instance.

getJavaVersion

public static String getJavaVersion()

Deprecated: since 1.5.x. Use org.apache.tools.ant.util.JavaEnvUtils instead.

Return the version of Java this class is running under.

Returns: the version of Java as a String, e.g. "1.1" .

See Also: JavaEnvUtils

getName

public String getName()
Return the project name, if one has been set.

Returns: the project name, or null if it hasn't been set.

getProperties

public Hashtable getProperties()
Return a copy of the properties table.

Returns: a hashtable containing all properties (including user properties).

getProperty

public String getProperty(String propertyName)
Return the value of a property, if it is set.

Parameters: propertyName The name of the property. May be null, in which case the return value is also null.

Returns: the property value, or null for no match or if a null name is provided.

getReference

public Object getReference(String key)
Look up a reference by its key (ID).

Parameters: key The key for the desired reference. Must not be null.

Returns: the reference with the specified ID, or null if there is no such reference in the project.

getReferences

public Hashtable getReferences()
Return a map of the references in the project (String to Object). The returned hashtable is "live" and so must not be modified.

Returns: a map of the references in the project (String to Object).

getResource

public Resource getResource(String name)
Resolve the file relative to the project's basedir and return it as a FileResource.

Parameters: name the name of the file to resolve.

Returns: the file resource.

Since: Ant 1.7

getTargets

public Hashtable getTargets()
Return the hashtable of targets. The returned hashtable is "live" and so should not be modified.

Returns: a map from name to target (String to Target).

getTaskDefinitions

public Hashtable getTaskDefinitions()
Return the current task definition hashtable. The returned hashtable is "live" and so should not be modified.

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

getThreadTask

public Task getThreadTask(Thread thread)
Get the current task associated with a thread, if any.

Parameters: thread the thread for which the task is required.

Returns: the task which is currently registered for the given thread or null if no task is registered.

getUserProperties

public Hashtable getUserProperties()
Return a copy of the user property hashtable.

Returns: a hashtable containing just the user properties.

getUserProperty

public String getUserProperty(String propertyName)
Return the value of a user property, if it is set.

Parameters: propertyName The name of the property. May be null, in which case the return value is also null.

Returns: the property value, or null for no match or if a null name is provided.

inheritIDReferences

public void inheritIDReferences(Project parent)
Inherit the id references.

Parameters: parent the parent project of this project.

init

public void init()
Initialise the project. This involves setting the default task definitions and loading the system properties.

Throws: BuildException if the default task list cannot be loaded.

initProperties

public void initProperties()
Initializes the properties.

Throws: BuildException if an vital property could not be set.

Since: Ant 1.7

initSubProject

public void initSubProject(Project subProject)
Initialize a subproject.

Parameters: subProject the subproject to initialize.

isKeepGoingMode

public boolean isKeepGoingMode()
Return the keep-going mode. If the keepGoing settor/getter methods are used in conjunction with the ant.executor.class property, they will have no effect.

Returns: "keep-going" mode

Since: Ant 1.6

log

public void log(String message)
Write a message to the log with the default log level of MSG_INFO .

Parameters: message The text to log. Should not be null.

log

public void log(String message, int msgLevel)
Write a project level message to the log with the given log level.

Parameters: message The text to log. Should not be null. msgLevel The log priority level to use.

log

public void log(String message, Throwable throwable, int msgLevel)
Write a project level message to the log with the given log level.

Parameters: message The text to log. Should not be null. throwable The exception causing this log, may be null. msgLevel The log priority level to use.

Since: 1.7

log

public void log(Task task, String message, int msgLevel)
Write a task level message to the log with the given log level.

Parameters: task The task to use in the log. Must not be null. message The text to log. Should not be null. msgLevel The log priority level to use.

log

public void log(Task task, String message, Throwable throwable, int msgLevel)
Write a task level message to the log with the given log level.

Parameters: task The task to use in the log. Must not be null. message The text to log. Should not be null. throwable The exception causing this log, may be null. msgLevel The log priority level to use.

Since: 1.7

log

public void log(Target target, String message, int msgLevel)
Write a target level message to the log with the given log level.

Parameters: target The target to use in the log. Must not be null. message The text to log. Should not be null. msgLevel The log priority level to use.

log

public void log(Target target, String message, Throwable throwable, int msgLevel)
Write a target level message to the log with the given log level.

Parameters: target The target to use in the log. Must not be null. message The text to log. Should not be null. throwable The exception causing this log, may be null. msgLevel The log priority level to use.

Since: 1.7

registerThreadTask

public void registerThreadTask(Thread thread, Task task)
Register a task as the current task for a thread. If the task is null, the thread's entry is removed.

Parameters: thread the thread on which the task is registered. task the task to be registered.

Since: Ant 1.5

removeBuildListener

public void removeBuildListener(BuildListener listener)
Remove a build listener from the list. This listener will no longer be notified of build events for this project.

Parameters: listener The listener to remove from the list. Should not be null.

replaceProperties

public String replaceProperties(String value)
Replace ${} style constructions in the given value with the string value of the corresponding data types.

Parameters: value The string to be scanned for property references. May be null.

Returns: the given string with embedded property names replaced by values, or null if the given string is null.

Throws: BuildException if the given value has an unclosed property name, e.g. ${xxx.

resolveFile

public File resolveFile(String fileName, File rootDir)

Deprecated: since 1.4.x

Return the canonical form of a filename.

If the specified file name is relative it is resolved with respect to the given root directory.

Parameters: fileName The name of the file to resolve. Must not be null. rootDir The directory respective to which relative file names are resolved. May be null, in which case the current directory is used.

Returns: the resolved File.

resolveFile

public File resolveFile(String fileName)
Return the canonical form of a filename.

If the specified file name is relative it is resolved with respect to the project's base directory.

Parameters: fileName The name of the file to resolve. Must not be null.

Returns: the resolved File.

setBasedir

public void setBasedir(String baseD)
Set the base directory for the project, checking that the given filename exists and is a directory.

Parameters: baseD The project base directory. Must not be null.

Throws: BuildException if the directory if invalid.

setBaseDir

public void setBaseDir(File baseDir)
Set the base directory for the project, checking that the given file exists and is a directory.

Parameters: baseDir The project base directory. Must not be null.

Throws: BuildException if the specified file doesn't exist or isn't a directory.

setCoreLoader

public void setCoreLoader(ClassLoader coreLoader)
Set the core classloader for the project. If a null classloader is specified, the parent classloader should be used.

Parameters: coreLoader The classloader to use for the project. May be null.

setDefault

public void setDefault(String defaultTarget)
Set the default target of the project.

Parameters: defaultTarget The name of the default target for this project. May be null, indicating that there is no default target.

setDefaultInputStream

public void setDefaultInputStream(InputStream defaultInputStream)
Set the default System input stream. Normally this stream is set to System.in. This inputStream is used when no task input redirection is being performed.

Parameters: defaultInputStream the default input stream to use when input is requested.

Since: Ant 1.6

setDefaultTarget

public void setDefaultTarget(String defaultTarget)

Deprecated: since 1.5.x. Use setDefault.

Set the default target of the project.

Parameters: defaultTarget The name of the default target for this project. May be null, indicating that there is no default target.

See Also: setDefault

setDescription

public void setDescription(String description)
Set the project description.

Parameters: description The description of the project. May be null.

setExecutor

public void setExecutor(Executor e)
Set the Executor instance for this Project.

Parameters: e the Executor to use.

setFileLastModified

public void setFileLastModified(File file, long time)

Deprecated: since 1.4.x

Call File.setLastModified(long time) on Java above 1.1, and logs a warning on Java 1.1.

Parameters: file The file to set the last modified time on. Must not be null. time the required modification time.

Throws: BuildException if the last modified time cannot be set despite running on a platform with a version above 1.1.

setInheritedProperty

public void setInheritedProperty(String name, String value)
Set a user property, which cannot be overwritten by set/unset property calls. Any previous value is overwritten. Also marks these properties as properties that have not come from the command line.

Parameters: name The name of property to set. Must not be null. value The new value of the property. Must not be null.

See Also: setProperty

setInputHandler

public void setInputHandler(InputHandler handler)
Set the input handler.

Parameters: handler the InputHandler instance to use for gathering input.

setJavaVersionProperty

public void setJavaVersionProperty()
Set the ant.java.version property and tests for unsupported JVM versions. If the version is supported, verbose log messages are generated to record the Java version and operating system name.

Throws: BuildException if this Java version is not supported.

See Also: JavaEnvUtils

setKeepGoingMode

public void setKeepGoingMode(boolean keepGoingMode)
Set "keep-going" mode. In this mode Ant will try to execute as many targets as possible. All targets that do not depend on failed target(s) will be executed. If the keepGoing settor/getter methods are used in conjunction with the ant.executor.class property, they will have no effect.

Parameters: keepGoingMode "keep-going" mode

Since: Ant 1.6

setName

public void setName(String name)
Set the name of the project, also setting the user property ant.project.name.

Parameters: name The name of the project. Must not be null.

setNewProperty

public void setNewProperty(String name, String value)
Set a property if no value currently exists. If the property exists already, a message is logged and the method returns with no other effect.

Parameters: name The name of property to set. Must not be null. value The new value of the property. Must not be null.

Since: 1.5

setProjectReference

public final void setProjectReference(Object obj)
Set a reference to this Project on the parameterized object. Need to set the project before other set/add elements are called.

Parameters: obj the object to invoke setProject(this) on.

setProperty

public void setProperty(String name, String value)
Set a property. Any existing property of the same name is overwritten, unless it is a user property.

Parameters: name The name of property to set. Must not be null. value The new value of the property. Must not be null.

setSystemProperties

public void setSystemProperties()
Add all system properties which aren't already defined as user properties to the project properties.

setUserProperty

public void setUserProperty(String name, String value)
Set a user property, which cannot be overwritten by set/unset property calls. Any previous value is overwritten.

Parameters: name The name of property to set. Must not be null. value The new value of the property. Must not be null.

See Also: setProperty

toBoolean

public static boolean toBoolean(String s)
Return the boolean equivalent of a string, which is considered true if either "on", "true", or "yes" is found, ignoring case.

Parameters: s The string to convert to a boolean value.

Returns: true if the given string is "on", "true" or "yes", or false otherwise.

topoSort

public final Vector topoSort(String root, Hashtable targetTable)
Topologically sort a set of targets. Equivalent to calling topoSort(new String[] {root}, targets, true).

Parameters: root The name of the root target. The sort is created in such a way that the sequence of Targets up to the root target is the minimum possible such sequence. Must not be null. targetTable A Hashtable mapping names to Targets. Must not be null.

Returns: a Vector of ALL Target objects in sorted order.

Throws: BuildException if there is a cyclic dependency among the targets, or if a named target does not exist.

topoSort

public final Vector topoSort(String root, Hashtable targetTable, boolean returnAll)
Topologically sort a set of targets. Equivalent to calling topoSort(new String[] {root}, targets, returnAll).

Parameters: root The name of the root target. The sort is created in such a way that the sequence of Targets up to the root target is the minimum possible such sequence. Must not be null. targetTable A Hashtable mapping names to Targets. Must not be null. returnAll boolean indicating whether to return all targets, or the execution sequence only.

Returns: a Vector of Target objects in sorted order.

Throws: BuildException if there is a cyclic dependency among the targets, or if a named target does not exist.

Since: Ant 1.6.3

topoSort

public final Vector topoSort(String[] root, Hashtable targetTable, boolean returnAll)
Topologically sort a set of targets.

Parameters: root String[] containing the names of the root targets. The sort is created in such a way that the ordered sequence of Targets is the minimum possible such sequence to the specified root targets. Must not be null. targetTable A map of names to targets (String to Target). Must not be null. returnAll boolean indicating whether to return all targets, or the execution sequence only.

Returns: a Vector of Target objects in sorted order.

Throws: BuildException if there is a cyclic dependency among the targets, or if a named target does not exist.

Since: Ant 1.6.3

translatePath

public static String translatePath(String toProcess)

Deprecated: since 1.7 Use FileUtils.translatePath instead.

Translate a path into its native (platform specific) format.

This method uses PathTokenizer to separate the input path into its components. This handles DOS style paths in a relatively sensible way. The file separators are then converted to their platform specific versions.

Parameters: toProcess The path to be translated. May be null.

Returns: the native version of the specified path or an empty string if the path is null or empty.

See Also: PathTokenizer