Top Description Inners Fields Constructors Methods
org.apache.commons.compress.utils

public Class FixedLengthBlockOutputStream

extends OutputStream
implements WritableByteChannel
Class Inheritance
All Implemented Interfaces
java.nio.channels.WritableByteChannel, java.nio.channels.Channel, java.io.Closeable, java.lang.AutoCloseable
Imports
java.io.FileOutputStream, .IOException, .OutputStream, java.nio.ByteBuffer, .ByteOrder, java.nio.channels.ClosedChannelException, .WritableByteChannel, 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.

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.

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.

Any content written to this stream should be self-delimiting and should tolerate any padding added to fill the last block.

Since
1.15

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
FixedLengthBlockOutputStream.BufferAtATimeOutputChannel

Helper class to provide channel wrapper for arbitrary output stream that doesn't alter the size of writes.

Field Summary

Modifier and TypeField and Description
private final int
blockSize

private final ByteBuffer
buffer

private final AtomicBoolean
closed

private final WritableByteChannel
out

Constructor Summary

AccessConstructor and Description
public
FixedLengthBlockOutputStream(final OutputStream
The stream to wrap.
os, final int
The block size to use.
blockSize)

Constructs a fixed length block output stream with given destination stream and block size.

public
FixedLengthBlockOutputStream(final WritableByteChannel
The writable byte channel to wrap.
out, final int
The block size to use.
blockSize)

Constructs a fixed length block output stream with given destination writable byte channel and block size.

Method Summary

Modifier and TypeMethod and Description
public void
close()

Overrides java.io.OutputStream.close.

Implements java.nio.channels.Channel.close, java.io.Closeable.close.

Closes this channel.
public void
flushBlock()

Potentially pads and then writes the current block to the underlying stream.

public boolean
isOpen()

Implements java.nio.channels.Channel.isOpen.

Tells whether or not this channel is open.
private void
maybeFlush()

private void
padBlock()

public void
write(final byte[]
the data.
b, final int
the start offset in the data.
offset, final int
the number of bytes to write.
length)

Overrides java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream.
public int
write(final ByteBuffer
The buffer from which bytes are to be retrieved
src)

Implements java.nio.channels.WritableByteChannel.write.

Writes a sequence of bytes to this channel from the given buffer.
public void
write(final int
the byte.
b)

Implements abstract java.io.OutputStream.write.

Writes the specified byte to this output stream.
private void
writeBlock()

Inherited from java.io.OutputStream:
flushnullOutputStreamwrite

Field Detail

blockSizeback to summary
private final int blockSize
bufferback to summary
private final ByteBuffer buffer
closedback to summary
private final AtomicBoolean closed
outback to summary
private final WritableByteChannel out

Constructor Detail

FixedLengthBlockOutputStreamback to summary
public FixedLengthBlockOutputStream(final OutputStream os, final int blockSize)

Constructs a fixed length block output stream with given destination stream and block size.

Parameters
os:OutputStream

The stream to wrap.

blockSize:int

The block size to use.

FixedLengthBlockOutputStreamback to summary
public FixedLengthBlockOutputStream(final WritableByteChannel out, final int blockSize)

Constructs a fixed length block output stream with given destination writable byte channel and block size.

Parameters
out:WritableByteChannel

The writable byte channel to wrap.

blockSize:int

The block size to use.

Method Detail

closeback to summary
public void close() throws IOException

Overrides java.io.OutputStream.close.

Implements java.nio.channels.Channel.close, java.io.Closeable.close.

Doc from java.nio.channels.Channel.close.

Closes this channel.

After a channel is closed, any further attempt to invoke I/O operations upon it will cause a ClosedChannelException to be thrown.

If this channel is already closed then invoking this method has no effect.

This method may be invoked at any time. If some other thread has already invoked it, however, then another invocation will block until the first invocation is complete, after which it will return without effect.

Annotations
@Override
Exceptions
IOException:
If an I/O error occurs
flushBlockback to summary
public void flushBlock() throws IOException

Potentially pads and then writes the current block to the underlying stream.

Exceptions
IOException:
if writing fails
isOpenback to summary
public boolean isOpen()

Implements java.nio.channels.Channel.isOpen.

Doc from java.nio.channels.Channel.isOpen.

Tells whether or not this channel is open.

Returns:boolean

true if, and only if, this channel is open

Annotations
@Override
maybeFlushback to summary
private void maybeFlush() throws IOException
padBlockback to summary
private void padBlock()
writeback to summary
public void write(final byte[] b, final int offset, final int length) throws IOException

Overrides java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

Parameters
b:byte[]

the data.

offset:int

the start offset in the data.

length:int

the number of bytes to write.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs. In particular, an IOException is thrown if the output stream is closed.
writeback to summary
public int write(final ByteBuffer src) throws IOException

Implements java.nio.channels.WritableByteChannel.write.

Doc from java.nio.channels.WritableByteChannel.write.

Writes a sequence of bytes to this channel from the given buffer.

An attempt is made to write up to r bytes to the channel, where r is the number of bytes remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked; the index of the last byte written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

Unless otherwise specified, a write operation will return only after writing all of the r requested bytes. Some types of channels, depending upon their state, may write only some of the bytes or possibly none at all. A socket channel in non-blocking mode, for example, cannot write any more bytes than are free in the socket's output buffer.

This method may be invoked at any time. If another thread has already initiated a write operation upon this channel, however, then an invocation of this method will block until the first operation is complete.

Parameters
src:ByteBuffer

The buffer from which bytes are to be retrieved

Returns:int

The number of bytes written, possibly zero

Annotations
@Override
Exceptions
IOException:
If some other I/O error occurs
writeback to summary
public void write(final int b) throws IOException

Implements abstract java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

Parameters
b:int

the byte.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if the output stream has been closed.
writeBlockback to summary
private void writeBlock() throws IOException
org.apache.commons.compress.utils back to summary

private final Class FixedLengthBlockOutputStream.BufferAtATimeOutputChannel

extends Object
implements WritableByteChannel
Class Inheritance
  • java.lang.Object
  • org.apache.commons.compress.utils.FixedLengthBlockOutputStream.BufferAtATimeOutputChannel
All Implemented Interfaces
java.nio.channels.WritableByteChannel, java.nio.channels.Channel, java.io.Closeable, java.lang.AutoCloseable
Helper class to provide channel wrapper for arbitrary output stream that doesn't alter the size of writes. We can't use Channels.newChannel, because for non FileOutputStreams, it breaks up writes into 8KB max chunks. Since the purpose of this class is to always write complete blocks, we need to write a simple class to take care of it.

Field Summary

Modifier and TypeField and Description
private final AtomicBoolean
closed

private final OutputStream
out

Constructor Summary

AccessConstructor and Description
private
BufferAtATimeOutputChannel(final OutputStream out)

Method Summary

Modifier and TypeMethod and Description
public void
close()

Implements java.nio.channels.Channel.close.

Closes this channel.
public boolean
isOpen()

Implements java.nio.channels.Channel.isOpen.

Tells whether or not this channel is open.
public int
write(final ByteBuffer
The buffer from which bytes are to be retrieved
buffer)

Implements java.nio.channels.WritableByteChannel.write.

Writes a sequence of bytes to this channel from the given buffer.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

closedback to summary
private final AtomicBoolean closed
outback to summary
private final OutputStream out

Constructor Detail

BufferAtATimeOutputChannelback to summary
private BufferAtATimeOutputChannel(final OutputStream out)

Method Detail

closeback to summary
public void close() throws IOException

Implements java.nio.channels.Channel.close.

Doc from java.nio.channels.Channel.close.

Closes this channel.

After a channel is closed, any further attempt to invoke I/O operations upon it will cause a ClosedChannelException to be thrown.

If this channel is already closed then invoking this method has no effect.

This method may be invoked at any time. If some other thread has already invoked it, however, then another invocation will block until the first invocation is complete, after which it will return without effect.

Annotations
@Override
Exceptions
IOException:
If an I/O error occurs
isOpenback to summary
public boolean isOpen()

Implements java.nio.channels.Channel.isOpen.

Doc from java.nio.channels.Channel.isOpen.

Tells whether or not this channel is open.

Returns:boolean

true if, and only if, this channel is open

Annotations
@Override
writeback to summary
public int write(final ByteBuffer buffer) throws IOException

Implements java.nio.channels.WritableByteChannel.write.

Doc from java.nio.channels.WritableByteChannel.write.

Writes a sequence of bytes to this channel from the given buffer.

An attempt is made to write up to r bytes to the channel, where r is the number of bytes remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked; the index of the last byte written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

Unless otherwise specified, a write operation will return only after writing all of the r requested bytes. Some types of channels, depending upon their state, may write only some of the bytes or possibly none at all. A socket channel in non-blocking mode, for example, cannot write any more bytes than are free in the socket's output buffer.

This method may be invoked at any time. If another thread has already initiated a write operation upon this channel, however, then an invocation of this method will block until the first operation is complete.

Parameters
buffer:ByteBuffer

The buffer from which bytes are to be retrieved

Returns:int

The number of bytes written, possibly zero

Annotations
@Override
Exceptions
IOException:
If some other I/O error occurs