htsjdk.beta.plugin.registry

Class HtsCodecResolver<C extends HtsCodec<?,?>>

java.lang.Object

htsjdk.beta.plugin.registry.HtsCodecResolver<C>

Type Parameters:

C - the HtsCodec type managed by this resolver

Direct Known Subclasses:

HaploidReferenceResolver, ReadsResolver, VariantsResolver

public class HtsCodecResolver<C extends HtsCodec<?,?>>
extends java.lang.Object

Base class for content-type-specific resolvers, with methods for resolving an input or output resource to a codec that can supply an encoder or decoder for that resource. Each resolver manages HtsCodecs of a single HtsContentType type, defined by the type parameters used to instantiate the resolver.

Methods in this class accept a bundle, and/or additional arguments, and return one or more matching codecs. The resolution methods use a series of probes to inspect resource structure and format to determine the file format in order to find codecs that claim to be able to process the resource.

Constructor Summary

Constructors

Constructor and Description
HtsCodecResolver(java.lang.String requiredContentType) Create a resolver for a given HtsCodec type, defined by the type parameter C.

Method Summary

Modifier and Type	Method and Description
java.util.List<C>	getCodecs() Get a list of all codecs of the type C managed by this resolver.
C	registerCodec(C codec) Register a codec of type C.
C	resolveForDecoding(Bundle bundle) Inspect a bundle and find a codec that can decode the primary resource.
C	resolveForEncoding(Bundle bundle) Inspect a bundle and find a codec that can encode to the primary resource.
C	resolveForEncoding(Bundle bundle, HtsVersion htsVersion) Inspect a bundle and find a codec that can encode to the primary resource using the format version requested.
java.util.List<C>	resolveForFormat(java.lang.String format) Get a list of codecs that claim to support file format format string
C	resolveFormatAndVersion(java.lang.String format, HtsVersion formatVersion) Get a list of codecs that claim to support version formatVersion of file format format.

Methods inherited from class java.lang.Object

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

Constructor Detail

HtsCodecResolver

public HtsCodecResolver(java.lang.String requiredContentType)

Create a resolver for a given HtsCodec type, defined by the type parameter C.

Parameters:

requiredContentType - the primary content type this resolver will use to interrogate a bundle to locate the primary resource when attempting to resolve the bundle to a codec

Method Detail

registerCodec

public C registerCodec(C codec)

Register a codec of type C. If a codec for the same format and version is already registered with this resolver, the resolver is updated with the new codec, and the previously registered codec is returned.

Parameters:

codec - a codec of type C

Returns:

the previously registered codec for the same format and version, or null if no codec was previously registered

resolveForDecoding

public C resolveForDecoding(Bundle bundle)

Inspect a bundle and find a codec that can decode the primary resource.

The resolution process starts with a list of candidate codecs consisting of all registered codecs that match this resolver's required content type. The bundle is then inspected to determine whether the primary resource is an IOPath or a stream, and the list of candidate codecs is reduced as follows:

If the primary resource is an IOPath:

1. The IOPath is passed to each candidate codec's HtsCodec.ownsURI(htsjdk.io.IOPath) method. If any codec returns true:
   1. The candidate list is first reduced to only those codecs that return true from HtsCodec.ownsURI(htsjdk.io.IOPath)
   2. The candidate list is then further reduced to only those codecs that return true from HtsCodec.canDecodeURI(IOPath).
2. Otherwise:
   1. The candidate list is first reduced to those codecs that return true from HtsCodec.canDecodeURI(IOPath)
   2. The candidate list is then further reduced to only those codecs that return true from HtsCodec.canDecodeSignature(SignatureStream, String)

If the primary resource is a stream:

1. The candidate list is reduced to those codecs that return true from HtsCodec.canDecodeSignature(SignatureStream, String)

If a single codec remains in the candidate list after the resolution process described above, that codec is returned. It is an error if more than one codec is remaining in the candidate list after codec resolution. This usually indicates that the registry contains an ill-behaved codec implementation.

Note: HtsCodec.canDecodeSignature(SignatureStream, String) will never be called by the framework on a resource if any codec returns true from HtsCodec.ownsURI(htsjdk.io.IOPath) for that resource.

Parameters:

bundle - the bundle to resolve to a codec

Returns:

a codec that can decode the bundle resource

Throws:

HtsjdkException - if no registered codecs can handle the resource

HtsjdkPluginException - if more than one codec claims to handle the resource. this usually indicates that the registry contains an incorrectly written codec.

resolveForEncoding

public C resolveForEncoding(Bundle bundle)

Inspect a bundle and find a codec that can encode to the primary resource. For bundles with a primary resource that is an IOPath, the structure of the IOPath (protocol scheme, file extension, and query parameters) are used to determine the file format to be used.

For resources that are ambiguous (i.e., a stream, which has no file extension that can be used to infer a format), the bundle resource must specify a format (see BundleResource.getFileFormat()) that corresponds to one of the formats for the content type used by this codec type. The newest available version of that file format will be used.

To request a specific version, see resolveForEncoding(Bundle, HtsVersion). To request a specific format and version, use resolveFormatAndVersion(String, HtsVersion).

Parameters:

bundle - the bundle to resolve to a codec for encoding

Returns:

A codec that can decode the input bundle

Throws:

HtsjdkException - if no registered codecs can handle the resource

HtsjdkPluginException - if more than one codec claims to handle the resource. this usually indicates that the registry contains an incorrectly written codec.

resolveForEncoding

public C resolveForEncoding(Bundle bundle,
                            HtsVersion htsVersion)

Inspect a bundle and find a codec that can encode to the primary resource using the format version requested. For bundles with a primary resource that is an IOPath, the structure of the IOPath (protocol scheme, file extension, and query parameters) are used to determine the file format used.

For resources that are ambiguous (i.e., a stream which has no file extension that can be used to infer a file format), the bundle resource must specify a format (see BundleResource.getFileFormat()) that corresponds to one of the formats for the requiredContentType used by this resolver.

Parameters:

bundle - the bundle to use for encoding

htsVersion - the version being requested (use HtsVersion.NEWEST_VERSION to use the newest version codec registered)

Returns:

A codec that can provide an encoder for the given inputs.

Throws:

HtsjdkException - if no registered codecs can handle the resource

HtsjdkPluginException - if more than one codec claims to handle the resource. this usually indicates that the registry contains an incorrectly written codec.

resolveForFormat

public java.util.List<C> resolveForFormat(java.lang.String format)

Get a list of codecs that claim to support file format format string

Parameters:

format - the format string of the input

Returns:

The list of registered codecs that claim to support some version of file format format

resolveFormatAndVersion

public C resolveFormatAndVersion(java.lang.String format,
                                 HtsVersion formatVersion)

Get a list of codecs that claim to support version formatVersion of file format format.

Parameters:

format - the input format

formatVersion - the version of format requested

Returns:

The list of registered codecs that claim to support version formatVersion of file format format

Throws:

HtsjdkException - if no registered codecs can handle the resource

getCodecs

public java.util.List<C> getCodecs()

Get a list of all codecs of the type C managed by this resolver.

Returns:

a list of all codecs of the type C managed by this resolver