How to annotate generated files, primarily in `nio`

We ended up manually preprocessing a template to produce and check in ByteBuffer.java:

• https://github.com/jspecify/jdk/commit/4a7c9ba179b241c6a71c66310454d6a1824c2133
• https://github.com/jspecify/jdk/pull/20

(I wonder if we had to make any accommodation for that in our build process?)

We could do the same for more generated classes, including not just the other *Buffer types but also:

• nio.charset.IllegalCharsetNameException
• nio.charset.UnsupportedCharsetException
• nio.charset.CharsetDecoder
• nio.charset.CharacterCodingException
• nio.ReadOnlyBufferException
• nio.InvalidMarkException
• nio.BufferUnderflowException

If my notes are correct:

• The first two exception types don't throw for a null charsetName but appear to be passed non-null values in practice in the JDK and in the third-party code that I looked non-exhaustively at. I would lean toward non-null for that parameter, but I don't feel strongly.
  • In fairness, I would probably have taken a null argument in some caller with a grain of salt: The parameter is supposed to be a charset name, but that doesn't stop code (Flink, Olingo, Checkstyle, ICU4J) from passing a full message, which would then be returned from getCharsetName() :)
• The other four exception types don't have any nullnes-relevant types at all.
• I didn't look at CharsetDecoder as closely as I would have if I were submitting a PR today, but I suspect that it doesn't need any @Nullable annotations.

Ideally we would probably not check in preprocessed code, instead annotating the templates (X-Buffer.java.template, Charset-X-Coder.java.template, src/java.base/share/classes/java/nio/charset/exceptions(?), ...?). Among other things, that would mean that we have more chance to notice when upstream adds more API to one of those templates! However, that's probably inconvenient for typical users (admittedly including Google... :)), for whom it can be convenient to just pull in some normal .java files. I also haven't tried to figure out whether any of the cases (probably the exception case, if any) require different nullnesses for different files generated from the same template. (Of course, the solution to that would be... more template parameters!)

(I wonder if there's any chance that upstream would change to avoid preprocessing for the simple case of the exception types. *Buffer, though, is much more complex, so I wouldn't anticipate any change there.)

(This is all on my mind again because of https://github.com/google/xplat/commit/7ab1a2c5b64d57086a7d5050de3f517b4ffb8283.)

Start by reviewing the linked ByteBuffer.java commit and pull request, then inspect X-Buffer.java.template, Charset-X-Coder.java.template, and the java.nio.charset exceptions path mentioned in the issue. Compare the listed generated classes and determine whether annotations require template-specific handling or build-process accommodation. Done means an agreed scope and approach for annotating the generated APIs.