RFR: 5041655: (ch) FileLock: negative param and overflow issues [v6]

[Brian Burkhalter]

On Thu, 10 Feb 2022 13:41:01 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   5041655: Update spec of zero lock size in channels and remove from FileLock spec
>
> src/java.base/share/classes/java/nio/channels/FileChannel.java line 1005:
> 
>> 1003:      *         A value of zero means to lock all bytes from the specified
>> 1004:      *         starting position to the end of the file, regardless of whether
>> 1005:      *         the file is subsequently extended or truncated
> 
> This looks okay but I think we will need to say something about the return FileLock object. It may be that we need to add text to the method description to say that a FileLock with size "Long.MAX_VALUE - position" is returning when called with a size of 0. What do you think?

I had wondered about adding that:

-     * Long#MAX_VALUE}.
+     * Long#MAX_VALUE}.  If a lock is created with a valid {@code position}
+     * and a {@code size} parameter of zero, then a lock of size
+     * {@code Long.MAX_VALUE - position} is returned.

> src/java.base/share/classes/java/nio/channels/FileLock.java line 269:
> 
>> 267:      * <p> If {@code size} is negative, {@code false} is returned regardless
>> 268:      * of the value of {@code position}.
>> 269:      *
> 
> This is okay but maybe it should move to the "@returns" description. The "@returns" description states the condition when true is returned. We could add "false if size is negative of the lock range does not overlap". Try it and see if it looks a bit better.

I think it does look better:

-     * @return  {@code true} if, and only if, this lock and the given lock
-     *          range overlap by at least one byte
+     * @return  {@code true} if this lock and the given lock range overlap
+     *          by at least one byte; {@code false} if {@code size} is
+     *          negative or the lock range does not overlap this lock

-------------

PR: https://git.openjdk.java.net/jdk/pull/7254