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