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

# Class ExecuteOn

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.ExecTask
org.apache.tools.ant.taskdefs.ExecuteOn

All Implemented Interfaces:
  `Cloneable`

Direct Known Subclasses:
  `AbstractAccessTask, Attrib, Chmod, Transform`

public class ExecuteOn extends ExecTask
Executes a given command, supplying a set of files as arguments.

Since:
  Ant 1.2

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ExecuteOn.FileDirBoth`
  Enumerated attribute with the values "file", "dir" and "both" for the type attribute.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected File`
  `destDir`
  `protected Vector<AbstractFileSet>`
  `filesets`
  `protected FileNameMapper`
  `mapper`
  `protected Mapper`
  `mapperElement`
  `protected Commandline.Marker`
  `srcFilePos`
  `protected boolean`
  `srcIsFirst`
  Has <srcfile> been specified before <targetfile>
  `protected Commandline.Marker`
  `targetFilePos`
  `protected String`
  `type`

  ### Fields inherited from class ExecTask

  `cmdl, failOnError, newEnvironment, redirector, redirectorElement`
  Modifier and Type
  Field
  Description
  `protected Commandline`
  `cmdl`
  `protected boolean`
  `failOnError`
  `protected boolean`
  `newEnvironment`
  `protected Redirector`
  `redirector`
  `protected RedirectorElement`
  `redirectorElement`

  ### 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
  `ExecuteOn()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(ResourceCollection rc)`
  Add a collection of resources upon which to operate.
  `void`
  `add(FileNameMapper fileNameMapper)`
  Add a nested FileNameMapper.
  `void`
  `addDirset(DirSet set)`
  Add a set of directories upon which to operate.
  `void`
  `addFilelist(FileList list)`
  Add a list of source files upon which to operate.
  `void`
  `addFileset(FileSet set)`
  Add a set of files upon which to operate.
  `protected void`
  `checkConfiguration()`
  Check the configuration of this ExecuteOn instance.
  `protected ExecuteStreamHandler`
  `createHandler()`
  Create the ExecuteStreamHandler instance that will be used during execution.
  `Mapper`
  `createMapper()`
  Create a nested Mapper element to use for mapping source files to target files.
  `Commandline.Marker`
  `createSrcfile()`
  Create a placeholder indicating where on the command line the name of the source file should be inserted.
  `Commandline.Marker`
  `createTargetfile()`
  Create a placeholder indicating where on the command line the name of the target file should be inserted.
  `protected String[]`
  `getCommandline(String[] srcFiles, File[] baseDirs)`
  Construct the command line for parallel execution.
  `protected String[]`
  `getCommandline(String srcFile, File baseDir)`
  Construct the command line for serial execution.
  `protected String[]`
  `getDirs(File baseDir, DirectoryScanner ds)`
  Return the list of Directories from this DirectoryScanner that should be included on the command line.
  `protected String[]`
  `getFiles(File baseDir, DirectoryScanner ds)`
  Return the list of files from this DirectoryScanner that should be included on the command line.
  `protected String[]`
  `getFilesAndDirs(FileList list)`
  Return the list of files or directories from this FileList that should be included on the command line.
  `protected void`
  `runExec(Execute exe)`
  Run the specified Execute object.
  `protected void`
  `runParallel(Execute exe, Vector<String> fileNames, Vector<File> baseDirs)`
  Run the command in "parallel" mode, making sure that at most maxParallel sourcefiles get passed on the command line.
  `void`
  `setAddsourcefile(boolean b)`
  Set whether to send the source file name on the command line.
  `void`
  `setDest(File destDir)`
  Specify the directory where target files are to be placed.
  `void`
  `setForce(boolean b)`
  Set whether to bypass timestamp comparisons for target files.
  `void`
  `setForwardslash(boolean forwardSlash)`
  Set whether the source and target file names on Windows and OS/2 must use the forward slash as file separator.
  `void`
  `setIgnoremissing(boolean b)`
  Set whether to ignore nonexistent files from filelists.
  `void`
  `setMaxParallel(int max)`
  Limit the command line length by passing at maximum this many sourcefiles at once to the command.
  `void`
  `setParallel(boolean parallel)`
  Set whether to execute in parallel mode.
  `void`
  `setRelative(boolean relative)`
  Set whether the filenames should be passed on the command line as absolute or relative pathnames.
  `void`
  `setSkipEmptyFilesets(boolean skip)`
  Set whether empty filesets will be skipped.
  `void`
  `setType(ExecuteOn.FileDirBoth type)`
  Set whether the command works only on files, directories or both.
  `protected void`
  `setupRedirector()`
  Set up the I/O Redirector.
  `void`
  `setVerbose(boolean b)`
  Set whether to operate in verbose mode.

  ### Methods inherited from class ExecTask

  `addConfiguredRedirector, addEnv, createArg, createWatchdog, execute, getOs, getOsFamily, getResolveExecutable, isValidOs, logFlush, maybeSetResultPropertyValue, prepareExec, resolveExecutable, runExecute, setAppend, setCommand, setDir, setDiscardError, setDiscardOutput, setError, setErrorProperty, setExecutable, setFailIfExecutionFails, setFailonerror, setInput, setInputString, setLogError, setNewenvironment, setOs, setOsFamily, setOutput, setOutputproperty, setResolveExecutable, setResultProperty, setSearchPath, setSpawn, setTimeout, setTimeout, setVMLauncher`
  Modifier and Type
  Method
  Description
  `void`
  `addConfiguredRedirector(RedirectorElement redirectorElement)`
  Add a `RedirectorElement` to this task.
  `void`
  `addEnv(Environment.Variable var)`
  Add an environment variable to the launched process.
  `Commandline.Argument`
  `createArg()`
  Adds a command-line argument.
  `protected ExecuteWatchdog`
  `createWatchdog()`
  Create the Watchdog to kill a runaway process.
  `void`
  `execute()`
  Do the work.
  `final String`
  `getOs()`
  List of operating systems on which the command may be executed.
  `final String`
  `getOsFamily()`
  Restrict this execution to a single OS Family
  `boolean`
  `getResolveExecutable()`
  Indicates whether to attempt to resolve the executable to a file.
  `protected boolean`
  `isValidOs()`
  Is this the OS the user wanted?
  `protected void`
  `logFlush()`
  Flush the output stream - if there is one.
  `protected void`
  `maybeSetResultPropertyValue(int result)`
  Helper method to set result property to the passed in value if appropriate.
  `protected Execute`
  `prepareExec()`
  Create an Execute instance with the correct working directory set.
  `protected String`
  `resolveExecutable(String exec, boolean mustSearchPath)`
  The method attempts to figure out where the executable is so that we can feed the full path.
  `protected final void`
  `runExecute(Execute exe)`
  A Utility method for this classes and subclasses to run an Execute instance (an external command).
  `void`
  `setAppend(boolean append)`
  Set whether output should be appended to or overwrite an existing file.
  `void`
  `setCommand(Commandline cmdl)`
  Sets a command line.
  `void`
  `setDir(File d)`
  Set the working directory of the process.
  `void`
  `setDiscardError(boolean discard)`
  Whether error output should be discarded.
  `void`
  `setDiscardOutput(boolean discard)`
  Whether output should be discarded.
  `void`
  `setError(File error)`
  Set the File to which the error stream of the process should be redirected.
  `void`
  `setErrorProperty(String errorProperty)`
  Sets the name of the property whose value should be set to the error of the process.
  `void`
  `setExecutable(String value)`
  Set the name of the executable program.
  `void`
  `setFailIfExecutionFails(boolean flag)`
  Set whether to stop the build if program cannot be started.
  `void`
  `setFailonerror(boolean fail)`
  Fail if the command exits with a non-zero return code.
  `void`
  `setInput(File input)`
  Set the input file to use for the task.
  `void`
  `setInputString(String inputString)`
  Set the string to use as input.
  `void`
  `setLogError(boolean logError)`
  Controls whether error output of exec is logged.
  `void`
  `setNewenvironment(boolean newenv)`
  Do not propagate old environment when new environment variables are specified.
  `void`
  `setOs(String os)`
  List of operating systems on which the command may be executed.
  `void`
  `setOsFamily(String osFamily)`
  Restrict this execution to a single OS Family
  `void`
  `setOutput(File out)`
  File the output of the process is redirected to.
  `void`
  `setOutputproperty(String outputProp)`
  Sets the property name whose value should be set to the output of the process.
  `void`
  `setResolveExecutable(boolean resolveExecutable)`
  Set whether to attempt to resolve the executable to a file.
  `void`
  `setResultProperty(String resultProperty)`
  Sets the name of a property in which the return code of the command should be stored.
  `void`
  `setSearchPath(boolean searchPath)`
  Set whether to search nested, then system PATH environment variables for the executable.
  `void`
  `setSpawn(boolean spawn)`
  Set whether or not you want the process to be spawned.
  `void`
  `setTimeout(Integer value)`
  Set the timeout in milliseconds after which the process will be killed.
  `void`
  `setTimeout(Long value)`
  Set the timeout in milliseconds after which the process will be killed.
  `void`
  `setVMLauncher(boolean vmLauncher)`
  Set whether to launch new process with VM, otherwise use the OS's shell.

  ### 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, setProject`
  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.
  `void`
  `setProject(Project project)`
  Sets the project object of this component.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### filesets

    protected Vector<AbstractFileSet> filesets

  - ### type

    protected String type

  - ### srcFilePos

    protected Commandline.Marker srcFilePos

  - ### targetFilePos

    protected Commandline.Marker targetFilePos

  - ### mapperElement

    protected Mapper mapperElement

  - ### mapper

    protected FileNameMapper mapper

  - ### destDir

    protected File destDir

  - ### srcIsFirst

    protected boolean srcIsFirst
    Has <srcfile> been specified before <targetfile>

- ## Constructor Details

  - ### ExecuteOn

    public ExecuteOn()

- ## Method Details

  - ### addFileset

    public void addFileset(FileSet set)
    Add a set of files upon which to operate.
    Parameters:
      `set` - the FileSet to add.

  - ### addDirset

    public void addDirset(DirSet set)
    Add a set of directories upon which to operate.
    Parameters:
      `set` - the DirSet to add.
    Since:
      Ant 1.6

  - ### addFilelist

    public void addFilelist(FileList list)
    Add a list of source files upon which to operate.
    Parameters:
      `list` - the FileList to add.

  - ### add

    public void add(ResourceCollection rc)
    Add a collection of resources upon which to operate.
    Parameters:
      `rc` - resource collection to add.
    Since:
      Ant 1.7

  - ### setRelative

    public void setRelative(boolean relative)
    Set whether the filenames should be passed on the command line as absolute or relative pathnames. Paths are relative to the base directory of the corresponding fileset for source files or the dest attribute for target files.
    Parameters:
      `relative` - whether to pass relative pathnames.

  - ### setParallel

    public void setParallel(boolean parallel)
    Set whether to execute in parallel mode. If true, run the command only once, appending all files as arguments. If false, command will be executed once for every file. Defaults to false.
    Parameters:
      `parallel` - whether to run in parallel.

  - ### setType

    public void setType(ExecuteOn.FileDirBoth type)
    Set whether the command works only on files, directories or both.
    Parameters:
      `type` - a FileDirBoth EnumeratedAttribute.

  - ### setSkipEmptyFilesets

    public void setSkipEmptyFilesets(boolean skip)
    Set whether empty filesets will be skipped. If true and no source files have been found or are newer than their corresponding target files, the command will not be run.
    Parameters:
      `skip` - whether to skip empty filesets.

  - ### setDest

    public void setDest(File destDir)
    Specify the directory where target files are to be placed.
    Parameters:
      `destDir` - the File object representing the destination directory.

  - ### setForwardslash

    public void setForwardslash(boolean forwardSlash)
    Set whether the source and target file names on Windows and OS/2 must use the forward slash as file separator.
    Parameters:
      `forwardSlash` - whether the forward slash will be forced.

  - ### setMaxParallel

    public void setMaxParallel(int max)
    Limit the command line length by passing at maximum this many sourcefiles at once to the command.

    Set to <= 0 for unlimited - this is the default.

    Parameters:
      `max` - `int` maximum number of sourcefiles passed to the executable.
    Since:
      Ant 1.6

  - ### setAddsourcefile

    public void setAddsourcefile(boolean b)
    Set whether to send the source file name on the command line.

    Defaults to `true`.

    Parameters:
      `b` - whether to add the source file to the command line.
    Since:
      Ant 1.6

  - ### setVerbose

    public void setVerbose(boolean b)
    Set whether to operate in verbose mode. If true, a verbose summary will be printed after execution.
    Parameters:
      `b` - whether to operate in verbose mode.
    Since:
      Ant 1.6

  - ### setIgnoremissing

    public void setIgnoremissing(boolean b)
    Set whether to ignore nonexistent files from filelists.
    Parameters:
      `b` - whether to ignore missing files.
    Since:
      Ant 1.6.2

  - ### setForce

    public void setForce(boolean b)
    Set whether to bypass timestamp comparisons for target files.
    Parameters:
      `b` - whether to bypass timestamp comparisons.
    Since:
      Ant 1.6.3

  - ### createSrcfile

    public Commandline.Marker createSrcfile()
    Create a placeholder indicating where on the command line the name of the source file should be inserted.
    Returns:
      `Commandline.Marker`.

  - ### createTargetfile

    public Commandline.Marker createTargetfile()
    Create a placeholder indicating where on the command line the name of the target file should be inserted.
    Returns:
      `Commandline.Marker`.

  - ### createMapper

    public Mapper createMapper() throws BuildException
    Create a nested Mapper element to use for mapping source files to target files.
    Returns:
      `Mapper`.
    Throws:
      `BuildException` - if more than one mapper is defined.

  - ### add

    public void add(FileNameMapper fileNameMapper)
    Add a nested FileNameMapper.
    Parameters:
      `fileNameMapper` - the mapper to add.
    Since:
      Ant 1.6.3

  - ### checkConfiguration

    protected void checkConfiguration()
    Check the configuration of this ExecuteOn instance.
    Overrides:
      `checkConfiguration` in class `ExecTask`

  - ### createHandler

    protected ExecuteStreamHandler createHandler() throws BuildException
    Create the ExecuteStreamHandler instance that will be used during execution.
    Overrides:
      `createHandler` in class `ExecTask`
    Returns:
      `ExecuteStreamHandler`.
    Throws:
      `BuildException` - on error.

  - ### setupRedirector

    protected void setupRedirector()
    Set up the I/O Redirector.
    Overrides:
      `setupRedirector` in class `ExecTask`

  - ### runExec

    protected void runExec(Execute exe) throws BuildException
    Run the specified Execute object.
    Overrides:
      `runExec` in class `ExecTask`
    Parameters:
      `exe` - the Execute instance representing the external process.
    Throws:
      `BuildException` - on error

  - ### getCommandline

    protected String[] getCommandline(String[] srcFiles, File[] baseDirs)
    Construct the command line for parallel execution.
    Parameters:
      `srcFiles` - The filenames to add to the commandline.
      `baseDirs` - filenames are relative to this dir.
    Returns:
      the command line in the form of a String[].

  - ### getCommandline

    protected String[] getCommandline(String srcFile, File baseDir)
    Construct the command line for serial execution.
    Parameters:
      `srcFile` - The filename to add to the commandline.
      `baseDir` - filename is relative to this dir.
    Returns:
      the command line in the form of a String[].

  - ### getFiles

    protected String[] getFiles(File baseDir, DirectoryScanner ds)
    Return the list of files from this DirectoryScanner that should be included on the command line.
    Parameters:
      `baseDir` - the File base directory.
      `ds` - the DirectoryScanner to use for file scanning.
    Returns:
      a String[] containing the filenames.

  - ### getDirs

    protected String[] getDirs(File baseDir, DirectoryScanner ds)
    Return the list of Directories from this DirectoryScanner that should be included on the command line.
    Parameters:
      `baseDir` - the File base directory.
      `ds` - the DirectoryScanner to use for file scanning.
    Returns:
      a String[] containing the directory names.

  - ### getFilesAndDirs

    protected String[] getFilesAndDirs(FileList list)
    Return the list of files or directories from this FileList that should be included on the command line.
    Parameters:
      `list` - the FileList to check.
    Returns:
      a String[] containing the directory names.
    Since:
      Ant 1.6.2

  - ### runParallel

    protected void runParallel(Execute exe, Vector<String> fileNames, Vector<File> baseDirs) throws IOException, BuildException
    Run the command in "parallel" mode, making sure that at most maxParallel sourcefiles get passed on the command line.
    Parameters:
      `exe` - the Executable to use.
      `fileNames` - the Vector of filenames.
      `baseDirs` - the Vector of base directories corresponding to fileNames.
    Throws:
      `IOException` - on I/O errors.
      `BuildException` - on other errors.
    Since:
      Ant 1.6