RFR: 8348427: DeferredLintHandler API should use JCTree instead of DiagnosticPosition

[Archie Cobbs]

The purpose of `DeferredLintHandler` is to allow `@SuppressWarnings` to be applied to warnings that are generated before `@SuppressWarnings` annotations themselves have been processed. The way this currently works is that warning callbacks are kept in a `HashMap` keyed by the innermost containing module, package, class, method, or variable declarations (in the form of a `JCModuleDecl`, `JCPackageDecl`, `JCClassDecl`, `JCMethodDecl`, or `JCVariableDecl`). Later, when the compiler executes the attribution phase and the lint categories suppressed at each declaration are known, the corresponding warning callbacks are provided with an appropriately configured `Lint` instance and "flushed".

However, the `DeferredLintHandler` API uses `DiagnosticPosition` instead of `JCTree` for registering and flushing deferred warnings. This opens the door for bugs where warnings are registered to an object which is not a declaration, and therefore ignored.

In fact, this occurs once in the code ([here](https://github.com/openjdk/jdk/blob/48ece0721489c1b357aaa81e89fe59f486079d15/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java#L679)) where a `JCExpression` is being passed, although in this case the bug appears to be harmless (because annotation values can't contain any type of declaration).

The API should be tighted up, and furthermore an assertion should be added to verify that the JCTree being passed is actually a declaration supporting `@SuppressWarnings`.

In addition, there is a design flaw in the API: it's not possible to obtain the current immediate mode `Lint` object, so if an immediate mode `Lint` object is pushed/popped more than once, the second `Lint` object will overwrite the first.

To fix this, the API should be adjusted so the stack of current declarations and/or immediate mode `Lint` objects is managed by the `DeferredLintHandler` itself, by providing a `push()` and `pop()` methods in the API.

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

Commit messages:
 - Refactor the DeferredLintHandler API to maintain the "stack" itself.
 - Add Javadoc to document a subtley in the API.
 - Update DeferredLintHandler API to use JCTree instead of DiagnosticPosition.

Changes: https://git.openjdk.org/jdk/pull/23281/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23281&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8348427
  Stats: 212 lines in 9 files changed: 52 ins; 29 del; 131 mod
  Patch: https://git.openjdk.org/jdk/pull/23281.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23281/head:pull/23281

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