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
class	Replace.NestedString an inline string to use as the replacement text
class	Replace.Replacefilter A filter to apply.

Method Summary
Replace.Replacefilter	createReplacefilter() Add a nested <replacefilter> element.
Replace.NestedString	createReplaceToken() the token to filter as the text of a nested element
Replace.NestedString	createReplaceValue() the string to replace the token as the text of a nested element
void	execute() Do the execution.
Properties	getProperties(File propertyFile) helper method to load a properties file and throw a build exception if it cannot be loaded
void	setDir(File dir) The base directory to use when replacing a token in multiple files; required if `file` is not defined.
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
void	setFile(File file) Set the source file; required unless `dir` is set.
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.
void	setReplaceFilterFile(File filename) Sets the name of a property file containing filters; optional.
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
void	setToken(String token) Set the string token to replace; required unless a nested `replacetoken` element or the `replacefilterfile` attribute is used.
void	setValue(String value) Set the string value to use as token replacement; optional, default is the empty string ""
void	validateAttributes() Validate attributes provided for this task in .xml build file.
void	validateReplacefilters() 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