* </ul>
 *
 * <p>Because of this situation, any public method accepting an iterable should invoke the {@code
 * iterator} method only once, and should be tested using this class. Exceptions to this rule should
 * be clearly documented.
 *
 * <p>Note that although your APIs should be liberal in what they accept, your methods which
 * <i>return</i> iterables should make every attempt to return ones of the robust variety.
 *

import java.util.Set;
import org.jspecify.annotations.Nullable;

/**
 * A map-like data structure that wraps a backing map and caches values while iterating through
 * {@link #unmodifiableKeySet()}. By design, the cache is cleared when this structure is mutated. If
 * this structure is never mutated, it provides a thread-safe view of the backing map.
 *
 * <p>The {@link MapIteratorCache} assumes ownership of the backing map, and cannot guarantee

        These advantages can take
        [many forms](https://github.com/google/guava/wiki/PhilosophyExplained#utility), but taking
        the time to discuss them in detail will make it much clearer why this feature should be
        added to Guava.


        Please fill out the following fields to give us a better understanding of your proposed
        feature and its potential value for other Guava users.

 * after the garbage collector reclaims the referent. This is a simpler alternative to using a
 * {@link ReferenceQueue}.
 *
 * <p>Unlike a normal phantom reference, this reference will be cleared automatically.
 *
 * @author Bob Lee
 * @since 2.0
 */
@J2ktIncompatible
@GwtIncompatible
public abstract class FinalizablePhantomReference<T> extends PhantomReference<T>
    implements FinalizableReference {

- ✅ File type context in MS Office errors
- ✅ Archive type in archive extractor errors

## Testing Best Practices

1. **Isolation**: Each test is independent and doesn't affect others
2. **Clarity**: Test names clearly describe what is being tested
3. **Coverage**: Both success and failure paths are tested
4. **Edge Cases**: Null, empty, and boundary conditions are covered
5. **Resources**: Test resources are properly managed and cleaned up

    @DisplayName("parseURL: fragment is moved into path and ref cleared")
    void testParseURL_FragmentMovedToPath() throws MalformedURLException {
        // Arrange & Act
        Handler handler = newHandler();
        URL url = new URL(null, "smb://server/share#frag", handler);

        // Assert: ref is moved into path by Handler.parseURL
        assertNull(url.getRef(), "Ref must be cleared by Handler");

        assertArrayEquals(testPassword.toCharArray(), passwordBefore, "Password should match before wipe");

        // Wipe the password
        authenticator.secureWipePassword();

        // Verify password is cleared after wipe
        char[] passwordAfter = (char[]) passwordField.get(authenticator);
        assertNull(passwordAfter, "Password should be null after wipe");
    }

    @Test
    @DisplayName("Test session ID generation")

 * </ul>
 *
 * <p>Because of this situation, any public method accepting an iterable should invoke the {@code
 * iterator} method only once, and should be tested using this class. Exceptions to this rule should
 * be clearly documented.
 *
 * <p>Note that although your APIs should be liberal in what they accept, your methods which
 * <i>return</i> iterables should make every attempt to return ones of the robust variety.
 *

        new TearDown() {

          @Override
          public void tearDown() throws Exception {
            synchronized (result.lock) {
              assertEquals(
                  "The test should have cleared the stack (say, by virtue of running runTearDown)",
                  0,
                  result.stack.size());
            }
          }
        });
    return result;
  }

        assertEquals(SmbComTransaction.TRANSACTION_BUF_SIZE, buffer2.length, "Reused buffer should have correct size");

        // Note: We don't check if content is cleared as that's not a security requirement
        // The important part is that the buffer is valid and has correct size
    }

    /**
     * Test getBuffers method for transaction buffers.
     */
    @Test