org.apache.tools.ant.taskdefs

Class Copy

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

UNKNOWN: category="filesystem"

Field Summary
protected HashtablecompleteDirMap
protected FiledestDir
protected FiledestFile
protected HashtabledirCopyMap
protected booleanfailonerror
protected Filefile
protected HashtablefileCopyMap
protected Vectorfilesets
protected FileUtilsfileUtils
protected booleanfiltering
protected booleanflatten
protected booleanforceOverwrite
protected booleanincludeEmpty
protected MappermapperElement
protected booleanpreserveLastModified
protected intverbosity
Constructor Summary
Copy()
Copy task constructor.
Method Summary
voidadd(FileNameMapper fileNameMapper)
A nested filenamemapper
voidaddFileset(FileSet set)
Adds a set of files to copy.
protected voidbuildMap(File fromDir, File toDir, String[] names, FileNameMapper mapper, Hashtable map)
Add to a map of files/directories to copy
FilterChaincreateFilterChain()
Adds a FilterChain.
FilterSetcreateFilterSet()
Adds a filterset.
MappercreateMapper()
Defines the mapper to map source to destination files.
protected voiddoFileOperations()
Actually does the file (and possibly empty directory) copies.
voidexecute()
Performs the copy operation.
StringgetEncoding()
protected FileUtilsgetFileUtils()
protected VectorgetFilterChains()
Get the filterchains being applied to this operation.
protected VectorgetFilterSets()
Get the filtersets being applied to this operation.
StringgetOutputEncoding()
booleangetPreserveLastModified()
Whether to give the copied files the same last modified time as the original files.
booleanisEnableMultipleMapping()
protected voidscan(File fromDir, File toDir, String[] files, String[] dirs)
Compares source files to destination files to see if they should be copied.
voidsetEnableMultipleMappings(boolean enableMultipleMappings)
Attribute to handle mappers that return multiple mappings for a given source path.
voidsetEncoding(String encoding)
Sets the character encoding
voidsetFailOnError(boolean failonerror)
If false, note errors to the output but keep going.
voidsetFile(File file)
Sets a single source file to copy.
voidsetFiltering(boolean filtering)
If true, enables filtering.
voidsetFlatten(boolean flatten)
When copying directory trees, the files can be "flattened" into a single directory.
voidsetGranularity(long granularity)
The number of milliseconds leeway to give before deciding a target is out of date.
voidsetIncludeEmptyDirs(boolean includeEmpty)
Used to copy empty directories.
voidsetOutputEncoding(String encoding)
Sets the character encoding for output files.
voidsetOverwrite(boolean overwrite)
Overwrite any existing destination file(s).
voidsetPreserveLastModified(String preserve)
Give the copied files the same last modified time as the original files.
voidsetPreserveLastModified(boolean preserve)
Give the copied files the same last modified time as the original files.
voidsetTodir(File destDir)
Sets the destination directory.
voidsetTofile(File destFile)
Sets the destination file.
voidsetVerbose(boolean verbose)
Used to force listing of all names of copied files.
protected voidvalidateAttributes()
Ensure we have a consistent and legal set of attributes, and set any internal flags necessary based on different combinations of attributes.

Field Detail

completeDirMap

protected Hashtable completeDirMap

destDir

protected File destDir

destFile

protected File destFile

dirCopyMap

protected Hashtable dirCopyMap

failonerror

protected boolean failonerror

file

protected File file

fileCopyMap

protected Hashtable fileCopyMap

filesets

protected Vector filesets

fileUtils

protected FileUtils fileUtils

filtering

protected boolean filtering

flatten

protected boolean flatten

forceOverwrite

protected boolean forceOverwrite

includeEmpty

protected boolean includeEmpty

mapperElement

protected Mapper mapperElement

preserveLastModified

protected boolean preserveLastModified

verbosity

protected int verbosity

Constructor Detail

Copy

public Copy()
Copy task constructor.

Method Detail

add

public void add(FileNameMapper fileNameMapper)
A nested filenamemapper

Parameters: fileNameMapper the mapper to add

Since: Ant 1.6.3

addFileset

public void addFileset(FileSet set)
Adds a set of files to copy.

Parameters: set a set of files to copy

buildMap

protected void buildMap(File fromDir, File toDir, String[] names, FileNameMapper mapper, 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

createFilterChain

public FilterChain createFilterChain()
Adds a FilterChain.

Returns: a filter chain object

createFilterSet

public FilterSet createFilterSet()
Adds a filterset.

Returns: a filter set object

createMapper

public Mapper createMapper()
Defines the mapper to map source to destination files.

Returns: a mapper to be configured

Throws: BuildException if more than one mapper is defined

doFileOperations

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

execute

public void execute()
Performs the copy operation.

Throws: BuildException if an error occurs

getEncoding

public String getEncoding()

Returns: the character encoding, null if not set.

Since: 1.32, Ant 1.5

getFileUtils

protected FileUtils getFileUtils()

Returns: the fileutils object

getFilterChains

protected Vector getFilterChains()
Get the filterchains being applied to this operation.

Returns: a vector of FilterChain objects

getFilterSets

protected Vector getFilterSets()
Get the filtersets being applied to this operation.

Returns: a vector of FilterSet objects

getOutputEncoding

public String getOutputEncoding()

Returns: the character encoding for output files, null if not set.

Since: Ant 1.6

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

isEnableMultipleMapping

public boolean isEnableMultipleMapping()

Returns: the value of the enableMultipleMapping attribute

scan

protected void scan(File fromDir, File toDir, String[] files, 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

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

setEncoding

public void setEncoding(String encoding)
Sets the character encoding

Parameters: encoding the character encoding

Since: 1.32, Ant 1.5

setFailOnError

public void setFailOnError(boolean failonerror)
If false, note errors to the output but keep going.

Parameters: failonerror true or false

setFile

public void setFile(File file)
Sets a single source file to copy.

Parameters: file the file to copy

setFiltering

public void setFiltering(boolean filtering)
If true, enables filtering.

Parameters: filtering if true enable filtering, 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.

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

setIncludeEmptyDirs

public void setIncludeEmptyDirs(boolean includeEmpty)
Used to copy empty directories.

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

setOutputEncoding

public void setOutputEncoding(String encoding)
Sets the character encoding for output files.

Parameters: encoding the character encoding

Since: Ant 1.6

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.

setPreserveLastModified

public void setPreserveLastModified(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

setTodir

public void setTodir(File destDir)
Sets the destination directory.

Parameters: destDir the destination directory

setTofile

public void setTofile(File destFile)
Sets the destination file.

Parameters: destFile the file to copy to

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.

validateAttributes

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.

Throws: BuildException if an error occurs

Copyright B) 2000-2007 Apache Software Foundation. All Rights Reserved.