commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject commons-compress git commit: document how the class wants to get used
Date Tue, 07 Feb 2017 05:22:06 GMT
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 <bodewig@apache.org>
Authored: Tue Feb 7 06:21:41 2017 +0100
Committer: Stefan Bodewig <bodewig@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 {


Mime
View raw message