FeatureCodec (htsjdk 2.14.3 API)

Type Parameters:

FEATURE_TYPE - The type of Feature this codec generates

SOURCE - The type of the data source this codec reads from

All Known Implementing Classes:

AbstractFeatureCodec, AbstractVCFCodec, AsciiFeatureCodec, BCF2Codec, BEDCodec, BinaryFeatureCodec, ExampleBinaryCodec, VCF3Codec, VCFCodec
```
public interface FeatureCodec<FEATURE_TYPE extends Feature,SOURCE>
```
The base interface for classes that read in features.
FeatureCodecs must implement several key methods:
- makeSourceFromStream(java.io.InputStream) Return a FeatureCodec for this FeatureCodec given an input stream that is buffered.
- makeIndexableSourceFromStream(java.io.InputStream) Return a FeatureCodec for this FeatureCodec that implements LocationAware, and is thus suitable for use during indexing. During the indexing process, the indexer passes the FeatureCodec to the codec to consume Features from the underlying FeatureCodec, one at a time, recording the Feature location via the FeatureCodec's LocationAware interface. Therefore, it is essential that the FeatureCodec implementation, the readHeader(SOURCE) method, and the decodeLoc(SOURCE) method, not introduce any buffering that would that would advance the FeatureCodec more than a single feature (or the more than the size of the header, in the case of readHeader(SOURCE)). Otherwise the index will be corrupt.
- readHeader(SOURCE) - Reads the header, provided a FeatureCodec pointing at the beginning of the source input. The implementation of this method must not consume any input from the underlying SOURCE beyond the end of the header.
- decode(SOURCE) - Reads a Feature record, provided a FeatureCodec pointing at the beginning of a record within the source input.
- decodeLoc(SOURCE) - Reads a Feature record, provided a FeatureCodec pointing at the beginning of a record within the source input. The implementation of this method must not consume any input from the underlying stream beyond the end of the Feature returned.
Note that it's not safe to carry state about the FeatureCodec within the codec. There's no guarantee about its state between calls.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`boolean`	`canDecode(String path)`	This function returns true iff the File potentialInput can be parsed by this codec.
`void`	`close(SOURCE source)`	Adapter method that closes the provided `FeatureCodec`.
`FEATURE_TYPE`	`decode(SOURCE source)`	Decode a single `Feature` from the `FeatureCodec`, reading no further in the underlying source than beyond that feature.
`Feature`	`decodeLoc(SOURCE source)`	Decode a line to obtain just its FeatureLoc for indexing -- contig, start, and stop.
`Class<FEATURE_TYPE>`	`getFeatureType()`	This function returns the object the codec generates.
`default TabixFormat`	`getTabixFormat()`	Define the tabix format for the feature, used for indexing.
`boolean`	`isDone(SOURCE source)`	Adapter method that assesses whether the provided `FeatureCodec` has more data.
`LocationAware`	`makeIndexableSourceFromStream(InputStream inputStream)`	Return a `FeatureCodec` for this `FeatureCodec` that implements `LocationAware`, and is thus suitable for use during indexing.
`SOURCE`	`makeSourceFromStream(InputStream bufferedInputStream)`	Generates a reader of type `FeatureCodec` appropriate for use by this codec from the generic input stream.
`FeatureCodecHeader`	`readHeader(SOURCE source)`	Read and return the header, or null if there is no header.

- Method Detail
  - decodeLoc
```
Feature decodeLoc(SOURCE source)
           throws IOException
```
    Decode a line to obtain just its FeatureLoc for indexing -- contig, start, and stop.
    
    Parameters:
    
    source - the input stream from which to decode the next record
    
    Returns:
    
    Return the FeatureLoc encoded by the line, or null if the line does not represent a feature (e.g. is a comment)
    
    Throws:
    
    IOException
  - decode
```
FEATURE_TYPE decode(SOURCE source)
             throws IOException
```
    Decode a single Feature from the FeatureCodec, reading no further in the underlying source than beyond that feature.
    
    Parameters:
    
    source - the input stream from which to decode the next record
    
    Returns:
    
    Return the Feature encoded by the line, or null if the line does not represent a feature (e.g. is a comment)
    
    Throws:
    
    IOException
  - readHeader
```
FeatureCodecHeader readHeader(SOURCE source)
                       throws IOException
```
    Read and return the header, or null if there is no header. Note: Implementers of this method must be careful to read exactly as much from FeatureCodec as needed to parse the header, and no more. Otherwise, data that might otherwise be fed into parsing a Feature may be lost.
    
    Parameters:
    
    source - the source from which to decode the header
    
    Returns:
    
    header object
    
    Throws:
    
    IOException
  - getFeatureType
```
Class<FEATURE_TYPE> getFeatureType()
```
    This function returns the object the codec generates. This is allowed to be Feature in the case where conditionally different types are generated. Be as specific as you can though.
    
    This function is used by reflections based tools, so we can know the underlying type
    
    Returns:
    
    the feature type this codec generates.
  - makeSourceFromStream
```
SOURCE makeSourceFromStream(InputStream bufferedInputStream)
```
    Generates a reader of type FeatureCodec appropriate for use by this codec from the generic input stream. Implementers should assume the stream is buffered.
  - makeIndexableSourceFromStream
```
LocationAware makeIndexableSourceFromStream(InputStream inputStream)
```
    Return a FeatureCodec for this FeatureCodec that implements LocationAware, and is thus suitable for use during indexing. Like makeSourceFromStream(java.io.InputStream), except the LocationAware compatibility is required for creating indexes.
    Implementers of this method must return a type that is both LocationAware as well as FeatureCodec. Note that this requirement cannot be enforced via the method signature due to limitations in Java's generic typing system. Instead, consumers should cast the call result into a FeatureCodec when applicable.
    NOTE: During the indexing process, the indexer passes the FeatureCodec to the codec to consume Features from the underlying FeatureCodec, one at a time, recording the Feature location via the FeatureCodec's LocationAware interface. Therefore, it is essential that the FeatureCodec implementation, the readHeader(SOURCE) method, and the decodeLoc(SOURCE) method, which are used during indexing, not introduce any buffering that would that would advance the FeatureCodec more than a single feature (or the more than the size of the header, in the case of readHeader(SOURCE)).
  - isDone
```
boolean isDone(SOURCE source)
```
    Adapter method that assesses whether the provided FeatureCodec has more data. True if it does, false otherwise.
  - close
```
void close(SOURCE source)
```
    Adapter method that closes the provided FeatureCodec.
  - canDecode
```
boolean canDecode(String path)
```
    This function returns true iff the File potentialInput can be parsed by this codec. Note that checking the file's extension is a perfectly acceptable implementation of this method and file contents only rarely need to be checked.
    
    There is an assumption that there's never a situation where two different Codecs return true for the same file. If this occurs, the recommendation would be to error out.
    Note this function must never throw an error. All errors should be trapped and false returned.
    
    Parameters:
    
    path - the file to test for parsability with this codec
    
    Returns:
    
    true if potentialInput can be parsed, false otherwise
  - getTabixFormat
```
default TabixFormat getTabixFormat()
```
    Define the tabix format for the feature, used for indexing. Default implementation throws an exception. Note that only AsciiFeatureCodec could read tabix files as defined in AbstractFeatureReader.getFeatureReader(String, String, FeatureCodec, boolean, java.util.function.Function, java.util.function.Function)
    
    Returns:
    
    the format to use with tabix
    
    Throws:
    
    TribbleException - if the format is not defined

Interface FeatureCodec<FEATURE_TYPE extends Feature,SOURCE>

Method Summary

Method Detail

decodeLoc

decode

readHeader

getFeatureType

makeSourceFromStream

makeIndexableSourceFromStream

isDone

close

canDecode

getTabixFormat