1. Overview
In this tutorial, we'll give an overview of the File class, which is part of the java.io API. The File class gives us the ability to work with files and directories on the file system.
2. Creating a File Object
The File class has 4 public constructors. Depending on the developer's needs, different types of instances of the File class can be created.
- File(String pathname) – Creates an instance representing the given pathname
- File(String parent, String child) – Creates an instance that represents the path formed by joining the parent and the child paths
- File(File parent, String child) – Creates an instance with the path formed by joining the parent path represented by another File instance and the child path
- File(URI uri) – Creates an instance that represents the given Uniform Resource Identifier
3. Working with the File Class
The File class has a number of methods that allow us to work with and manipulate files on the file system. We will highlight some of them here. It is important to note that the File class cannot modify or access the contents of the file it represents.
3.1. Creating and Deleting Directories and Files
The File class has instance methods to create and delete directories and files. Directories and files are created using the mkdir and createNewFile methods, respectively.
Directories and files are deleted using the delete method. All these methods return a boolean value that is true when the operation succeeds, and false otherwise:
@Test public void givenDirectoryCreated_whenMkdirIsInvoked_thenDirectoryIsDeleted() { File directory = new File("testDirectory"); if (!directory.isDirectory() || !directory.exists()) { directory.mkdir(); } assertTrue(directory.delete()); } @Test public void givenFileCreated_whenCreateNewFileIsInvoked_thenFileIsDeleted() throws IOException { File file = new File("testFile.txt"); if (!file.isFile() || !file.exists()) { file.createNewFile(); } assertTrue(file.delete()); }
In the above snippet, we also see other helpful methods.
The isDirectory method can be used to test if the file denoted by the provided name is a directory, while the isFile method can be used to test if the file denoted by the provided name is a file. And, we can use the exists method to test whether a directory or file already exists on the system.
3.2. Getting Metadata About File Instances
The File class has a number of methods that return metadata about File instances. Let's see how to use the getName, getParentFile, and getPath methods:
@Test public void givenFileCreated_whenCreateNewFileInvoked_thenMetadataIsAsExpected() throws IOException { String separatorCharacter = System.getProperty("file.separator"); File parentDirectory = makeDirectory("filesDirectory"); File childFile = new File(parentDirectory, "file1.txt"); childFile.createNewFile(); assertTrue(childFile.getName().equals("file1.txt")); assertTrue(childFile.getParentFile().getName().equals(parentDirectory.getName())); assertTrue(childFile.getPath().equals(parentDirectory.getPath() + separatorCharacter + "file1.txt")); removeDirectory(parentDirectory); }
Here, we've illustrated validating the metadata about the file that was created inside the directory. We've also shown how to find the parent of the file and the relative path to that file.
3.3. Setting File and Directory Permissions
The File class has methods that allow you to set permissions on a file or a directory. Here, we'll look at the setWritable and setReadable methods:
@Test(expected = FileNotFoundException.class) public void givenReadOnlyFileCreated_whenCreateNewFileInvoked_thenFileCannotBeWrittenTo() throws IOException { File parentDirectory = makeDirectory("filesDirectory"); File childFile = new File(parentDirectory, "file1.txt"); childFile.createNewFile(); childFile.setWritable(false); FileOutputStream fos = new FileOutputStream(childFile); fos.write("Hello World".getBytes()); // write operation fos.flush(); fos.close(); removeDirectory(parentDirectory); }
In the code above, we attempt to write to a file after we explicitly set permissions on it that blocks any writes. We do this with the setWritable method. Attempting to write to a file when writing to the file is not permitted results in a FileNotFoundException being thrown.
Next, we attempt to read from a file after setting permissions on it that blocks any reads. Reads are blocked using the setReadable method:
@Test(expected = FileNotFoundException.class) public void givenWriteOnlyFileCreated_whenCreateNewFileInvoked_thenFileCannotBeReadFrom() throws IOException { File parentDirectory = makeDirectory("filesDirectory"); File childFile = new File(parentDirectory, "file1.txt"); childFile.createNewFile(); childFile.setReadable(false); FileInputStream fis = new FileInputStream(childFile); fis.read(); // read operation fis.close(); removeDirectory(parentDirectory); }
Again, the JVM will throw a FileNotFoundException for attempts to read a file where reads are not permitted.
3.4. Listing Files Inside a Directory
The File class has methods that allow us to list files contained in a directory. Similarly, directories can also be listed. Here we'll look at the list and list(FilenameFilter) methods:
@Test public void givenFilesCreatedInDirectory_whenCreateNewFileInvoked_thenTheyCanBeListedAsExpected() throws IOException { File directory = makeDirectory("filtersDirectory"); File csvFile = new File(directory, "csvFile.csv"); csvFile.createNewFile(); File txtFile = new File(directory, "txtFile.txt"); txtFile.createNewFile(); // Standard listing assertEquals(2, directory.list().length); // Filtered listing FilenameFilter csvFilter = (dir, ext) -> ext.endsWith(".csv"); assertEquals(1, directory.list(csvFilter).length); removeDirectory(directory); }
We created a directory and added two files to it — one with a csv extension and the other with a txt extension. When listing all files in the directory, we get two files as expected. When we filter the listing by filtering around files with a csv extension, we get only one file returned.
3.5. Renaming Files and Directories
The File class has the functionality of renaming files and directories using the renameTo method:
@Test public void givenDirectoryIsCreated_whenMkdirInvoked_thenDirectoryCanBeRenamed() { File source = makeDirectory("source"); File destination = makeDirectory("destination"); source.renameTo(destination); assertFalse(source.isDirectory()); assertTrue(destination.isDirectory()); removeDirectory(destination); }
In the example above, we create two directories — the source and the destination directories. We then rename the source directory to the destination directory using the renameTo method. The same can be used to rename files instead of directories.
3.6. Getting Disk Space Information
The File class also allows us to get disk space information. Let's see a demonstration of the getFreeSpace method:
@Test public void givenDataIsWrittenToFile_whenWriteIsInvoked_thenFreeSpaceOnSystemDecreases() throws IOException { String name = System.getProperty("user.home") + System.getProperty("file.separator") + "test"; File testDir = makeDirectory(name); File sample = new File(testDir, "sample.txt"); long freeSpaceBeforeWrite = testDir.getFreeSpace(); writeSampleDataToFile(sample); long freeSpaceAfterWrite = testDir.getFreeSpace(); assertTrue(freeSpaceAfterWrite < freeSpaceBeforeWrite); removeDirectory(testDir); }
In this example, we created a directory inside the user's home directory and then created a file in it. We then checked if the free space on the home directory partition had changed after populating this file with some text. Other methods that give information about disk space are getTotalSpace and getUsableSpace.
4. Conclusion
In this tutorial, we've shown some of the functionality the File class provides for working with files and directories on the file system. .
As always, the full source code of the example is available over on Github.