htsjdk.samtools.util

Class BlockCompressedOutputStream

java.lang.Object

java.io.OutputStream

htsjdk.samtools.util.BlockCompressedOutputStream

All Implemented Interfaces:

LocationAware, java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

public class BlockCompressedOutputStream
extends java.io.OutputStream
implements LocationAware

Writer for a file that is a series of gzip blocks (BGZF format). The caller just treats it as an OutputStream, and under the covers a gzip block is written when the amount of uncompressed as-yet-unwritten bytes reaches a threshold. The advantage of BGZF over conventional gzip is that BGZF allows for seeking without having to scan through the entire file up to the position being sought. Note that the flush() method should not be called by client unless you know what you're doing, because it forces a gzip block to be written even if the number of buffered bytes has not reached threshold. close(), on the other hand, must be called when done writing in order to force the last gzip block to be written. c.f. http://samtools.sourceforge.net/SAM1.pdf for details of BGZF file format.

Constructor Summary

Constructors

Constructor and Description
BlockCompressedOutputStream(java.io.File file) Uses default compression level, which is 5 unless changed by setCompressionLevel Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory().
BlockCompressedOutputStream(java.io.File file, int compressionLevel) Prepare to compress at the given compression level
BlockCompressedOutputStream(java.io.File file, int compressionLevel, DeflaterFactory deflaterFactory) Prepare to compress at the given compression level
BlockCompressedOutputStream(java.io.OutputStream os, java.io.File file) Uses default compression level, which is 5 unless changed by setCompressionLevel Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory().
BlockCompressedOutputStream(java.io.OutputStream os, java.io.File file, int compressionLevel) Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory().
BlockCompressedOutputStream(java.io.OutputStream os, java.io.File file, int compressionLevel, DeflaterFactory deflaterFactory) Creates the output stream.
BlockCompressedOutputStream(java.lang.String filename) Uses default compression level, which is 5 unless changed by setCompressionLevel Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory().
BlockCompressedOutputStream(java.lang.String filename, int compressionLevel) Prepare to compress at the given compression level Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory().

Method Summary

Modifier and Type	Method and Description
void	close() close() must be called in order to flush any remaining buffered bytes.
void	flush() WARNING: flush() affects the output format, because it causes the current contents of uncompressedBuffer to be compressed and written, even if it isn't full.
static int	getDefaultCompressionLevel()
static DeflaterFactory	getDefaultDeflaterFactory()
long	getFilePointer() Encode virtual file pointer Upper 48 bits is the byte offset into the compressed stream of a block.
long	getPosition() The current offset, in bytes, of this stream/writer/file.
static BlockCompressedOutputStream	maybeBgzfWrapOutputStream(java.io.File location, java.io.OutputStream output)
static void	setDefaultCompressionLevel(int compressionLevel) Sets the GZip compression level for subsequent BlockCompressedOutputStream object creation that do not specify the compression level.
static void	setDefaultDeflaterFactory(DeflaterFactory deflaterFactory) Sets the default DeflaterFactory that will be used for all instances unless specified otherwise in the constructor.
void	write(byte[] bytes) Writes b.length bytes from the specified byte array to this output stream.
void	write(byte[] bytes, int startIndex, int numBytes) Writes len bytes from the specified byte array starting at offset off to this output stream.
void	write(int bite) Writes the specified byte to this output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.lang.String filename)

Uses default compression level, which is 5 unless changed by setCompressionLevel Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory(). Use BlockCompressedOutputStream(File, int, DeflaterFactory) to specify a custom factory.

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.io.File file)

Uses default compression level, which is 5 unless changed by setCompressionLevel Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory(). Use BlockCompressedOutputStream(File, int, DeflaterFactory) to specify a custom factory.

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.lang.String filename,
                                   int compressionLevel)

Prepare to compress at the given compression level Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory().

Parameters:

compressionLevel - 1 <= compressionLevel <= 9

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.io.File file,
                                   int compressionLevel)

Prepare to compress at the given compression level

Parameters:

compressionLevel - 1 <= compressionLevel <= 9 Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory(). Use BlockCompressedOutputStream(File, int, DeflaterFactory) to specify a custom factory.

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.io.File file,
                                   int compressionLevel,
                                   DeflaterFactory deflaterFactory)

Prepare to compress at the given compression level

Parameters:

compressionLevel - 1 <= compressionLevel <= 9

deflaterFactory - custom factory to create deflaters (overrides the default)

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.io.OutputStream os,
                                   java.io.File file)

Uses default compression level, which is 5 unless changed by setCompressionLevel Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory(). Use BlockCompressedOutputStream(OutputStream, File, int, DeflaterFactory) to specify a custom factory.

Parameters:

file - may be null

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.io.OutputStream os,
                                   java.io.File file,
                                   int compressionLevel)

Note: this constructor uses the default DeflaterFactory, see getDefaultDeflaterFactory(). Use BlockCompressedOutputStream(OutputStream, File, int, DeflaterFactory) to specify a custom factory.

BlockCompressedOutputStream

public BlockCompressedOutputStream(java.io.OutputStream os,
                                   java.io.File file,
                                   int compressionLevel,
                                   DeflaterFactory deflaterFactory)

Creates the output stream.

Parameters:

os - output stream to create a BlockCompressedOutputStream from

file - file to which to write the output or null if not available

compressionLevel - the compression level (0-9)

deflaterFactory - custom factory to create deflaters (overrides the default)

Method Detail

setDefaultCompressionLevel

public static void setDefaultCompressionLevel(int compressionLevel)

Sets the GZip compression level for subsequent BlockCompressedOutputStream object creation that do not specify the compression level.

Parameters:

compressionLevel - 1 <= compressionLevel <= 9

getDefaultCompressionLevel

public static int getDefaultCompressionLevel()

setDefaultDeflaterFactory

public static void setDefaultDeflaterFactory(DeflaterFactory deflaterFactory)

Sets the default DeflaterFactory that will be used for all instances unless specified otherwise in the constructor. If this method is not called the default is a factory that will create the JDK Deflater.

Parameters:

deflaterFactory - non-null default factory.

getDefaultDeflaterFactory

public static DeflaterFactory getDefaultDeflaterFactory()

maybeBgzfWrapOutputStream

public static BlockCompressedOutputStream maybeBgzfWrapOutputStream(java.io.File location,
                                                                    java.io.OutputStream output)

Parameters:

location - May be null. Used for error messages, and for checking file termination.

output - May or not already be a BlockCompressedOutputStream.

Returns:

A BlockCompressedOutputStream, either by wrapping the given OutputStream, or by casting if it already is a BCOS.

write

public void write(byte[] bytes)
           throws java.io.IOException

Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).

Overrides:

write in class java.io.OutputStream

Parameters:

bytes - the data

Throws:

java.io.IOException

write

public void write(byte[] bytes,
                  int startIndex,
                  int numBytes)
           throws java.io.IOException

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.

Overrides:

write in class java.io.OutputStream

Parameters:

bytes - the data

startIndex - the start offset in the data

numBytes - the number of bytes to write

Throws:

java.io.IOException

flush

public void flush()
           throws java.io.IOException

WARNING: flush() affects the output format, because it causes the current contents of uncompressedBuffer to be compressed and written, even if it isn't full. Unless you know what you're doing, don't call flush(). Instead, call close(), which will flush any unwritten data before closing the underlying stream.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.OutputStream

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

close() must be called in order to flush any remaining buffered bytes. An unclosed file will likely be defective.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.OutputStream

Throws:

java.io.IOException

write

public void write(int bite)
           throws java.io.IOException

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.

Specified by:

write in class java.io.OutputStream

Parameters:

bite -

Throws:

java.io.IOException

getFilePointer

public long getFilePointer()

Encode virtual file pointer Upper 48 bits is the byte offset into the compressed stream of a block. Lower 16 bits is the byte offset into the uncompressed stream inside the block.

getPosition

public long getPosition()

Description copied from interface: LocationAware

The current offset, in bytes, of this stream/writer/file. Or, if this is an iterator/producer, the offset (in bytes) of the END of the most recently returned record (since a produced record corresponds to something that has been read already). See class javadoc for more. Note that for BGZF files, this does not represent an actually file position, but a virtual file pointer.

Specified by:

getPosition in interface LocationAware