[cleanup][client] PIP-478: say what the self-suppression guard actually is

The comment justified the identity guard in closeQuietly as "Identity-guarded, as try-with-resources
generates". It is not. The JLS 14.20.3.1 translation calls addSuppressed unguarded, javac's lowering
emits no identity test, and a self-suppressing resource in a try-with-resources block propagates the
same IllegalArgumentException this guard exists to prevent — confirmed by running one (it prints
"PROPAGATED: java.lang.IllegalArgumentException: Self-suppression not permitted") and by javap:

    20: invokevirtual #19   // Method R.close:()V
    26: astore_2
    27: aload_1
    28: aload_2
    29: invokevirtual #22   // Method java/lang/Throwable.addSuppressed

no comparison between the two throwables.

That matters because the comment is load-bearing: it is there to stop someone deleting the guard as
redundant, and it justified it by a precedent that would not have caught the bug. The guard is
STRICTER than try-with-resources, which is both true and the useful thing to say.

Two more corrections in the same comment, from cross-review:

- "The probe path could not do this — it always mints a fresh one" was false. probe()'s own throws
  are all freshly minted, but it calls TlsHandle.dispose() outside any wrapping catch, so an
  unchecked throwable from dispose() propagates by identity and close() could rethrow that same
  instance. The probe path is a second route to self-suppression, not an impossibility.
- The javadoc promised to attach "any close failure". It attaches any DISTINCT one; the identical
  case is precisely what the guard drops.

Also records that addSuppressed validates its argument even when suppression is disabled, so the
guard is needed regardless of how the propagating throwable was constructed.

Comment-only; no behaviour change. The guard itself and
aFactoryThatFailsInitializeAndCloseWithOneExceptionKeepsTheRealFailure are untouched.

Author: lhotari

pulsar-client/src/main/java/org/apache/pulsar/client/impl/tls/ClientTlsFactorySupport.java

@@ -645,8 +645,9 @@ private static void initializeBlocking(PulsarTlsFactory factory, TlsFactoryInitC
     }
 
     /**
-     * Close a factory the framework initialized, or tried to, attaching any close failure to the original
-     * error so the cleanup problem is visible without displacing the reason the build failed.
+     * Close a factory the framework initialized, or tried to, attaching any <em>distinct</em> close failure
+     * to the original error so the cleanup problem is visible without displacing the reason the build failed.
+     * A close failure that is the original error itself is deliberately not attached — see below.
      *
      * @param factory the factory to release — initialized, or left half-built by a failed {@code initialize}
      * @param failure the failure being propagated
@@ -655,13 +656,19 @@ private static void closeQuietly(PulsarTlsFactory factory, Throwable failure) {
         try {
             factory.close();
         } catch (Throwable closeFailure) {
-            // Identity-guarded, as try-with-resources generates: addSuppressed throws
-            // IllegalArgumentException("Self-suppression not permitted") when handed the throwable it is
-            // being attached to, and that would escape this method and replace the very failure it is
-            // supposed to preserve. Reachable since this also cleans up after a failed initialize():
-            // initializeBlocking unwraps the ExecutionException and rethrows the factory's OWN exception
-            // instance, so a factory that fails initialize() and close() with one latched exception hands
-            // the same object back twice. The probe path could not do this — it always mints a fresh one.
+            // Identity-guarded because addSuppressed rejects self-suppression — IllegalArgumentException
+            // ("Self-suppression not permitted"), and it validates the argument even when suppression is
+            // disabled — and that exception would escape this method and replace the very failure it is
+            // supposed to preserve. Deliberately STRICTER than try-with-resources, whose JLS 14.20.3.1
+            // translation calls addSuppressed unguarded (as does javac's lowering of it), so the language
+            // construct propagates that IllegalArgumentException itself. This guard is therefore not
+            // redundant with try-with-resources and must not be deleted as such.
+            //
+            // Reachable because a factory can hand the same throwable back twice: initializeBlocking unwraps
+            // the ExecutionException and rethrows the factory's OWN exception instance, so one latched
+            // failure out of both initialize() and close() is one object. The probe path can reach it too,
+            // but only through TlsHandle.dispose(), whose unchecked throwables propagate unwrapped —
+            // probe()'s own throws are all freshly minted.
             if (closeFailure != failure) {
                 failure.addSuppressed(closeFailure);
             }