## org.apache.tools.ant.taskdefs
Class Copy

    java.lang.Object
      |
      +--org.apache.tools.ant.ProjectComponent
            |
            +--org.apache.tools.ant.Task
                  |
                  +--org.apache.tools.ant.taskdefs.Copy

Direct Known Subclasses:
  Move, Sync.MyCopy

public class Copy
extends Task

Copies a file or directory to a new file or directory. Files are only copied if the source file is newer than the destination file, or when the destination file does not exist. It is possible to explicitly overwrite existing files.

This implementation is based on Arnout Kuiper's initial design document, the following mailing list discussions, and the copyfile/copydir tasks.

Since:
  Ant 1.2
Version:
  $Revision: 1.66.2.5 $

Field Summary
`protected java.util.Hashtable` `completeDirMap`
`protected java.io.File` `destDir`
`protected java.io.File` `destFile`
`protected java.util.Hashtable` `dirCopyMap`
`protected java.io.File` `file`
`protected java.util.Hashtable` `fileCopyMap`
`protected java.util.Vector` `filesets`
`protected boolean` `filtering`
`protected boolean` `flatten`
`protected boolean` `forceOverwrite`
`protected boolean` `includeEmpty`
`protected Mapper` `mapperElement`
`protected boolean` `preserveLastModified`
`protected int` `verbosity`

Fields inherited from class org.apache.tools.ant.Task
`description, location, target, taskName, taskType, wrapper`

Fields inherited from class org.apache.tools.ant.ProjectComponent
`project`

Constructor Summary
`Copy()` Copy task constructor.

Method Summary
`void` `addFileset(FileSet set)` Adds a set of files to copy.
`protected void` `buildMap(java.io.File fromDir, java.io.File toDir, java.lang.String[] names, FileNameMapper mapper, java.util.Hashtable map)` Add to a map of files/directories to copy
`FilterChain` `createFilterChain()` Adds a FilterChain.
`FilterSet` `createFilterSet()` Adds a filterset.
`Mapper` `createMapper()` Defines the mapper to map source to destination files.
`protected void` `doFileOperations()` Actually does the file (and possibly empty directory) copies.
`void` `execute()` Performs the copy operation.
`java.lang.String` `getEncoding()`
`protected FileUtils` `getFileUtils()`
`protected java.util.Vector` `getFilterChains()` Get the filterchains being applied to this operation.
`protected java.util.Vector` `getFilterSets()` Get the filtersets being applied to this operation.
`java.lang.String` `getOutputEncoding()`
`boolean` `getPreserveLastModified()` Whether to give the copied files the same last modified time as the original files.
`boolean` `isEnableMultipleMapping()`
`protected void` `scan(java.io.File fromDir, java.io.File toDir, java.lang.String[] files, java.lang.String[] dirs)` Compares source files to destination files to see if they should be copied.
`void` `setEnableMultipleMappings(boolean enableMultipleMappings)` Attribute to handle mappers that return multiple mappings for a given source path.
`void` `setEncoding(java.lang.String encoding)` Sets the character encoding
`void` `setFailOnError(boolean failonerror)` If false, note errors to the output but keep going.
`void` `setFile(java.io.File file)` Sets a single source file to copy.
`void` `setFiltering(boolean filtering)` If true, enables filtering.
`void` `setFlatten(boolean flatten)` When copying directory trees, the files can be "flattened" into a single directory.
`void` `setGranularity(long granularity)` The number of milliseconds leeway to give before deciding a target is out of date.
`void` `setIncludeEmptyDirs(boolean includeEmpty)` Used to copy empty directories.
`void` `setOutputEncoding(java.lang.String encoding)` Sets the character encoding for output files.
`void` `setOverwrite(boolean overwrite)` Overwrite any existing destination file(s).
`void` `setPreserveLastModified(boolean preserve)` Give the copied files the same last modified time as the original files.
`void` `setPreserveLastModified(java.lang.String preserve)` Deprecated. setPreserveLastModified(String) has been deprecated and replaced with setPreserveLastModified(boolean) to consistently let the Introspection mechanism work.
`void` `setTodir(java.io.File destDir)` Sets the destination directory.
`void` `setTofile(java.io.File destFile)` Sets the destination file.
`void` `setVerbose(boolean verbose)` Used to force listing of all names of copied files.
`protected void` `validateAttributes()` Ensure we have a consistent and legal set of attributes, and set any internal flags necessary based on different combinations of attributes.

Methods inherited from class org.apache.tools.ant.Task
`getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

Methods inherited from class org.apache.tools.ant.ProjectComponent
`getProject, setProject`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### file

    protected java.io.File file

### destFile

    protected java.io.File destFile

### destDir

    protected java.io.File destDir

### filesets

    protected java.util.Vector filesets

### filtering

    protected boolean filtering

### preserveLastModified

    protected boolean preserveLastModified

### forceOverwrite

    protected boolean forceOverwrite

### flatten

    protected boolean flatten

### verbosity

    protected int verbosity

### includeEmpty

    protected boolean includeEmpty

### fileCopyMap

    protected java.util.Hashtable fileCopyMap

### dirCopyMap

    protected java.util.Hashtable dirCopyMap

### completeDirMap

    protected java.util.Hashtable completeDirMap

### mapperElement

    protected Mapper mapperElement

Constructor Detail

### Copy

    public Copy()

  Copy task constructor.

Method Detail

### getFileUtils

    protected FileUtils getFileUtils()

  Returns:
    the fileutils object

### setFile

    public void setFile(java.io.File file)

  Sets a single source file to copy.

  Parameters:
    `file` - the file to copy

### setTofile

    public void setTofile(java.io.File destFile)

  Sets the destination file.

  Parameters:
    `destFile` - the file to copy to

### setTodir

    public void setTodir(java.io.File destDir)

  Sets the destination directory.

  Parameters:
    `destDir` - the destination directory

### createFilterChain

    public FilterChain createFilterChain()

  Adds a FilterChain.

  Returns:
    a filter chain object

### createFilterSet

    public FilterSet createFilterSet()

  Adds a filterset.

  Returns:
    a filter set object

### setPreserveLastModified

    public void setPreserveLastModified(java.lang.String preserve)

  Deprecated. setPreserveLastModified(String) has been deprecated and replaced with setPreserveLastModified(boolean) to consistently let the Introspection mechanism work.

  Give the copied files the same last modified time as the original files.

  Parameters:
    `preserve` - a boolean string

### setPreserveLastModified

    public void setPreserveLastModified(boolean preserve)

  Give the copied files the same last modified time as the original files.

  Parameters:
    `preserve` - if true perverse the modified time, default is false

### getPreserveLastModified

    public boolean getPreserveLastModified()

  Whether to give the copied files the same last modified time as the original files.

  Returns:
    the preserveLastModified attribute
  Since:
    1.32, Ant 1.5

### getFilterSets

    protected java.util.Vector getFilterSets()

  Get the filtersets being applied to this operation.

  Returns:
    a vector of FilterSet objects

### getFilterChains

    protected java.util.Vector getFilterChains()

  Get the filterchains being applied to this operation.

  Returns:
    a vector of FilterChain objects

### setFiltering

    public void setFiltering(boolean filtering)

  If true, enables filtering.

  Parameters:
    `filtering` - if true enable filtering, default is false

### setOverwrite

    public void setOverwrite(boolean overwrite)

  Overwrite any existing destination file(s).

  Parameters:
    `overwrite` - if true force overwriting of destination file(s) even if the destination file(s) are younger than the corresponding source file. Default is false.

### setFlatten

    public void setFlatten(boolean flatten)

  When copying directory trees, the files can be "flattened" into a single directory. If there are multiple files with the same name in the source directory tree, only the first file will be copied into the "flattened" directory, unless the forceoverwrite attribute is true.

  Parameters:
    `flatten` - if true flatten the destination directory. Default is false.

### setVerbose

    public void setVerbose(boolean verbose)

  Used to force listing of all names of copied files.

  Parameters:
    `verbose` - output the names of copied files. Default is false.

### setIncludeEmptyDirs

    public void setIncludeEmptyDirs(boolean includeEmpty)

  Used to copy empty directories.

  Parameters:
    `includeEmpty` - if true copy empty directories. Default is true.

### setEnableMultipleMappings

    public void setEnableMultipleMappings(boolean enableMultipleMappings)

  Attribute to handle mappers that return multiple mappings for a given source path.

  Parameters:
    `enableMultipleMappings` - If true the task will copy to all the mappings for a given source path, if false, only the first file or directory is processed. By default, this setting is false to provide backward compatibility with earlier releases.
  Since:
    1.6

### isEnableMultipleMapping

    public boolean isEnableMultipleMapping()

  Returns:
    the value of the enableMultipleMapping attribute

### setFailOnError

    public void setFailOnError(boolean failonerror)

  If false, note errors to the output but keep going.

  Parameters:
    `failonerror` - true or false

### addFileset

    public void addFileset(FileSet set)

  Adds a set of files to copy.

  Parameters:
    `set` - a set of files to copy

### createMapper

    public Mapper createMapper()
                        throws BuildException

  Defines the mapper to map source to destination files.

  Returns:
    a mapper to be configured
  Throws:
    `BuildException` - if more than one mapper is defined

### setEncoding

    public void setEncoding(java.lang.String encoding)

  Sets the character encoding

  Parameters:
    `encoding` - the character encoding
  Since:
    1.32, Ant 1.5

### getEncoding

    public java.lang.String getEncoding()

  Returns:
    the character encoding, `null` if not set.
  Since:
    1.32, Ant 1.5

### setOutputEncoding

    public void setOutputEncoding(java.lang.String encoding)

  Sets the character encoding for output files.

  Parameters:
    `encoding` - the character encoding
  Since:
    Ant 1.6

### getOutputEncoding

    public java.lang.String getOutputEncoding()

  Returns:
    the character encoding for output files, `null` if not set.
  Since:
    Ant 1.6

### setGranularity

    public void setGranularity(long granularity)

  The number of milliseconds leeway to give before deciding a target is out of date.

  Default is 0 milliseconds, or 2 seconds on DOS systems.

  Since:
    Ant 1.6.2

### execute

    public void execute()
                 throws BuildException

  Performs the copy operation.

  Overrides:
    `execute` in class `Task`
  Throws:
    `BuildException` - if an error occurs

### validateAttributes

    protected void validateAttributes()
                               throws BuildException

  Ensure we have a consistent and legal set of attributes, and set any internal flags necessary based on different combinations of attributes.

  Throws:
    `BuildException` - if an error occurs

### scan

    protected void scan(java.io.File fromDir,
                        java.io.File toDir,
                        java.lang.String[] files,
                        java.lang.String[] dirs)

  Compares source files to destination files to see if they should be copied.

  Parameters:
    `fromDir` - The source directory
    `toDir` - The destination directory
    `files` - A list of files to copy
    `dirs` - A list of directories to copy

### buildMap

    protected void buildMap(java.io.File fromDir,
                            java.io.File toDir,
                            java.lang.String[] names,
                            FileNameMapper mapper,
                            java.util.Hashtable map)

  Add to a map of files/directories to copy

  Parameters:
    `fromDir` - the source directory
    `toDir` - the destination directory
    `names` - a list of filenames
    `mapper` - a `FileNameMapper` value
    `map` - a map of source file to array of destination files

### doFileOperations

    protected void doFileOperations()

  Actually does the file (and possibly empty directory) copies. This is a good method for subclasses to override.

Copyright © 2000-2004 Apache Software Foundation. All Rights Reserved.