Add suppressed exception details in NativeFSLockFactory lock acquisition failure (#16278)

* Add suppressed exception details in NativeFSLockFactory lock acquisition failure

When lock acquisition fails in NativeFSLockFactory.obtainFSLock, exceptions
thrown while closing the FileChannel are now attached as suppressed exceptions
to the original failure instead of being silently swallowed via
IOUtils.closeWhileHandlingException.

Changes:
- Replace finally block with catch(Throwable) to properly propagate suppressed
  exceptions using IOUtils.closeWhileSuppressingExceptions and addSuppressed
- Add test testSuppressedExceptionOnLockFailure verifying close failures
  appear as suppressed exceptions on the original lock failure
- Add CHANGES.txt entry under Lucene 11.0.0 Bug Fixes

Resolves the TODO comment at NativeFSLockFactory.java line 121.

* Update CHANGES.txt with PR number #16278

* Refactor NativeFSLockFactory lock acquisition to separate concerns

Author: Bharathi-Kanna

lucene/CHANGES.txt

@@ -195,6 +195,8 @@ Bug Fixes
 
 * GITHUB#15939: Fix thread-safety issues with NFARunAutomaton. (Dimitris Rempapis)
 
+* GITHUB#16278: Refactor NativeFSLockFactory lock acquisition to cleanly separate locking and file system logic. (Bharathi-Kanna)
+
 Changes in Runtime Behavior
 ---------------------
 * GITHUB#14187: The query cache is now disabled by default. (Adrien Grand)

lucene/core/src/java/org/apache/lucene/store/NativeFSLockFactory.java

@@ -106,27 +106,44 @@ protected Lock obtainFSLock(FSDirectory dir, String lockName) throws IOException
         Files.readAttributes(realPath, BasicFileAttributes.class).creationTime();
 
     if (LOCK_HELD.add(realPath.toString())) {
-      FileChannel channel = null;
-      FileLock lock = null;
+      NativeFSLock lock = null;
       try {
-        channel = FileChannel.open(realPath, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
-        lock = channel.tryLock();
-        if (lock != null) {
-          return new NativeFSLock(lock, channel, realPath, creationTime);
-        } else {
-          throw new LockObtainFailedException("Lock held by another program: " + realPath);
-        }
+        lock = tryLock(realPath, creationTime);
+        return lock;
       } finally {
-        if (lock == null) { // not successful - clear up and move out
-          IOUtils.closeWhileHandlingException(channel); // TODO: addSuppressed
-          clearLockHeld(realPath); // clear LOCK_HELD last
+        if (lock == null) {
+          clearLockHeld(realPath);
         }
       }
     } else {
       throw new LockObtainFailedException("Lock held by this virtual machine: " + realPath);
     }
   }
 
+  /**
+   * Attempts to obtain the lock without blocking.
+   *
+   * @return a NativeFSLock if successful
+   * @throws IOException if not successful
+   */
+  private static NativeFSLock tryLock(Path path, FileTime creationTime) throws IOException {
+    FileChannel channel = null;
+    FileLock lock = null;
+    try {
+      channel = FileChannel.open(path, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
+      lock = channel.tryLock();
+      if (lock != null) {
+        return new NativeFSLock(lock, channel, path, creationTime);
+      } else {
+        throw new LockObtainFailedException("Lock held by another program: " + path);
+      }
+    } finally {
+      if (lock == null) { // not successful - clear up and move out
+        IOUtils.closeWhileHandlingException(channel); // TODO: addSuppressed
+      }
+    }
+  }
+
   private static void clearLockHeld(Path path) throws IOException {
     boolean remove = LOCK_HELD.remove(path.toString());
     if (remove == false) {