org.apache.tools.ant.taskdefs

Class Replace

public class Replace extends MatchingTask

Replaces all occurrences of one or more string tokens with given values in the indicated files. Each value can be either a string or the value of a property available in a designated property file. If you want to replace a text that crosses line boundaries, you must use a nested <replacetoken> element.

Since: Ant 1.1

UNKNOWN: category="filesystem"

Nested Class Summary
classReplace.NestedString
an inline string to use as the replacement text
classReplace.Replacefilter
A filter to apply.
Method Summary
Replace.ReplacefiltercreateReplacefilter()
Add a nested <replacefilter> element.
Replace.NestedStringcreateReplaceToken()
the token to filter as the text of a nested element
Replace.NestedStringcreateReplaceValue()
the string to replace the token as the text of a nested element
voidexecute()
Do the execution.
PropertiesgetProperties(File propertyFile)
helper method to load a properties file and throw a build exception if it cannot be loaded
voidsetDir(File dir)
The base directory to use when replacing a token in multiple files; required if file is not defined.
voidsetEncoding(String encoding)
Set the file encoding to use on the files read and written by the task; optional, defaults to default JVM encoding
voidsetFile(File file)
Set the source file; required unless dir is set.
voidsetPropertyFile(File filename)
The name of a property file from which properties specified using nested <replacefilter> elements are drawn; Required only if property attribute of <replacefilter> is used.
voidsetReplaceFilterFile(File filename)
Sets the name of a property file containing filters; optional.
voidsetSummary(boolean summary)
Indicates whether a summary of the replace operation should be produced, detailing how many token occurrences and files were processed; optional, default=false
voidsetToken(String token)
Set the string token to replace; required unless a nested replacetoken element or the replacefilterfile attribute is used.
voidsetValue(String value)
Set the string value to use as token replacement; optional, default is the empty string ""
voidvalidateAttributes()
Validate attributes provided for this task in .xml build file.
voidvalidateReplacefilters()
Validate nested elements.

Method Detail

createReplacefilter

public Replace.Replacefilter createReplacefilter()
Add a nested <replacefilter> element.

Returns: a nested ReplaceFilter object to be configured

createReplaceToken

public Replace.NestedString createReplaceToken()
the token to filter as the text of a nested element

Returns: nested token to configure

createReplaceValue

public Replace.NestedString createReplaceValue()
the string to replace the token as the text of a nested element

Returns: replacement value to configure

execute

public void execute()
Do the execution.

Throws: BuildException if we cant build

getProperties

public Properties getProperties(File propertyFile)
helper method to load a properties file and throw a build exception if it cannot be loaded

Parameters: propertyFile the file to load the properties from

Returns: loaded properties collection

Throws: BuildException if the file could not be found or read

setDir

public void setDir(File dir)
The base directory to use when replacing a token in multiple files; required if file is not defined.

Parameters: dir base dir

setEncoding

public void setEncoding(String encoding)
Set the file encoding to use on the files read and written by the task; optional, defaults to default JVM encoding

Parameters: encoding the encoding to use on the files

setFile

public void setFile(File file)
Set the source file; required unless dir is set.

Parameters: file source file

setPropertyFile

public void setPropertyFile(File filename)
The name of a property file from which properties specified using nested <replacefilter> elements are drawn; Required only if property attribute of <replacefilter> is used.

Parameters: filename file to load

setReplaceFilterFile

public void setReplaceFilterFile(File filename)
Sets the name of a property file containing filters; optional. Each property will be treated as a replacefilter where token is the name of the property and value is the value of the property.

Parameters: filename file to load

setSummary

public void setSummary(boolean summary)
Indicates whether a summary of the replace operation should be produced, detailing how many token occurrences and files were processed; optional, default=false

Parameters: summary true if you would like a summary logged of the replace operation

setToken

public void setToken(String token)
Set the string token to replace; required unless a nested replacetoken element or the replacefilterfile attribute is used.

Parameters: token token string

setValue

public void setValue(String value)
Set the string value to use as token replacement; optional, default is the empty string ""

Parameters: value replacement value

validateAttributes

public void validateAttributes()
Validate attributes provided for this task in .xml build file.

Throws: BuildException if any supplied attribute is invalid or any mandatory attribute is missing

validateReplacefilters

public void validateReplacefilters()
Validate nested elements.

Throws: BuildException if any supplied attribute is invalid or any mandatory attribute is missing

Copyright B) 2000-2007 Apache Software Foundation. All Rights Reserved.