Notes on Java File IO (NIO 2) API's Files.copy()

Feb 8, 2013

This blog post is about usage of the Java File IO (NIO 2) API's java.nio.file.Files class's copy static method.

The copy method is overloaded:

Copy a file to a target file.
Copies all bytes from an input stream to a file.
Copies all bytes from a file to an output stream.

1. Copy a File to a Target File

copy(Path source, Path target, CopyOption… options)

Returns: Target file Path.

Parameters: File Path (source and target), and CopyOption.

Copy Options: REPLACE_EXISTING, COPY_ATTRIBUTES and NOFOLLOW_LINKS. The three copy options can be specified together. See details on Copy Options (at the bottom of this blog post).

Throws:

IOException, runtime UnsupportedOperationException and runtime SecurityException.
FileAlreadyExistsException is thrown if the target file or directory exists.
DirectoryNotEmptyException is thrown if the target file is a non-empty directory, when REPLACE_EXISTING option is specified.
UnsupportedOperationException is thrown if a copy option is not supported.

FileAlreadyExistsException and DirectoryNotEmptyException are defined in java.nio.file package and are subclasses of java.io.IOException.

1.1. Description

CopyOption → File type ↓	No option	REPLACE_EXISTING	NOFOLLOW_LINKS
File	Copies a file to target.	Copies a file to target.	Creates a copy of the link (not the link target).
Directory (its entries are not copied)	Creates an empty directory.	Creates an empty directory.	Creates a copy of the link (not the link target).
Symbolic Link	Copies the target of the link.	Copies the target of the link.	–

1.2. Example

FilesCopyExample1.java (for Windows OS):

import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;
import java.io.IOException;

public class FilesCopyExample1 {
    public static void main (String [] args)
            throws IOException {
        Path srcePath = Paths.get("C:\\java nio2\\testfolder\\fileA.txt");		
        Path targetPath = Paths.get("C:\\java nio2\\testfolder\\fileB.txt");
        Files.copy(srcePath, targetPath); // Statement A
    }
}

1.3. Running FilesCopyExample1.java

Scenario 1:

Without any copy options specified at 'Statement A'.
Source file fileA.txt exists and the target file fileB.txt does not exist in the specified path.
On running the code, the target file fileB.txt is created (as a copy of fileA.txt).

Scenario 2:

Without any copy options specified at 'Statement A'.
Source file fileA.txt and the target file fileB.txt exist in the specified path.
On running the code, throws FileAlreadyExistsException.

Scenario 3:

'Statement A' modified to: Files.copy(srcePath, targetPath, StandardCopyOption.REPLACE_EXISTING);
Source file fileA.txt and the target file fileB.txt exist in the specified path.
On running the code, the existing target file fileB.txt is replaced with fileA.txt (and renamed to fileB.txt).

Scenario 4:

'Statement A' modified to: Files.copy(srcePath, targetPath, StandardCopyOption.REPLACE_EXISTING);
Source file fileA.txt exists and the target file fileB.txt does not exist in the specified path.
On running the code, the target file fileB.txt is created (as a copy of fileA.txt).

2. Copies All Bytes from an Input Stream to a File

copy(InputStream in, Path target, CopyOption... options)

Returns: Number of bytes (long) read.

Parameters: InputStream, target file Path, and CopyOption.

Copy Options: REPLACE_EXISTING.

Throws:

IOException, runtime UnsupportedOperationException and runtime SecurityException.
FileAlreadyExistsException is thrown if the target file or directory exists.
DirectoryNotEmptyException is thrown if the target file is a non-empty directory, when REPLACE_EXISTING option is specified.

2.1. Description

CopyOption → File type ↓	No option	REPLACE_EXISTING
File	Copies all bytes from an input stream to a file.	Copies all bytes from an input stream to a file.
Directory (not applicable)	–	–
Symbolic Link (the target of the link is copied)	Copies all bytes (from target of the link) to a file.	Copies all bytes (from target of the link) to a file.

2.2. Example

FilesCopyExample2.java (for Windows OS):

import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;
import java.io.File;
import java.io.InputStream;
import java.io.FileInputStream;
import java.io.IOException;

public class FilesCopyExample2 {
    public static void main (String [] args)
            throws IOException {
        String srceString = "C:\\java nio2\\testfolder\\fileA.pdf";
        Path targetPath = Paths.get("C:\\java nio2\\testfolder\\fileB.pdf";);
        File file = new File(srceString);
        InputStream inStream = new FileInputStream(file);
        Files.copy(inStream, targetPath, StandardCopyOption.REPLACE_EXISTING);	
    }
}

2.3. Running FilesCopyExample2.java

Scenario 1:

Source file fileA.pdf and the target file fileB.pdf exist in the specified path.
On running the code, the existing target file fileB.pdf is replaced with fileA.pdf (and renamed to fileB.pdf).

Scenario 2:

Source file fileA.pdf exists and the target file fileB.pdf does not exist in the specified path.
On running the code, the existing target file fileB.pdf is created (as a copy of fileA.pdf).

3. Copies All Bytes From a File to an Output Stream

copy(Path source, OutputStream os)

Returns: Number of bytes (long) read or written.

Parameters: Source file Path and OutputStream.

Throws: IOException and runtime SecurityException.

4. Copy Options

The copy() and move() methods of the Files class use the java.nio.file.CopyOption interface. CopyOption configures how to copy or move a file. LinkOption and StandardCopyOption enums implement CopyOption.

4.1. StandardCopyOption enum

COPY_ATTRIBUTES
Copy attributes to the new file. Minimally, the last-modified-time attribute is copied to the target file. Used only with the copy(Path source, Path target).

REPLACE_EXISTING
Replace an existing file.

ATOMIC_MOVE
Move the file as an atomic file system operation. Used only with the move() method.

4.2. LinkOption enum

NOFOLLOW_LINKS
Do not follow symbolic links. Used only with the copy(Path source, Path target).

5. References

Java SE 7 API > java.nio.file (NIO 2).

Return to top