Class SAMCodec
- All Implemented Interfaces:
HtsCodec<ReadsDecoderOptions,
,ReadsEncoderOptions> ReadsCodec
,Upgradeable
- Direct Known Subclasses:
SAMCodecV1_0
BundleResourceType.FMT_READS_SAM
codecs.-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
canDecodeSignature
(SignatureStream probingInputStream, 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 forioPath
(obtained viaIOPath.getURI()
) conforms to the expected URI format this codec's file format.Get a user-friendly display name for this codec.Get the name of the file format supported by this codec.int
Get the number of bytes in the format and version signature used by the file format supported by this codec.int
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.boolean
Determine if this codec "owns" the URI contained inioPath
see (IOPath.getURI()
).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.HtsCodec
getDecoder, getEncoder, getVersion
Methods inherited from interface htsjdk.beta.plugin.reads.ReadsCodec
getContentType
Methods inherited from interface htsjdk.beta.plugin.Upgradeable
runVersionUpgrade
-
Constructor Details
-
SAMCodec
public SAMCodec()
-
-
Method Details
-
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 (seeBundleResourceType
andBundleResource.getFileFormat()
).- Specified by:
getFileFormat
in interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - Returns:
- the name of the underlying file format handled by this codec
-
getDisplayName
Description copied from interface:HtsCodec
Get a user-friendly display name for this codec. It is recommended that the display name minimally include both the name of the supported file format and the supported version.- Specified by:
getDisplayName
in interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - Returns:
- a user-friendly display name for this codec
-
ownsURI
Description copied from interface:HtsCodec
Determine if this codec "owns" the URI contained inioPath
see (IOPath.getURI()
).A codec "owns" the URI only if it has specific requirements on the URI protocol scheme, URI format, or query parameters that go beyond a simple file extension, AND it explicitly recognizes the URI as conforming to those requirements. File formats that only require a specific file extension should always return false from
HtsCodec.ownsURI(htsjdk.io.IOPath)
, and should instead use the extension as a filter inHtsCodec.canDecodeURI(IOPath)
.Returning true from this method will cause the framework to bypass the stream-oriented signature probing that is used to resolve inputs to a codec handler. During codec resolution, if any registered codec returns true for this method on
ioPath
, the signature probing protocol will instead:- immediately prune the list of candidate codecs to only those that return true for this method
on
ioPath
- not attempt to obtain an InputStream on the IOPath containing the URI, on the assumption that special handling is required in order to access the underlying resource (i.e., htsget codec would claim an "http://" URI if the rest of the URI conforms to the expected format for that codec's protocol).
Any codec that returns true from
HtsCodec.ownsURI(IOPath)
for a given IOPath must also return true fromHtsCodec.canDecodeURI(IOPath)
for the same IOPath. For custom URI handlers, codecs should avoid making remote calls to determine the suitability or accessibility of the input resource; the return value for this method should be based only on the format of the URI that is presented. Operations that require remote access that can fail, such as validating server connectivity, authentication, or authorization, should be deferred until data is requested by the caller via the codec'sHtsEncoder
orHtsDecoder
. Since this method is used during codec resolution, implementations should avoid calling methods that may throw exceptions.- Specified by:
ownsURI
in interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - Parameters:
ioPath
- the ioPath to inspect- Returns:
- true if the ioPath's URI represents a custom URI that this codec handles
- immediately prune the list of candidate codecs to only those that return true for this method
on
-
canDecodeURI
Description copied from interface:HtsCodec
Determine if the URI forioPath
(obtained viaIOPath.getURI()
) conforms to the expected URI format this codec's file format. Most implementations only look at the file extension (seeIOPath.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'sHtsCodec.canDecodeSignature(SignatureStream, String)
method, at which time the codec can inspect the actual underlying stream via theSignatureStream
.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)
andHtsCodec.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 fromHtsCodec.canDecodeURI(IOPath)
varying based on features such as file extension probes.It is never safe to attempt to directly inspect the underlying stream for
For custom URI handlers (seeioPath
in this method. If the stream needs to be inspected, it should be done using the signature stream when theHtsCodec.canDecodeSignature(SignatureStream, String)
method is called.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 interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - Parameters:
ioPath
- to be decoded- Returns:
- true if the codec can provide a decoder to provide this URI
-
canDecodeSignature
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:- the number of bytes returned by
HtsCodec.getSignatureProbeLength()
- 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 whichHtsCodec.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 interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - Parameters:
probingInputStream
- the stream to be inspect for the resource's embedded signature and versionsourceName
- 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
- the number of bytes returned by
-
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 interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - 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 theSignatureStream
that is subsequently passed toHtsCodec.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.- Specified by:
getSignatureLength
in interfaceHtsCodec<ReadsDecoderOptions,
ReadsEncoderOptions> - 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.
-