htsjdk.beta.codecs.reads.bam.bamV1_0

Class BAMCodecV1_0

java.lang.Object

htsjdk.beta.codecs.reads.bam.BAMCodec

htsjdk.beta.codecs.reads.bam.bamV1_0.BAMCodecV1_0

All Implemented Interfaces:

HtsCodec<ReadsDecoderOptions,ReadsEncoderOptions>, ReadsCodec, Upgradeable

public class BAMCodecV1_0
extends BAMCodec

BAM v1.0 codec.

Field Summary

Fields

Modifier and Type	Field and Description
static HtsVersion	VERSION_1

Fields inherited from class htsjdk.beta.codecs.reads.bam.BAMCodec

BAM_DEFAULT_VERSION

Constructor Summary

Constructors

Constructor and Description
BAMCodecV1_0()

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeSignature(SignatureStream probingInputStream, java.lang.String sourceName) Determine if the codec can decode an input stream by inspecting a signature embedded within the stream.
BAMDecoder	getDecoder(Bundle inputBundle, ReadsDecoderOptions decoderOptions) Get an HtsDecoder to decode the provided inputs.
BAMEncoder	getEncoder(Bundle outputBundle, ReadsEncoderOptions encoderOptions) Get an HtsEncoder to encode to the provided outputs.
int	getSignatureLength() Get the number of bytes in the format and version signature used by the file format supported by this codec.
int	getSignatureProbeLength() Get the number of bytes of needed by this codec to probe an input stream for a format/version signature, and determine if it can supply a decoder for the stream.
HtsVersion	getVersion() Get the version of the file format returned by HtsCodec.getFileFormat() that is supported by this codec.
boolean	runVersionUpgrade(HtsVersion sourceCodecVersion, HtsVersion targetCodecVersion)

Methods inherited from class htsjdk.beta.codecs.reads.bam.BAMCodec

canDecodeURI, getFileFormat

Methods inherited from class java.lang.Object

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

Methods inherited from interface htsjdk.beta.plugin.reads.ReadsCodec

getContentType

Methods inherited from interface htsjdk.beta.plugin.HtsCodec

getDisplayName, ownsURI

Field Detail

VERSION_1

public static final HtsVersion VERSION_1

Constructor Detail

BAMCodecV1_0

public BAMCodecV1_0()

Method Detail

getVersion

public HtsVersion getVersion()

Description copied from interface: HtsCodec

Get the version of the file format returned by HtsCodec.getFileFormat() that is supported by this codec.

Returns:

the file format version (HtsVersion) supported by this codec

getSignatureProbeLength

public int getSignatureProbeLength()

Description copied from interface: HtsCodec

Get the number of bytes of needed by this codec to probe an input stream for a format/version signature, and determine if it can supply a decoder for the stream.

Returns:

the number of bytes this codec must consume from a stream in order to determine whether it can decode that stream. This number may differ from the actual signature size as returned by HtsCodec.getSignatureLength() for codecs that support compressed or encrypted streams, since they may require a larger and more semantically meaningful input fragment (such as an entire encrypted or compressed block) in order to inspect the plaintext signature.

Therefore signatureProbeLength should be expressed in "compressed/encrypted" space rather than "plaintext" space. The length returned from this method is used to determine the size of the SignatureStream that is subsequently passed to HtsCodec.canDecodeSignature(SignatureStream, String).

Note: Codecs that are custom URI handlers (those that return true for HtsCodec.ownsURI(IOPath)), should always return 0 from this method when it is called. Since this method is used during codec resolution, implementations should avoid calling methods that may throw exceptions.

getSignatureLength

public int getSignatureLength()

Description copied from interface: HtsCodec

Get the number of bytes in the format and version signature used by the file format supported by this codec.

Returns:

if the file format supported by this codecs is not remote, and is accessible via a local file or stream, the size of the unique signature/version for this file format. otherwise 0.

Note: Codecs that are custom URI handlers (those that return true for HtsCodec.ownsURI(htsjdk.io.IOPath)), should always return 0 from this method. Since this method is used during codec resolution, implementations should avoid calling methods that may throw exceptions.

canDecodeSignature

public boolean canDecodeSignature(SignatureStream probingInputStream,
                                  java.lang.String sourceName)

Description copied from interface: HtsCodec

Determine if the codec can decode an input stream by inspecting a signature embedded within the stream.

The probingInputStream stream will contain only a fragment of the actual input stream, taken from the start of the stream, the size of which will be the lesser of:

1. the number of bytes returned by HtsCodec.getSignatureProbeLength()
2. the entire input stream, for streams that are smaller than HtsCodec.getSignatureProbeLength()

Codecs that handle custom URIs that reference remote resources (those that return true for HtsCodec.ownsURI(htsjdk.io.IOPath)) should generally not inspect the stream, and should return false from this method, since the method will never be called with any resource for which HtsCodec.ownsURI(htsjdk.io.IOPath) returned true. Since this method is used during codec resolution, implementations should avoid calling methods that may throw exceptions.

Parameters:

probingInputStream - the stream to be inspect for the resource's embedded signature and version

sourceName - a display name describing the source of the input stream, for use in error messages

Returns:

true if this codec recognizes the stream by it's signature, and can provide a decoder to decode the stream, otherwise false

getDecoder

public BAMDecoder getDecoder(Bundle inputBundle,
                             ReadsDecoderOptions decoderOptions)

Description copied from interface: HtsCodec

Get an HtsDecoder to decode the provided inputs. The input bundle must contain resources of the type required by this codec. To find a codec appropriate for decoding a given resource, use an HtsCodecResolver obtained from an HtsCodecRegistry.

The framework will never call thi* method unless either HtsCodec.ownsURI(IOPath), or HtsCodec.canDecodeURI(IOPath) and HtsCodec.canDecodeSignature(SignatureStream, String) (IOPath)} return true for inputBundle.

Parameters:

inputBundle - input to be decoded. To get a decoder for use with index queries that use HtsQuery methods, the bundle must contain an index resource.

decoderOptions - options for the decoder to use

Returns:

an HtsDecoder that can decode the provided inputs

getEncoder

public BAMEncoder getEncoder(Bundle outputBundle,
                             ReadsEncoderOptions encoderOptions)

Description copied from interface: HtsCodec

Get an HtsEncoder to encode to the provided outputs. The output bundle must contain resources of the type required by this codec. To find a codec appropriate for encoding a given resource, use an HtsCodecResolver obtained from an HtsCodecRegistry.

The framework will never call this method unless either HtsCodec.ownsURI(IOPath), or HtsCodec.canDecodeURI(IOPath) returned true for outputBundle.

Parameters:

outputBundle - target output for the encoder

encoderOptions - encoder options to use

Returns:

an HtsEncoder suitable for writing to the provided outputs

runVersionUpgrade

public boolean runVersionUpgrade(HtsVersion sourceCodecVersion,
                                 HtsVersion targetCodecVersion)