Package 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 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 `HtsCodec`s 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
Description
`HtsCodecResolver(String requiredContentType)`
Create a resolver for a given `HtsCodec` type, defined by the type parameter `C`.

## Method Summary

Modifier and Type
Method
Description
`protected List<C>`
`filterByVersion(List<C> candidateCodecs, HtsVersion htsVersion)`
Filter the candidate codecs, returning only those that match the requested version.
`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.
`List<C>`
`resolveForFormat(String format)`
Get a list of codecs that claim to support file format `format` string
`C`
`resolveFormatAndVersion(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 Details

### HtsCodecResolver

public HtsCodecResolver(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 Details

### 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 List<C> resolveForFormat(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(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 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

### filterByVersion

protected List<C> filterByVersion(List<C> candidateCodecs, HtsVersion htsVersion)
Filter the candidate codecs, returning only those that match the requested version. Only called for encoding.