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

# Class Chmod

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
org.apache.tools.ant.taskdefs.Chmod

All Implemented Interfaces:
  `Cloneable`

public class Chmod extends ExecuteOn
Chmod equivalent for unix-like environments.

Since:
  Ant 1.1
To do:
  Refactor so it does not extend from ExecuteOn and then turn around and unsupport several attributes.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class ExecuteOn

  `ExecuteOn.FileDirBoth`
  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 inherited from class ExecuteOn

  `destDir, filesets, mapper, mapperElement, srcFilePos, srcIsFirst, targetFilePos, type`
  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
  `Chmod()`
  Chmod task for setting file and directory permissions.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `checkConfiguration()`
  Check the attributes and nested elements.
  `PatternSet.NameEntry`
  `createExclude()`
  Add a name entry on the exclude list.
  `PatternSet.NameEntry`
  `createInclude()`
  Add a name entry on the include list.
  `PatternSet`
  `createPatternSet()`
  Add a set of patterns.
  `void`
  `execute()`
  Carry out the chmoding.
  `protected boolean`
  `isValidOs()`
  Check if the os is valid.
  `void`
  `setAddsourcefile(boolean b)`
  This is not allowed for Chmod.
  `void`
  `setCommand(Commandline cmdl)`
  Set the command.
  `void`
  `setDefaultexcludes(boolean useDefaultExcludes)`
  Sets whether default exclusions should be used or not.
  `void`
  `setDir(File src)`
  The directory which holds the files whose permissions must be changed.
  `void`
  `setExcludes(String excludes)`
  Sets the set of exclude patterns.
  `void`
  `setExecutable(String e)`
  Set the executable.
  `void`
  `setFile(File src)`
  The file or single directory of which the permissions must be changed.
  `void`
  `setIncludes(String includes)`
  Sets the set of include patterns.
  `void`
  `setPerm(String perm)`
  Set the new permissions.
  `void`
  `setProject(Project project)`
  Set the project of this task.
  `void`
  `setSkipEmptyFilesets(boolean skip)`
  This is not allowed for Chmod.

  ### Methods inherited from class ExecuteOn

  `add, add, addDirset, addFilelist, addFileset, createHandler, createMapper, createSrcfile, createTargetfile, getCommandline, getCommandline, getDirs, getFiles, getFilesAndDirs, runExec, runParallel, setDest, setForce, setForwardslash, setIgnoremissing, setMaxParallel, setParallel, setRelative, setType, setupRedirector, setVerbose`
  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 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`
  `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`
  `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, getOs, getOsFamily, getResolveExecutable, logFlush, maybeSetResultPropertyValue, prepareExec, resolveExecutable, runExecute, setAppend, setDiscardError, setDiscardOutput, setError, setErrorProperty, 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.
  `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 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`
  `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`
  `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`
  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

  - ### Chmod

    public Chmod()
    Chmod task for setting file and directory permissions.

- ## Method Details

  - ### setProject

    public void setProject(Project project)
    Set the project of this task. Calls the super class and sets the project on dhe default FileSet.
    Overrides:
      `setProject` in class `ProjectComponent`
    Parameters:
      `project` - the project for this task.
    See Also:
      - `ProjectComponent.setProject(Project)`

  - ### setFile

    public void setFile(File src)
    The file or single directory of which the permissions must be changed.
    Parameters:
      `src` - the source file or directory.

  - ### setDir

    public void setDir(File src)
    The directory which holds the files whose permissions must be changed.
    Overrides:
      `setDir` in class `ExecTask`
    Parameters:
      `src` - the directory.

  - ### setPerm

    public void setPerm(String perm)
    Set the new permissions.
    Parameters:
      `perm` - the new permissions.

  - ### createInclude

    public PatternSet.NameEntry createInclude()
    Add a name entry on the include list.
    Returns:
      a NameEntry to be configured.

  - ### createExclude

    public PatternSet.NameEntry createExclude()
    Add a name entry on the exclude list.
    Returns:
      a nameentry to be configured.

  - ### createPatternSet

    public PatternSet createPatternSet()
    Add a set of patterns.
    Returns:
      a patternset to be configured.

  - ### setIncludes

    public void setIncludes(String includes)
    Sets the set of include patterns. Patterns may be separated by a comma or a space.
    Parameters:
      `includes` - the string containing the include patterns.

  - ### setExcludes

    public void setExcludes(String excludes)
    Sets the set of exclude patterns. Patterns may be separated by a comma or a space.
    Parameters:
      `excludes` - the string containing the exclude patterns.

  - ### setDefaultexcludes

    public void setDefaultexcludes(boolean useDefaultExcludes)
    Sets whether default exclusions should be used or not.
    Parameters:
      `useDefaultExcludes` - "true"|"on"|"yes" when default exclusions should be used, "false"|"off"|"no" when they shouldn't be used.

  - ### checkConfiguration

    protected void checkConfiguration()
    Check the attributes and nested elements.
    Overrides:
      `checkConfiguration` in class `ExecuteOn`

  - ### execute

    public void execute() throws BuildException
    Carry out the chmoding.
    Overrides:
      `execute` in class `ExecTask`
    Throws:
      `BuildException` - on error.

  - ### setExecutable

    public void setExecutable(String e)
    Set the executable. This is not allowed for Chmod.
    Overrides:
      `setExecutable` in class `ExecTask`
    Parameters:
      `e` - ignored.
    Throws:
      `BuildException` - always.

  - ### setCommand

    public void setCommand(Commandline cmdl)
    Set the command. This is not allowed for Chmod.
    Overrides:
      `setCommand` in class `ExecTask`
    Parameters:
      `cmdl` - ignored.
    Throws:
      `BuildException` - always.

  - ### setSkipEmptyFilesets

    public void setSkipEmptyFilesets(boolean skip)
    This is not allowed for Chmod.
    Overrides:
      `setSkipEmptyFilesets` in class `ExecuteOn`
    Parameters:
      `skip` - ignored.
    Throws:
      `BuildException` - always.

  - ### setAddsourcefile

    public void setAddsourcefile(boolean b)
    This is not allowed for Chmod.
    Overrides:
      `setAddsourcefile` in class `ExecuteOn`
    Parameters:
      `b` - ignored.
    Throws:
      `BuildException` - always.

  - ### isValidOs

    protected boolean isValidOs()
    Check if the os is valid. Always include unix.
    Overrides:
      `isValidOs` in class `ExecTask`
    Returns:
      true if the os is valid.