FileChannel doc

[Alan Bateman]

On 01/10/2012 23:27, Jeff Hain wrote:
> Hello.
>
> I was digging through FileChannel(Impl)
> (to do a mock of it, and have my unit tests not
> slowed down by the drive, nor burning it out),
> and found some perfectibilities:
>
> - lock(), tryLock() and tryLock(long,long,boolean) docs
>   should be aligned with lock(long,long,boolean) doc,
>   regarding NonReadableChannelException and
>   NonWritableChannelException:
>      * @throws  NonReadableChannelException
>      *          If <tt>shared</tt> is <tt>true</tt> this channel was not
>      *          opened for reading
>      *
>      * @throws  NonWritableChannelException
>      *          If <tt>shared</tt> is <tt>false</tt> but this channel 
> was not
>      *          opened for writing
Just so I understand, is this what you are saying:

1. Typo in the @throws NonReadableChannelException as "but" is missing.

2. tryLock methods don't specify 
NonReadableChannelException/NonWritableChannelException - yes, this is a 
known issue, see 4510562.

>
> - in all 4 lock/tryLock methods, in the doc for
>   OverlappingFileLockException, "in this method" could be
>   replaced with "in a lock method", since there are multiple
>   blocking lock methods, and tryLock methods are not blocking.
You're right, this could be clearer.

>
> Something else I found perfectible was the order of checks
> (open/writable/etc.), which varies across methods, and some
> "if (position > size) return 0" that could be replaced with
> "if (position >= size) return 0".
> Changing that could break some bad programs, but don't they
> deserve to break? ;)
>
We don't want to deliberately break anyone. Are you concerned with cases 
where more than one exception is possible?

-Alan

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/nio-dev/attachments/20121002/222e4004/attachment.html