Replace (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs, class: Replace

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:
  `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.
  `Properties`
  `getProperties(File propertyFile)`
  Load a properties file.
  `Properties`
  `getProperties(Resource propertyResource)`
  Load a properties resource.
  `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`
  `setFailOnNoReplacements(boolean b)`
  Whether the build should fail if nothing has been replaced.
  `void`
  `setFile(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(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(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(String token)`
  Set the string token to replace; required unless a nested `replacetoken` element or the `replacefilterresource` 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.

  ### 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 Properties getProperties(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 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(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(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(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(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(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(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(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