htsjdk.beta.codecs.variants.vcf

Class VCFCodec

java.lang.Object

htsjdk.beta.codecs.variants.vcf.VCFCodec

All Implemented Interfaces:

HtsCodec<VariantsDecoderOptions,VariantsEncoderOptions>, Upgradeable, VariantsCodec

Direct Known Subclasses:

VCFCodecV3_2, VCFCodecV3_3, VCFCodecV4_0, VCFCodecV4_1, VCFCodecV4_2, VCFCodecV4_3

@InternalAPI
public abstract class VCFCodec
extends java.lang.Object
implements VariantsCodec

InternalAPI Base class for concrete implementations of HtsContentType.VARIANT_CONTEXTS codecs.

Constructor Summary

Constructors

Constructor and Description
VCFCodec()

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.
boolean	canDecodeURI(IOPath ioPath) Determine if the URI for ioPath (obtained via IOPath.getURI()) conforms to the expected URI format this codec's file format.
java.lang.String	getFileFormat() Get the name of the file format supported by this codec.
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.
protected abstract java.lang.String	getSignatureString() Get the signature string for this codec.

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.variants.VariantsCodec

getContentType

Methods inherited from interface htsjdk.beta.plugin.HtsCodec

getDecoder, getDisplayName, getEncoder, getVersion, ownsURI

Methods inherited from interface htsjdk.beta.plugin.Upgradeable

runVersionUpgrade

Constructor Detail

VCFCodec

public VCFCodec()

Method Detail

getFileFormat

public java.lang.String getFileFormat()

Description copied from interface: HtsCodec

Get the name of the file format supported by this codec. The format name defines the underlying format handled by this codec, and also corresponds to the format of the primary bundle resource that is required when decoding or encoding (see BundleResourceType and BundleResource.getFileFormat()).

Specified by:

getFileFormat in interface HtsCodec<VariantsDecoderOptions,VariantsEncoderOptions>

Returns:

the name of the underlying file format handled by this codec

canDecodeURI

public boolean canDecodeURI(IOPath ioPath)

Description copied from interface: HtsCodec

Determine if the URI for ioPath (obtained via IOPath.getURI()) conforms to the expected URI format this codec's file format.

Most implementations only look at the file extension (see IOPath.hasExtension(java.lang.String)). For codecs that implement formats that use specific, well known file extensions, the codec should reject inputs that do not conform to any of the accepted extensions. If the format does not use a specific extension, or if the codec cannot determine if it can decode the underlying resource without inspecting the underlying stream, it is safe to return true, after which the framework will subsequently call this codec's HtsCodec.canDecodeSignature(SignatureStream, String) method, at which time the codec can inspect the actual underlying stream via the SignatureStream.

Implementations should generally not inspect the URI's protocol scheme unless the file format supported by the codec requires the use a specific protocol scheme. For codecs that do own a specific scheme or URI format, the return values for HtsCodec.ownsURI(IOPath) and HtsCodec.canDecodeURI(IOPath) must always be the same (both true or both false) for a given IOPath. For codecs that do not use a custom URI (and rely on NIO access), @link #ownsURI(IOPath)} should always return false, with only the value returned from HtsCodec.canDecodeURI(IOPath) varying based on features such as file extension probes.

It is never safe to attempt to directly inspect the underlying stream for ioPath in this method. If the stream needs to be inspected, it should be done using the signature stream when the HtsCodec.canDecodeSignature(SignatureStream, String) method is called.

For custom URI handlers (see HtsCodec.ownsURI(IOPath), codecs should avoid making remote calls to determine the suitability of the input resource; the return value for this method should be based only on the format of the URI that is presented. Since this method is used during codec resolution, implementations should avoid calling methods that may throw exceptions.

Specified by:

canDecodeURI in interface HtsCodec<VariantsDecoderOptions,VariantsEncoderOptions>

Parameters:

ioPath - to be decoded

Returns:

true if the codec can provide a decoder to provide this URI

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.

Specified by:

getSignatureLength in interface HtsCodec<VariantsDecoderOptions,VariantsEncoderOptions>

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.

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.

Specified by:

getSignatureProbeLength in interface HtsCodec<VariantsDecoderOptions,VariantsEncoderOptions>

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.

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.

Specified by:

canDecodeSignature in interface HtsCodec<VariantsDecoderOptions,VariantsEncoderOptions>

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

getSignatureString

protected abstract java.lang.String getSignatureString()

Get the signature string for this codec.

Returns:

the signature string for this codec