RFR: 8353197: Document preconditions for JavaLangAccess methods [v7]

[Alan Bateman]

On Mon, 12 May 2025 19:42:15 GMT, Volkan Yazici <vyazici at openjdk.org> wrote:

>> Document preconditions on certain `JavaLangAccess` methods that use operations either unsafe and/or without range checks.
>
> Volkan Yazici has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains nine additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'upstream/master' into jla
>  - Improve `uncheckedGetBytesNoRepl` docs
>  - Apply suggestions from code review
>    
>    Co-authored-by: Roger Riggs <Roger.Riggs at Oracle.com>
>  - Prefixed `JavaLangAccess::stringConcat1` with `unchecked`
>  - Fix `HexDigits` copyright year
>  - Fix copyright years
>  - Prefix touched methods with `unchecked`
>  - Fix typo in pre-existing JavaDoc
>  - Improve `JavaLangAccess` documentation

src/java.base/share/classes/java/lang/System.java line 2113:

> 2111: 
> 2112:             public int uncheckedCountPositives(byte[] bytes, int offset, int length) {
> 2113:                 return StringCoding.countPositives(bytes, offset, length);

The prefix means the method is uncheckedXXX when outside of java.lang, and XXX when in java.lang. Okay for this PR but I think we should follow-up and rename the methods in java.lang to uncheckedXXX, then introduce checked versions that do the bounds check.  In this case, we could have countPositives exposed via JLA, its implementation would do the bounds check before calling the unchecked version.  It would mean that "far away" callers in DIS, OIS, ZipCoder, ... would have a bounds check but it would make things easier to audit.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24982#discussion_r2087154008