ExecuteOn (Apache Ant API)
Date: 2018-09-11

Package org.apache.tools.ant.taskdefs

## 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:
    `java.lang.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 java.io.File` | `destDir` |
    `protected java.util.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 java.lang.String` | `type` |

    - ### Fields inherited from class org.apache.tools.ant.taskdefs.ExecTask

      `cmdl, failOnError, newEnvironment, redirector, redirectorElement`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ExecuteOn()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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 java.lang.String[]` | `getCommandline​(java.lang.String[] srcFiles, java.io.File[] baseDirs)` | Construct the command line for parallel execution.
    `protected java.lang.String[]` | `getCommandline​(java.lang.String srcFile, java.io.File baseDir)` | Construct the command line for serial execution.
    `protected java.lang.String[]` | `getDirs​(java.io.File baseDir, DirectoryScanner ds)` | Return the list of Directories from this DirectoryScanner that should be included on the command line.
    `protected java.lang.String[]` | `getFiles​(java.io.File baseDir, DirectoryScanner ds)` | Return the list of files from this DirectoryScanner that should be included on the command line.
    `protected java.lang.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, java.util.Vector<java.lang.String> fileNames, java.util.Vector<java.io.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​(java.io.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 org.apache.tools.ant.taskdefs.ExecTask

      `addConfiguredRedirector, addEnv, createArg, createWatchdog, execute, getOs, getOsFamily, getResolveExecutable, isValidOs, logFlush, maybeSetResultPropertyValue, prepareExec, resolveExecutable, runExecute, setAppend, setCommand, setDir, setError, setErrorProperty, setExecutable, setFailIfExecutionFails, setFailonerror, setInput, setInputString, setLogError, setNewenvironment, setOs, setOsFamily, setOutput, setOutputproperty, setResolveExecutable, setResultProperty, setSearchPath, setSpawn, setTimeout, setTimeout, setVMLauncher`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

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

- - ### Field Detail

    - #### filesets

          protected java.util.Vector<AbstractFileSet> filesets

    - #### type

          protected java.lang.String type

    - #### srcFilePos

          protected Commandline.Marker srcFilePos

    - #### targetFilePos

          protected Commandline.Marker targetFilePos

    - #### mapperElement

          protected Mapper mapperElement

    - #### mapper

          protected FileNameMapper mapper

    - #### destDir

          protected java.io.File destDir

    - #### srcIsFirst

          protected boolean srcIsFirst

      Has <srcfile> been specified before <targetfile>

  - ### Constructor Detail

    - #### ExecuteOn

          public ExecuteOn()

  - ### Method Detail

    - #### 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​(java.io.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 java.lang.String[] getCommandline​(java.lang.String[] srcFiles,
                                                      java.io.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 java.lang.String[] getCommandline​(java.lang.String srcFile,
                                                      java.io.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 java.lang.String[] getFiles​(java.io.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 java.lang.String[] getDirs​(java.io.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 java.lang.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,
                                     java.util.Vector<java.lang.String> fileNames,
                                     java.util.Vector<java.io.File> baseDirs)
                              throws java.io.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:
        `java.io.IOException` - on I/O errors.
        `BuildException` - on other errors.
      Since:
        Ant 1.6