Copy Options

The enum types LinkOption (Table 21.6) and StandardCopyOption (Table 21.8) implement the CopyOption interface. These options can be used to configure copying and moving of directory entries. A variable arity parameter of type CopyOption… is declared by the copy() and move() methods of the Files class that support specific constants of the LinkOption and StandardCopyOption enum types.

Table 21.8 Standard Copy Options

Enum java.nio.file.StandardCopyOption implements the java.nio.file.CopyOption interface	Description
REPLACE_EXISTING	Replace a file if it exists.
COPY_ATTRIBUTES	Copy file attributes to the new file (p. 1321).
ATOMIC_MOVE	Move the file as an atomic file system operation—that is, an operation that is either performed uninterrupted in its entirety, or it fails.

Copying Directory Entries

The overloaded copy() methods of the Files class implement copying contents of files. Two of the copy() methods can be configured by specifying copy options.

Click here to view code image

static Path copy(Path source, Path destination, CopyOption… options)
                throws IOException

Copies a source directory entry to the destination directory entry. It returns the path to the destination directory entry. The default behavior is outlined below, but can be configured by copy options:

• If destination already exists or is a symbolic link, copying fails.
• • If source and destination are the same, the method completes without any copying.
• If source is a symbolic link, the target of the link is copied.
• If source is a directory, just an empty destination directory is created.

The following copy options can be specified to configure the default copying behavior:

• StandardCopyOption.REPLACE_EXISTING: If the destination exists, this option indicates to replace the destination if it is a file or an empty directory. If the destination exists and is a symbolic link, it indicates to replace the symbolic link and not its target.
• StandardCopyOption.COPY_ATTRIBUTES: This option indicates to copy the file attributes of the source to the destination. However, copying of attributes is platform dependent.
• LinkOption.NOFOLLOW_LINKS: This option indicates not to follow symbolic links. If the source is a symbolic link, then the symbolic link is copied and not its target.

Click here to view code image

static long copy(InputStream in, Path destination, CopyOption… options)
                throws IOException

Copies all bytes from an input stream to a destination path, and returns the number of bytes copied. The input stream will be at the end of the stream after copying, but may not be because of I/O errors.

By default, if the destination path already exists or is a symbolic link, copying fails.

It can be configured by the following copy option:

• StandardCopyOption.REPLACE_EXISTING: If the destination path exists and is a file or an empty directory, this option indicates to replace the destination. If the destination exists and is a symbolic link, this option indicates to replace the symbolic link and not its target.

Click here to view code image

static long copy(Path source, OutputStream output) throws IOException

Copies all bytes from the source to the output stream, and returns the number of bytes copied. It may be necessary to flush the output stream.

Note that this copy() method cannot be configured.

The output stream may be in an inconsistent state because of I/O errors.

The first thing to keep in mind is that the copy methods do not create the intermediate directories that are in the destination path. Given the destination path ./project/archive/destFile, the parent path ./project/archive must exist. Otherwise, a NoSuchFileException is thrown.

Note also that copying fails if the destination path already exists—a FileAlreadyExistsException is thrown, unless the method is qualified by the enum constant StandardCopyOption.REPLACE_EXISTING.