Replace (Apache Ant API)
Date: 2018-03-24

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 and 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 and Description
    `Replace()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

    - #### Replace

          public Replace()

  - ### Method Detail

    - #### 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