FIO02-J. Detect and handle file-related errors

Java's file-manipulation functions often indicate failure with a return value, rather than throwing an exception. The Java Tutorial for Java 7 notes:

Prior to the Java SE 7 release, the java.io.File class was the mechanism used for file I/O, but it had several drawbacks.

Many methods didn't throw exceptions when they failed, so it was impossible to obtain a useful error message. For example, if a file deletion failed, the program would receive a "delete fail" but wouldn't know if it was because the file didn't exist, the user didn't have permissions, or there was some other problem.

Consequently, file operations can silently fail if the methods' return values are ignored. Java programs must check the return values of method that perform file I/O (this is a specific instance of rule EXP00-J. Do not ignore values returned by methods.)

Noncompliant Code Example (delete())

This noncompliant code example attempts to delete a specified file, but gives no indication of its success. The [API 2006] requires File.delete() to only throw a SecurityException if the program is not authorized to delete the file. No other exceptions are thrown; so the deletion can silently fail.

File file = /* initialize */
file.delete();

Compliant Solution

This compliant solution checks the return value of delete().

File file = new File(args[0]);
if (!file.delete()) {
  System.out.println("Deletion failed");
}

Compliant Solution (Java 1.7)

This compliant solution uses the Files.delete() method from Java 1.7 to delete the file.

Path file = new File("file").toPath();
try {
  Files.delete(file);
} catch (IOException x) {
  // handle error
}

The Java™ SE 7 Documentation [[J2SE 2011]] defines Files.delete() to throw the following exceptions:

Risk Assessment

Failure to check the return values of methods that perform file I/O can result in unexpected behavior.

Automated Detection

TODO

Related Guidelines

Bibliography

      12. Input Output (FIO)