Package org.apache.tools.ant.taskdefs

# Class Replace

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.MatchingTask
org.apache.tools.ant.taskdefs.Replace

All Implemented Interfaces:
  `java.lang.Cloneable`, `SelectorContainer`

    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

## Nested Class Summary

Nested Classes
Modifier and Type | Class | Description
--- | --- | ---
`class` | `Replace.NestedString` | An inline string to use as the replacement text.
`class` | `Replace.Replacefilter` | A filter to apply.

## Field Summary

### Fields inherited from class org.apache.tools.ant.taskdefs.MatchingTask

`fileset`

### Fields inherited from class org.apache.tools.ant.Task

`target, taskName, taskType, wrapper`

### Fields inherited from class org.apache.tools.ant.ProjectComponent

`description, location, project`

## Constructor Summary

Constructors
Constructor | Description
--- | ---
`Replace()` |

## Method Summary

Modifier and Type | Method | Description
--- | --- | ---
`void` | `addConfigured​(ResourceCollection rc)` | Support arbitrary file system based resource collections.
`Replace.Replacefilter` | `createReplacefilter()` | Add a nested <replacefilter> element.
`Replace.NestedString` | `createReplaceToken()` | Create a token to filter as the text of a nested element.
`Replace.NestedString` | `createReplaceValue()` | Create a string to replace the token as the text of a nested element.
`void` | `execute()` | Do the execution.
`java.util.Properties` | `getProperties​(java.io.File propertyFile)` | Load a properties file.
`java.util.Properties` | `getProperties​(Resource propertyResource)` | Load a properties resource.
`void` | `setDir​(java.io.File dir)` | The base directory to use when replacing a token in multiple files; required if `file` is not defined.
`void` | `setEncoding​(java.lang.String encoding)` | Set the file encoding to use on the files read and written by the task; optional, defaults to default JVM encoding.
`void` | `setFailOnNoReplacements​(boolean b)` | Whether the build should fail if nothing has been replaced.
`void` | `setFile​(java.io.File file)` | Set the source file; required unless `dir` is set.
`void` | `setPreserveLastModified​(boolean b)` | Whether the file timestamp shall be preserved even if the file is modified.
`void` | `setPropertyFile​(java.io.File propertyFile)` | The name of a property file from which properties specified using nested `<replacefilter>` elements are drawn; required only if the property attribute of `<replacefilter>` is used.
`void` | `setPropertyResource​(Resource propertyResource)` | A resource from which properties specified using nested `<replacefilter>` elements are drawn; required only if the property attribute of `<replacefilter>` is used.
`void` | `setReplaceFilterFile​(java.io.File replaceFilterFile)` | Sets the name of a property file containing filters; optional.
`void` | `setReplaceFilterResource​(Resource replaceFilter)` | Sets the name of a resource 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​(java.lang.String token)` | Set the string token to replace; required unless a nested `replacetoken` element or the `replacefilterresource` attribute is used.
`void` | `setValue​(java.lang.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.

### Methods inherited from class org.apache.tools.ant.taskdefs.MatchingTask

`add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, getDirectoryScanner, getImplicitFileSet, getSelectors, hasSelectors, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setProject, XsetIgnore, XsetItems`

### Methods inherited from class org.apache.tools.ant.Task

`bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

### Methods inherited from class org.apache.tools.ant.ProjectComponent

`clone, getDescription, getLocation, getProject, setDescription, setLocation`

### Methods inherited from class java.lang.Object

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

## Constructor Details

### Replace

public Replace()

## Method Details

### execute

public void execute() throws BuildException
Do the execution.

Overrides:
  `execute` in class `Task`
Throws:
  `BuildException` - if we can't build

### validateAttributes

public void validateAttributes() throws BuildException
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() throws BuildException
Validate nested elements.

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

### getProperties

public java.util.Properties getProperties​(java.io.File propertyFile) throws BuildException
Load a properties file.

Parameters:
  `propertyFile` - the file to load the properties from.
Returns:
  loaded `Properties` object.
Throws:
  `BuildException` - if the file could not be found or read.

### getProperties

public java.util.Properties getProperties​(Resource propertyResource) throws BuildException
Load a properties resource.

Parameters:
  `propertyResource` - the resource to load the properties from.
Returns:
  loaded `Properties` object.
Throws:
  `BuildException` - if the resource could not be found or read.
Since:
  Ant 1.8.0

### setFile

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

Parameters:
  `file` - source `File`.

### 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` - `boolean` whether a summary of the replace operation should be logged.

### setReplaceFilterFile

public void setReplaceFilterFile​(java.io.File replaceFilterFile)
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:
  `replaceFilterFile` - `File` to load.

### setReplaceFilterResource

public void setReplaceFilterResource​(Resource replaceFilter)
Sets the name of a resource 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:
  `replaceFilter` - `Resource` to load.
Since:
  Ant 1.8.0

### setDir

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

Parameters:
  `dir` - `File` representing the base directory.

### setToken

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

Parameters:
  `token` - token `String`.

### setValue

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

Parameters:
  `value` - replacement value.

### setEncoding

public void setEncoding​(java.lang.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.

### createReplaceToken

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

Returns:
  nested token `NestedString` to configure.

### createReplaceValue

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

Returns:
  replacement value `NestedString` to configure.

### setPropertyFile

public void setPropertyFile​(java.io.File propertyFile)
The name of a property file from which properties specified using nested `<replacefilter>` elements are drawn; required only if the property attribute of `<replacefilter>` is used.

Parameters:
  `propertyFile` - `File` to load.

### setPropertyResource

public void setPropertyResource​(Resource propertyResource)
A resource from which properties specified using nested `<replacefilter>` elements are drawn; required only if the property attribute of `<replacefilter>` is used.

Parameters:
  `propertyResource` - `Resource` to load.
Since:
  Ant 1.8.0

### createReplacefilter

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

Returns:
  a nested `Replacefilter` object to be configured.

### addConfigured

public void addConfigured​(ResourceCollection rc)
Support arbitrary file system based resource collections.

Parameters:
  `rc` - ResourceCollection
Since:
  Ant 1.8.0

### setPreserveLastModified

public void setPreserveLastModified​(boolean b)
Whether the file timestamp shall be preserved even if the file is modified.

Parameters:
  `b` - boolean
Since:
  Ant 1.8.0

### setFailOnNoReplacements

public void setFailOnNoReplacements​(boolean b)
Whether the build should fail if nothing has been replaced.

Parameters:
  `b` - boolean
Since:
  Ant 1.8.0