Summary

Add an @implNote to describe the current (and expected) behavior of DigestInputStream on the skip, mark, and reset methods.

Problem

DigestInputStream calculates the message digest on data in an input stream while reading them. It was not clear whether data skipped by the skip method or re-read after a reset are also included in the update.

Solution

Add an @implNote to clarify that only those data actually read are included in the update. This means skipped data are ignored, and re-read data are re-updated.

This is not only the behavior exhibited by the current implementation, but it's also the most intuitive explanation. The current class specification contains sentences like

[calculate the digest] after your calls to one of this digest input stream's {@link #read() read} methods

and

a call to one of the {@code read} methods results in an update on the message digest

which imply the message digest update is highly associated with the "read" methods. The existence of the on(boolean) method demonstrates that the message digest update can be turned on and off freely and the same input stream is allowed to have different digest depending on how it's consumed. The new @implNote further clarifies:

1. what methods are categorized as read methods
2. skip is not a read method
3. every "read" counts even if it's on an already read data

Specification

Add the following @implNote to the class specification of java.security.DigestInputStream:

 * @implNote This implementation only updates the message digest
 *      with data actually read from the input stream when it is
 *      {@linkplain #on(boolean) turned on}. This includes the various
 *      {@code read} methods, {@code transferTo}, {@code readAllBytes},
 *      and {@code readNBytes}. Please note that data bypassed by the
 *      {@code skip} method are ignored. On the other hand,
 *      if the underlying stream supports the {@code mark} and
 *      {@code reset} methods, and the same data is read again after
 *      {@code reset}, then the message digest is updated again.