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 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 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