Repository: commons-compress Updated Branches: refs/heads/master 8a6d8a574 -> fd7b3c165
Add javadoc for FixedLengthBlockOutputStream. Signed-off-by: Simon Spero <sesunc...@gmail.com> Project: http://git-wip-us.apache.org/repos/asf/commons-compress/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-compress/commit/567dc4bd Tree: http://git-wip-us.apache.org/repos/asf/commons-compress/tree/567dc4bd Diff: http://git-wip-us.apache.org/repos/asf/commons-compress/diff/567dc4bd Branch: refs/heads/master Commit: 567dc4bdbee04919c5d8b06a4df0498b3f078b6c Parents: 8a6d8a5 Author: Simon Spero <sesunc...@gmail.com> Authored: Thu Jun 15 15:25:43 2017 -0400 Committer: Stefan Bodewig <bode...@apache.org> Committed: Fri Jun 16 09:30:52 2017 +0200 ---------------------------------------------------------------------- .../utils/FixedLengthBlockOutputStream.java | 28 ++++++++++++++++++++ 1 file changed, 28 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-compress/blob/567dc4bd/src/main/java/org/apache/commons/compress/utils/FixedLengthBlockOutputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/compress/utils/FixedLengthBlockOutputStream.java b/src/main/java/org/apache/commons/compress/utils/FixedLengthBlockOutputStream.java index 19831ff..9d59e99 100644 --- a/src/main/java/org/apache/commons/compress/utils/FixedLengthBlockOutputStream.java +++ b/src/main/java/org/apache/commons/compress/utils/FixedLengthBlockOutputStream.java @@ -27,6 +27,25 @@ import java.nio.channels.ClosedChannelException; import java.nio.channels.WritableByteChannel; import java.util.concurrent.atomic.AtomicBoolean; +/** + * This class supports writing to an Outputstream or WritableByteChannel in fixed length blocks. + * It can be be used to support output to devices such as tape drives that require output in this + * format. If the final block does not have enough content to fill an entire block, the output will + * be padded to a full block size. + * <p/> + * This class can be used to support TAR,PAX, and CPIO blocked output to character special devices. + * It is not recommended that this class be used unless writing to such devices, as the padding + * serves no useful purpose in such cases. + * <p/> + * This class should normally wrap a FileOutputStream or associated WritableByteChannel directly. + * If there is an intervening filter that modified the output, such as a CompressorOutputStream, or + * performs its own buffering, such as BufferedOutputStream, output to the device may + * no longer be of the specified size. + * <p/> + * Any content written to this stream should be self-delimiting and should tolerate any padding + * added to fill the last block + * . + */ public class FixedLengthBlockOutputStream extends OutputStream implements WritableByteChannel, AutoCloseable { @@ -35,6 +54,11 @@ public class FixedLengthBlockOutputStream extends OutputStream implements Writab private final ByteBuffer buffer; private final AtomicBoolean closed = new AtomicBoolean(false); + /** + * Create a fixed length block output stream with given destination stream and block size + * @param os The stream to wrap. + * @param blockSize The block size to use. + */ public FixedLengthBlockOutputStream(OutputStream os, int blockSize) { if (os instanceof FileOutputStream) { FileOutputStream fileOutputStream = (FileOutputStream) os; @@ -46,6 +70,10 @@ public class FixedLengthBlockOutputStream extends OutputStream implements Writab } this.blockSize = blockSize; } + /** Create a fixed length block output stream with given destination writable byte channel and block size + * @param out The writable byte channel to wrap. + * @param blockSize The block size to use. + */ public FixedLengthBlockOutputStream(WritableByteChannel out, int blockSize) { this.out = out;