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

All Implemented Interfaces:

Cloneable

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

Field Summary

Fields

Modifier and Type	Field and Description
protected Hashtable<File,File>	completeDirMap
protected File	destDir
protected File	destFile
protected Hashtable<String,String[]>	dirCopyMap
protected boolean	failonerror
protected File	file
protected Hashtable<String,String[]>	fileCopyMap
protected Vector<ResourceCollection>	filesets
protected FileUtils	fileUtils
protected boolean	filtering
protected boolean	flatten
protected boolean	forceOverwrite
protected boolean	includeEmpty
protected Mapper	mapperElement
protected boolean	preserveLastModified
protected Vector<ResourceCollection>	rcs
protected int	verbosity

Constructor Summary

Constructors

Constructor and Description
Copy() Copy task constructor.

Method Summary

Modifier and Type	Method and Description
void	add(FileNameMapper fileNameMapper) Add a nested filenamemapper.
void	add(ResourceCollection res) Add a collection of files to copy.
void	addFileset(FileSet set) Add a set of files to copy.
protected void	buildMap(File fromDir, File toDir, String[] names, FileNameMapper mapper, Hashtable<String,String[]> map) Add to a map of files/directories to copy.
protected Map<Resource,String[]>	buildMap(Resource[] fromResources, File toDir, FileNameMapper mapper) Create a map of resources to copy.
FilterChain	createFilterChain() Add a FilterChain.
FilterSet	createFilterSet() Add a filterset.
Mapper	createMapper() Define the mapper to map source to destination files.
protected void	doFileOperations() Actually does the file (and possibly empty directory) copies.
protected void	doResourceOperations(Map<Resource,String[]> map) Actually does the resource copies.
void	execute() Perform the copy operation.
String	getEncoding() Get the character encoding to be used.
protected FileUtils	getFileUtils() Get the FileUtils for this task.
protected Vector<FilterChain>	getFilterChains() Get the filterchains being applied to this operation.
protected Vector<FilterSet>	getFilterSets() Get the filtersets being applied to this operation.
boolean	getForce() Whether read-only destinations will be overwritten.
String	getOutputEncoding() Get the character encoding for output files.
boolean	getPreserveLastModified() Get whether to give the copied files the same last modified time as the original files.
boolean	isEnableMultipleMapping() Get whether multiple mapping is enabled.
protected void	scan(File fromDir, File toDir, String[] files, String[] dirs) Compares source files to destination files to see if they should be copied.
protected Map<Resource,String[]>	scan(Resource[] fromResources, File toDir) Compares source resources to destination files to see if they should be copied.
void	setEnableMultipleMappings(boolean enableMultipleMappings) Set method of handling mappers that return multiple mappings for a given source path.
void	setEncoding(String encoding) Set the character encoding.
void	setFailOnError(boolean failonerror) Set whether to fail when errors are encountered.
void	setFile(File file) Set a single source file to copy.
void	setFiltering(boolean filtering) Set filtering mode.
void	setFlatten(boolean flatten) Set whether files copied from directory trees will be "flattened" into a single directory.
void	setForce(boolean f) Whether read-only destinations will be overwritten.
void	setGranularity(long granularity) Set the number of milliseconds leeway to give before deciding a target is out of date.
void	setIncludeEmptyDirs(boolean includeEmpty) Set whether to copy empty directories.
void	setOutputEncoding(String encoding) Set the character encoding for output files.
void	setOverwrite(boolean overwrite) Set overwrite mode regarding existing destination file(s).
void	setPreserveLastModified(boolean preserve) Give the copied files the same last modified time as the original files.
void	setQuiet(boolean quiet) Set quiet mode.
void	setTodir(File destDir) Set the destination directory.
void	setTofile(File destFile) Set the destination file.
void	setVerbose(boolean verbose) Set verbose mode.
protected boolean	supportsNonFileResources() Whether this task can deal with non-file resources.
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

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

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

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

Methods inherited from class java.lang.Object

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

Field Detail

completeDirMap

protected Hashtable<File,File> completeDirMap

destDir

protected File destDir

destFile

protected File destFile

dirCopyMap

protected Hashtable<String,String[]> dirCopyMap

failonerror

protected boolean failonerror

file

protected File file

fileCopyMap

protected Hashtable<String,String[]> fileCopyMap

filesets

protected Vector<ResourceCollection> 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

rcs

protected Vector<ResourceCollection> rcs

verbosity

protected int verbosity

Constructor Detail

Copy

public Copy()

Copy task constructor.

Method Detail

add

public void add(FileNameMapper fileNameMapper)

Add a nested filenamemapper.

Parameters:

fileNameMapper - the mapper to add.

Since:

Ant 1.6.3

add

public void add(ResourceCollection res)

Add a collection of files to copy.

Parameters:

res - a resource collection to copy.

Since:

Ant 1.7

addFileset

public void addFileset(FileSet set)

Add 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<String,String[]> 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.

buildMap

protected Map<Resource,String[]> buildMap(Resource[] fromResources,
                                          File toDir,
                                          FileNameMapper mapper)

Create a map of resources to copy.

Parameters:

fromResources - The source resources.

toDir - the destination directory.

mapper - a FileNameMapper value.

Returns:

a map of source resource to array of destination files.

Since:

Ant 1.7

createFilterChain

public FilterChain createFilterChain()

Add a FilterChain.

Returns:

a filter chain object.

createFilterSet

public FilterSet createFilterSet()

Add a filterset.

Returns:

a filter set object.

createMapper

public Mapper createMapper()
                    throws BuildException

Define 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.

doResourceOperations

protected void doResourceOperations(Map<Resource,String[]> map)

Actually does the resource copies. This is a good method for subclasses to override.

Parameters:

map - a map of source resource to array of destination files.

Since:

Ant 1.7

execute

public void execute()
             throws BuildException

Perform the copy operation.

Overrides:

execute in class Task

Throws:

BuildException - if an error occurs.

getEncoding

public String getEncoding()

Get the character encoding to be used.

Returns:

the character encoding, null if not set.

Since:

1.32, Ant 1.5

getFileUtils

protected FileUtils getFileUtils()

Get the FileUtils for this task.

Returns:

the fileutils object.

getFilterChains

protected Vector<FilterChain> getFilterChains()

Get the filterchains being applied to this operation.

Returns:

a vector of FilterChain objects.

getFilterSets

protected Vector<FilterSet> getFilterSets()

Get the filtersets being applied to this operation.

Returns:

a vector of FilterSet objects.

getForce

public boolean getForce()

Whether read-only destinations will be overwritten.

Since:

Ant 1.8.2

getOutputEncoding

public String getOutputEncoding()

Get the character encoding for output files.

Returns:

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

Since:

Ant 1.6

getPreserveLastModified

public boolean getPreserveLastModified()

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

Returns:

the whether destination files will inherit the modification times of the corresponding source files.

Since:

1.32, Ant 1.5

isEnableMultipleMapping

public boolean isEnableMultipleMapping()

Get whether multiple mapping is enabled.

Returns:

true if multiple mapping is enabled; false otherwise.

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.

scan

protected Map<Resource,String[]> scan(Resource[] fromResources,
                                      File toDir)

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

Parameters:

fromResources - The source resources.

toDir - The destination directory.

Returns:

a Map with the out-of-date resources as keys and an array of target file names as values.

Since:

Ant 1.7

setEnableMultipleMappings

public void setEnableMultipleMappings(boolean enableMultipleMappings)

Set method of handling 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:

Ant 1.6

setEncoding

public void setEncoding(String encoding)

Set the character encoding.

Parameters:

encoding - the character encoding.

Since:

1.32, Ant 1.5

setFailOnError

public void setFailOnError(boolean failonerror)

Set whether to fail when errors are encountered. If false, note errors to the output but keep going. Default is true.

Parameters:

failonerror - true or false.

setFile

public void setFile(File file)

Set a single source file to copy.

Parameters:

file - the file to copy.

setFiltering

public void setFiltering(boolean filtering)

Set filtering mode.

Parameters:

filtering - if true enable filtering; default is false.

setFlatten

public void setFlatten(boolean flatten)

Set whether files copied from directory trees will 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.

setForce

public void setForce(boolean f)

Whether read-only destinations will be overwritten.

Defaults to false

Since:

Ant 1.8.2

setGranularity

public void setGranularity(long granularity)

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

Default is 1 second, or 2 seconds on DOS systems.

Parameters:

granularity - the granularity used to decide if a target is out of date.

Since:

Ant 1.6.2

setIncludeEmptyDirs

public void setIncludeEmptyDirs(boolean includeEmpty)

Set whether to copy empty directories.

Parameters:

includeEmpty - if true copy empty directories. Default is true.

setOutputEncoding

public void setOutputEncoding(String encoding)

Set the character encoding for output files.

Parameters:

encoding - the output character encoding.

Since:

Ant 1.6

setOverwrite

public void setOverwrite(boolean overwrite)

Set overwrite mode regarding 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(boolean preserve)

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

Parameters:

preserve - if true preserve the modified time; default is false.

setQuiet

public void setQuiet(boolean quiet)

Set quiet mode. Used to hide messages when a file or directory to be copied does not exist.

Parameters:

quiet - whether or not to display error messages when a file or directory does not exist. Default is false.

setTodir

public void setTodir(File destDir)

Set the destination directory.

Parameters:

destDir - the destination directory.

setTofile

public void setTofile(File destFile)

Set the destination file.

Parameters:

destFile - the file to copy to.

setVerbose

public void setVerbose(boolean verbose)

Set verbose mode. Used to force listing of all names of copied files.

Parameters:

verbose - whether to output the names of copied files. Default is false.

supportsNonFileResources

protected boolean supportsNonFileResources()

Whether this task can deal with non-file resources.

<copy> can while <move> can't since we don't know how to remove non-file resources.

This implementation returns true only if this task is <copy>. Any subclass of this class that also wants to support non-file resources needs to override this method. We need to do so for backwards compatibility reasons since we can't expect subclasses to support resources.

Returns:

true if this task supports non file resources.

Since:

Ant 1.7

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.