File.listFiles Gotcha

I had another WTF!? moment trying to get to the bottom of a NullPointerException we've been seeing. It turns out File.listFiles returns null when you're trying to list something that's not actually a directory, or when an I/O error occurs!

/**
 * Returns an array of abstract pathnames denoting the files in the
 * directory denoted by this abstract pathname.

...

 * @return  An array of abstract pathnames denoting the files and
 *          directories in the directory denoted by this abstract pathname.
 *          The array will be empty if the directory is empty.  Returns
 *          {@code null} if this abstract pathname does not denote a
 *          directory, or if an I/O error occurs.
 *
 * @throws  SecurityException
 *          If a security manager exists and its {@link
 *          SecurityManager#checkRead(String)} method denies read access to
 *          the directory
 *
 * @since  1.2
 */
public File[] listFiles() {

Good luck trying to find out which I/O error occurred! I'm guessing just throwing an IOException would have been too easy. Luckily Java 8 provides Files.list as an alternative which does throw an IOException if needed.