File getUsableSpace() returns a negative number on very large file system

Summary

Make the getTotalSpace, getFreeSpace, and getUsableSpace methods of java.io.File return Long.MAX_VALUE instead of a negative value when the size of the space exceeds the range of a long.

Problem

Currently if the size of the type of space they correspond to exceeds the maximum value of a long, the methods getTotalSpace, getFreeSpace, and getUsableSpace return a negative value. This is not helpful as it is ambiguous as to whether an overflow occurred or there was some other error.

Solution

Make the aforementioned methods return Long.MAX_VALUE if the size of the spaces they correspond to overflows a long.

Specification

The following verbiage will be added to each of the indicated methods of java.io.File. The changes are also detailed in the attached webrev archive.

• getTotalSpace()

If the total number of bytes in the partition is greater than Long.MAX_VALUE, then Long.MAX_VALUE will be returned.

See Also: FileStore.getTotalSpace()

• getFreeSpace()

If the number of unallocated bytes in the partition is greater than Long.MAX_VALUE, then Long.MAX_VALUE will be returned.

See Also: FileStore.getUnallocatedSpace()

• getUsableSpace()

If the number of available bytes in the partition is greater than Long.MAX_VALUE, then Long.MAX_VALUE will be returned.

See Also: FileStore.getUsableSpace()

The description of return is also changed to indicate that a value of zero can signify that the requested size could not be obtained.

• getTotalSpace()

     * @return  The size, in bytes, of the partition or {@code 0L} if this
     *          abstract pathname does not name a partition or if the size
     *          cannot be obtained

• getFreeSpace()

     * @return  The number of unallocated bytes on the partition or {@code 0L}
     *          if the abstract pathname does not name a partition or if this
     *          number cannot be obtained.  This value will be less than or
     *          equal to the total file system size returned by
     *          {@link #getTotalSpace}.

• getUsableSpace()

     * @return  The number of available bytes on the partition or {@code 0L}
     *          if the abstract pathname does not name a partition or if this
     *          number cannot be obtained.  On systems where this information
     *          is not available, this method will be equivalent to a call to
     *          {@link #getFreeSpace}.