Make FilenameUtils.equals() not throw an exception

[mernst]

It is surprising that FilenameUtils.equals can throw NullPointerException, because:

• such behavior is outside the ordinary contract of equals(), and
• FilenameUtils.equals throws NullPointerExceptioneven if the client did not pass null as an argument. It throws NullPointerExceptioneven if one of the arguments is not a valid, normalizable filename. However, this behavior is not documented.

This pull request:

• documents the requirement that the arguments must be valid,
• makes the exception message more specific, indicating the filename that was invalid, and
• throws IllegalArgumentException instead of NullPointerException.

[coveralls]

Coverage increased (+0.003%) to 89.494% when pulling f59813b on mernst:filenameutils-equals into cdf7794 on apache:master.

[garydgregory]

I see the current implementation and this PR as incorrect, the method should never throw IMO. The normalization returns null, then the method should return false.

[mernst]

I agree that change is better. I was aiming for minimal changes to the existing specification and tests.
I have now changed the method to return false rather than throwing an exception.

[mernst]

@garydgregory What do you think of the revised pull request that makes equals not throw an exception?