[IO-808] Rationalize and unify checking for existence of files and directories

[elharo]

The existing code is a bit of a hodge-podge. This PR moves most current IllegalArgumentExceptions for non-existent files and directories to FileNotFoundExceptions instead. A few turned into UncheckedIOExceptions to maintain API compatibility. The general principle is:

• If a file or directory is not found, throw a FileNotFoundException (or UncheckedIOException if necessary for backwards compatibility)
• if a file is found where a directory is expected or vice versa, throw an IllegalArgumentException

IllegalArgumentExceptions are still thrown in the case where a file object exists but is a file instead of the expected directory or a directory instead of the expected file. I've come to understand that this is wrong too, but this is existing behavior that can be improved in a subsequent PR.

In addition to correctly reporting missing files, this PR removes a number of duplicate checks and methods, and tries to clarify the names of private methods, e.g. by distinguishing whether we're checking for a file, directory, or file object.

Some further changes that should happen here would break the API and require a major version update.

@garydgregory

[garydgregory]

@elharo
Please run 'mvn' locally before you push to avoid all these failures.

[garydgregory]

Hi @elharo

PR merged, TY. I think we might now hear complaints that not all IO exceptions are documented. For example: FileUtils.checksum(File, Checksum) does document IOException but not FileNotFoundException. Shouldn't all (checked) exceptions be documented? I might have mistakenly assumed this was a goal for this PR.

[elharo]

It doesn't hurt to add more detailed exception documentation. If there are any public methods where FileNotFoundException is thrown and neither FileNotFoundException nor IOException is documented, then that should be fixed. FileNotFoundException is a subclass of IOException so it's not absolutely necessary to document it separately though it can be.