RFR: 8344911: Introduce test utility for asserting file open status

[Eirik Bjørsnøs]

Please review this PR which  adds a utility API in the test libraries to assert whether a file is currently open.

Several OpenJDK  tests currently rely on approximations to check this, including deletion (fails only on Windows), or checking `/proc/<pid>/fd` (Works only on Linux). These approximations are blunt instruments, it would be better to have an exact cross platform solution for this need to check if a file is open or closed.

Initial support includes:

* `FileInputStream`, `FileOutputStream` and `RandomAccessFile` from `java.io`
* `FileChannelImpl` from `java.nio`, meaning we can check synchronous NIO APIs such as `Files.newInputStream`, `Files.newOutputStream`, `Files.newByteChannel` and `FileChannel.open`

This allows testing of many (most?) JDK APIs such as `ZipFile`, `JarFile`, `JarURLConnection`, `FileURLConnection` etc.

Tests use the following configuration to enable  instrumentation of file access APIs:


* @library /test/lib
* @run driver jdk.test.lib.util.OpenFilesAgent
* @run junit/othervm -javaagent:OpenFilesAgent.jar OpenFilesTest


Also provided is an assertion API to verify whether files are open or not:


Path file = Files.createFile(Path.of("file.txt"));
assertClosed(file);
try (var is = Files.newInputStream(file)) {
    assertOpen(file);
}
assertClosed(file);
``` 

A failed `assertClosed` shows the stack trace for whatever action opened the file:


Caused by: java.lang.Throwable: Opening stack trace of jdk/build/macosx-x86_64-server-release/JTwork/scratch/file.txt
	at jdk.test.lib.util.OpenFiles.openFile(OpenFiles.java:59)
	at java.base/java.nio.file.Files.newByteChannel(Files.java:357)
	at java.base/java.nio.file.Files.newByteChannel(Files.java:399)
	at java.base/java.nio.file.spi.FileSystemProvider.newInputStream(FileSystemProvider.java:371)
	at java.base/java.nio.file.Files.newInputStream(Files.java:154)
	at OpenFilesTest.sample(OpenFilesTest.java:81)


See the library implementation test `OpenFilesTest` for samples.

Verification:
With `OpenFilesTest` temporarily in tier1, GHA completed successfully across platforms.

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

Commit messages:
 - Revert "Temporarily move OpenFilesTest to tier one to trigger run in GHA"
 - Temporarily move OpenFilesTest to tier one to trigger run in GHA
 - Simplify NIO instrumentation to only instrument FileChannelImpl::open and FileChannelImpl::implCloseChannel
 - Avoid calling OpenFiles.closeFile twice when closing streams created by Files.newOutputStream
 - Add support for Files.newOutputStream
 - Add support for FileOutputStream
 - Fix some Javadocs in OpenFiles
 - Add some missing Javadocs in OpenFiles
 - Add support for Files::newByteChannel
 - Test infrastructure to assert that a file is open or closed

Changes: https://git.openjdk.org/jdk/pull/22343/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=22343&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8344911
  Stats: 898 lines in 3 files changed: 898 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/22343.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/22343/head:pull/22343

PR: https://git.openjdk.org/jdk/pull/22343