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

[Volkan Yazici]

On Tue, 13 May 2025 15:51:12 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> 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.

[8356380: Check bounds for JavaLangAccess::countPositives](https://bugs.openjdk.org/browse/JDK-8356380) will address this.

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

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