RFR: 8286735: (fc) FileChannel#map should document behavior when using custom file systems

[Uwe Schindler]

On Tue, 17 May 2022 01:12:55 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

> Clarify when the `map()` methods of `java.nio.channels.FileChannel` throw an `UnsupportedOperationException`.

Hi,
sorry if this issue may have caused more friction than intended originally.

Actually this is indeed two issues intermixed, that's my fault. The basic issue after merging Panama into main branch is the following and that was what I stumbled on from the beginning: Filesystems developed for JDK 8 to JDK 18 may return their own implementation of FileChannel. We do this in Lucene during our testing to catch bugs - thats all fine! We subclass FileChannel and implement the abstract methods, often just delegating (e.g. we emulate some windows behaviour in our testing on top of Linux - think of - just as example - differences regarding the issue that you cannot delete files while still open or similar). For that we just create a custom Filesystem that wraps all native FileChannel (and other APIs) to add some "bad behaviour" (like we all know form windows).

Thats all fine and works great - util the new method added in JDK 19 (although it is `@Preview` feature - I know about that): If you create a wrapper filesystem  and just wrap, the whole thing breaks with JDK 19. You won't of course not implement the new method added for Panama. When you the have code calling the new code to get a mmapped `MemorySegment` from a `FileChannel`, it thows `UnsupportedOperationException` (because the code was compiled for JDK 17 where the new method doid not exist). Of course that's expected with JDK 19, but it is not documented like that! That was the issue we have seen. Very simple.

This was the reason why I opened the issue: In JDK 19, if you create your own FileSystem hat returns a FileChannel for a file and that FileChannel does not know that there's a new method in JDK 19. The Javadocs are just wrong in that case stating "If an unsupported map mode is specified."

If you want to split the issue and just fix the issue for the new metod added in JDK 19: Let's just do it. The current Javadocs are wrong, because the default implementation also thorws UOE (because mmapping a file as MemorySegment) is not supported by a FileChannel by default (unless supported).

Because I  know that often custom Filesystems do not support mameory mapping I was suggesting to add that javadoc also to the legacy `MappedByteBuffer` code. If that's not wanted remove that. It was just a good meants suggestion to change the spec if you already do it for 19. That's all.

Does this sound OK to you?

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

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