RFR: 6587699: Document DigestInputStream behavior when skip() or mark() / reset() is used [v2]

Bradford Wetmore wetmore at openjdk.org
Thu Jul 28 17:43:59 UTC 2022


On Thu, 28 Jul 2022 01:23:12 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> src/java.base/share/classes/java/security/DigestInputStream.java line 54:
>> 
>>> 52:  * digest to be computed, leaving the original digest untouched.
>>> 53:  *
>>> 54:  * @implNote This implementation updates and only updates the message digest
>> 
>> The "updates and only updates" feel awkward.  Maybe just the one mention of update?
>
> I'm using the "if and only if" style, which means other non-read methods will not update the message digest.

My feeling still remains.  I don't recall seeing a wording construction like this except for IFF, which is well-understood.  I think it could be said more compactly with:

`This implementation only updates the message digest with data actually read from the input stream when it is on. `

Just my $0.02.

>> src/java.base/share/classes/java/security/DigestInputStream.java line 55:
>> 
>>> 53:  *
>>> 54:  * @implNote This implementation updates and only updates the message digest
>>> 55:  *      with data actually read from the input stream when it is turned on.
>> 
>> "when it is turned on"?  You could probably just end with "actually read from the input stream."
>
> This is about the `on(boolean)` method. I just want to be precise.

Thanks.  It's been a long time since I've looked at DigestInputStream, forgot about the on/off mode.

>> src/java.base/share/classes/java/security/DigestInputStream.java line 57:
>> 
>>> 55:  *      with data actually read from the input stream when it is turned on.
>>> 56:  *      This includes various {@code read} methods, {@code transferTo},
>>> 57:  *      {@code readAllBytes}, and {@code readNBytes}. Specifically, data
>> 
>> Specifically
>> ->
>> Additionally ?
>
> Maybe I should use "especially". This is not "additionally" because `skip` is not one of these "read"-methods.

I meant additionally as in "here's an additional case to be aware of...", not "this is an additional read case..."

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

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



More information about the security-dev mailing list