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

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

  `fileset`
  Modifier and Type
  Field
  Description
  `protected FileSet`
  `fileset`

  ### Fields inherited from class Task

  `target, taskName, taskType, wrapper`
  Modifier and Type
  Field
  Description
  `protected Target`
  `target`
  Deprecated.
  since 1.6.x.
  `protected String`
  `taskName`
  Deprecated.
  since 1.6.x.
  `protected String`
  `taskType`
  Deprecated.
  since 1.6.x.
  `protected RuntimeConfigurable`
  `wrapper`
  Deprecated.
  since 1.6.x.

  ### Fields inherited from class ProjectComponent

  `description, location, project`
  Modifier and Type
  Field
  Description
  `protected String`
  `description`
  Deprecated.
  since 1.6.x.
  `protected Location`
  `location`
  Deprecated.
  since 1.6.x.
  `protected Project`
  `project`
  Deprecated.
  since 1.6.x.

- ## 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 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`
  Modifier and Type
  Method
  Description
  `void`
  `add(FileSelector selector)`
  add an arbitrary selector
  `void`
  `addAnd(AndSelector selector)`
  add an "And" selector entry on the selector list
  `void`
  `addContains(ContainsSelector selector)`
  add a contains selector entry on the selector list
  `void`
  `addContainsRegexp(ContainsRegexpSelector selector)`
  add a regular expression selector entry on the selector list
  `void`
  `addCustom(ExtendSelector selector)`
  add an extended selector entry on the selector list
  `void`
  `addDate(DateSelector selector)`
  add a selector date entry on the selector list
  `void`
  `addDepend(DependSelector selector)`
  add a depends selector entry on the selector list
  `void`
  `addDepth(DepthSelector selector)`
  add a depth selector entry on the selector list
  `void`
  `addDifferent(DifferentSelector selector)`
  add a type selector entry on the type list
  `void`
  `addFilename(FilenameSelector selector)`
  add a selector filename entry on the selector list
  `void`
  `addMajority(MajoritySelector selector)`
  add a majority selector entry on the selector list
  `void`
  `addModified(ModifiedSelector selector)`
  add the modified selector
  `void`
  `addNone(NoneSelector selector)`
  add a "None" selector entry on the selector list
  `void`
  `addNot(NotSelector selector)`
  add a "Not" selector entry on the selector list
  `void`
  `addOr(OrSelector selector)`
  add an "Or" selector entry on the selector list
  `void`
  `addPresent(PresentSelector selector)`
  add a present selector entry on the selector list
  `void`
  `addSelector(SelectSelector selector)`
  add a "Select" selector entry on the selector list
  `void`
  `addSize(SizeSelector selector)`
  add a selector size entry on the selector list
  `void`
  `addType(TypeSelector selector)`
  add a type selector entry on the type list
  `void`
  `appendSelector(FileSelector selector)`
  Add a new selector into this container.
  `PatternSet.NameEntry`
  `createExclude()`
  add a name entry on the exclude list
  `PatternSet.NameEntry`
  `createExcludesFile()`
  add a name entry on the include files list
  `PatternSet.NameEntry`
  `createInclude()`
  add a name entry on the include list
  `PatternSet.NameEntry`
  `createIncludesFile()`
  add a name entry on the include files list
  `PatternSet`
  `createPatternSet()`
  add a set of patterns
  `protected DirectoryScanner`
  `getDirectoryScanner(File baseDir)`
  Returns the directory scanner needed to access the files to process.
  `protected final FileSet`
  `getImplicitFileSet()`
  Accessor for the implicit fileset.
  `FileSelector[]`
  `getSelectors(Project p)`
  Returns the set of selectors as an array.
  `boolean`
  `hasSelectors()`
  Indicates whether there are any selectors here.
  `int`
  `selectorCount()`
  Gives the count of the number of selectors in this container
  `Enumeration<FileSelector>`
  `selectorElements()`
  Returns an enumerator for accessing the set of selectors.
  `void`
  `setCaseSensitive(boolean isCaseSensitive)`
  Sets case sensitivity of the file system
  `void`
  `setDefaultexcludes(boolean useDefaultExcludes)`
  Sets whether default exclusions should be used or not.
  `void`
  `setExcludes(String excludes)`
  Sets the set of exclude patterns.
  `void`
  `setExcludesfile(File excludesfile)`
  Sets the name of the file containing the includes patterns.
  `void`
  `setFollowSymlinks(boolean followSymlinks)`
  Sets whether or not symbolic links or Windows junctions should be followed.
  `void`
  `setIncludes(String includes)`
  Sets the set of include patterns.
  `void`
  `setIncludesfile(File includesfile)`
  Sets the name of the file containing the includes patterns.
  `void`
  `setProject(Project project)`
  Sets the project object of this component.
  `void`
  `XsetIgnore(String ignoreString)`
  List of filenames and directory names to not include.
  `void`
  `XsetItems(String itemString)`
  Set this to be the items in the base directory that you want to be included.

  ### Methods inherited from class 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`
  Modifier and Type
  Method
  Description
  `final void`
  `bindToOwner(Task owner)`
  Bind a task to another; use this when configuring a newly created task to do work on behalf of another.
  `Target`
  `getOwningTarget()`
  Returns the container target of this task.
  `RuntimeConfigurable`
  `getRuntimeConfigurableWrapper()`
  Returns the wrapper used for runtime configuration.
  `String`
  `getTaskName()`
  Returns the name to use in logging messages.
  `String`
  `getTaskType()`
  Return the type of task.
  `protected RuntimeConfigurable`
  `getWrapper()`
  Return the runtime configurable structure for this task.
  `protected void`
  `handleErrorFlush(String output)`
  Handles an error line by logging it with the WARN priority.
  `protected void`
  `handleErrorOutput(String output)`
  Handles an error output by logging it with the WARN priority.
  `protected void`
  `handleFlush(String output)`
  Handles output by logging it with the INFO priority.
  `protected int`
  `handleInput(byte[] buffer, int offset, int length)`
  Handle an input request by this task.
  `protected void`
  `handleOutput(String output)`
  Handles output by logging it with the INFO priority.
  `void`
  `init()`
  Called by the project to let the task initialize properly.
  `protected final boolean`
  `isInvalid()`
  Has this task been marked invalid?
  `void`
  `log(String msg)`
  Logs a message with the default (INFO) priority.
  `void`
  `log(String msg, int msgLevel)`
  Logs a message with the given priority.
  `void`
  `log(String msg, Throwable t, int msgLevel)`
  Logs a message with the given priority.
  `void`
  `log(Throwable t, int msgLevel)`
  Logs a message with the given priority.
  `void`
  `maybeConfigure()`
  Configures this task - if it hasn't been done already.
  `final void`
  `perform()`
  Performs this task if it's still valid, or gets a replacement version and performs that otherwise.
  `void`
  `reconfigure()`
  Force the task to be reconfigured from its RuntimeConfigurable.
  `void`
  `setOwningTarget(Target target)`
  Sets the target container of this task.
  `void`
  `setRuntimeConfigurableWrapper(RuntimeConfigurable wrapper)`
  Sets the wrapper to be used for runtime configuration.
  `void`
  `setTaskName(String name)`
  Sets the name to use in logging messages.
  `void`
  `setTaskType(String type)`
  Sets the name with which the task has been invoked.

  ### Methods inherited from class ProjectComponent

  `clone, getDescription, getLocation, getProject, setDescription, setLocation`
  Modifier and Type
  Method
  Description
  `Object`
  `clone()`
  `String`
  `getDescription()`
  Returns the description of the current action.
  `Location`
  `getLocation()`
  Returns the file/location where this task was defined.
  `Project`
  `getProject()`
  Returns the project to which this component belongs.
  `void`
  `setDescription(String desc)`
  Sets a description of the current action.
  `void`
  `setLocation(Location location)`
  Sets the file/location where this task was defined.

  ### Methods inherited from class 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