Repository: commons-compress Updated Branches: refs/heads/master de2738ae4 -> 75bb48015
document how the class wants to get used Project: http://git-wip-us.apache.org/repos/asf/commons-compress/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-compress/commit/75bb4801 Tree: http://git-wip-us.apache.org/repos/asf/commons-compress/tree/75bb4801 Diff: http://git-wip-us.apache.org/repos/asf/commons-compress/diff/75bb4801 Branch: refs/heads/master Commit: 75bb4801554bdd389d4de811eb9552ef4332fc2d Parents: de2738a Author: Stefan Bodewig <bode...@apache.org> Authored: Tue Feb 7 06:21:41 2017 +0100 Committer: Stefan Bodewig <bode...@apache.org> Committed: Tue Feb 7 06:21:41 2017 +0100 ---------------------------------------------------------------------- .../AbstractLZ77CompressorInputStream.java | 29 ++++++++++++++++++++ 1 file changed, 29 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-compress/blob/75bb4801/src/main/java/org/apache/commons/compress/compressors/lz77support/AbstractLZ77CompressorInputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/compress/compressors/lz77support/AbstractLZ77CompressorInputStream.java b/src/main/java/org/apache/commons/compress/compressors/lz77support/AbstractLZ77CompressorInputStream.java index 29bb320..cd9fb7e 100644 --- a/src/main/java/org/apache/commons/compress/compressors/lz77support/AbstractLZ77CompressorInputStream.java +++ b/src/main/java/org/apache/commons/compress/compressors/lz77support/AbstractLZ77CompressorInputStream.java @@ -41,6 +41,35 @@ import org.apache.commons.compress.utils.IOUtils; * implementation delegates to the no-arg version, leading to infinite * mutual recursion and a {@code StackOverflowError} otherwise.</p> * + * <p>The contract for subclasses {@code read} implementation is:</p> + * <ul> + * + * <li>keep track of the current state of the stream. Is it inside a + * literal block or a back-reference or in-between blocks?</li> + * + * <li>Use {@link #readOneByte} to access the underlying stream + * directly.</li> + * + * <li>If a new literal block starts, use {@link #startLiteral} to + * tell this class about it and read the literal data using {@link + * #readLiteral} until it returns {@code 0}. {@link + * #hasMoreDataInBlock} will return {@code false} before the next + * call to {@link #readLiteral} would return {@code 0}.</li> + * + * <li>If a new back-reference starts, use {@link #startBackReference} to + * tell this class about it and read the literal data using {@link + * #readBackReference} until it returns {@code 0}. {@link + * #hasMoreDataInBlock} will return {@code false} before the next + * call to {@link #readBackReference} would return {@code 0}.</li> + * + * <li>If the end of the stream has been reached, return {@code -1} + * as this class' methods will never do so themselves.</li> + * + * </ul> + * + * <p>{@link #readOneByte} and {@link #readLiteral} update the counter + * for bytes read.</p> + * * @since 1.14 */ public abstract class AbstractLZ77CompressorInputStream extends CompressorInputStream {
