htsjdk.tribble

Interface FeatureCodec<FEATURE_TYPE extends Feature,SOURCE>

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, GeliTextCodec, VCF3Codec, VCFCodec

public interface FeatureCodec<FEATURE_TYPE extends Feature,SOURCE>

The base interface for classes that read in features.

FeatureCodecs have to implement two key methods:

#readHeader(SOURCE) - Reads the header, provided a SOURCE pointing at the beginning of the source input. #decode(SOURCE) - Reads a Feature record, provided a SOURCE pointing at the beginning of a record within the source input.

Note that it's not safe to carry state about the SOURCE within the codec. There's no guarantee about its state between calls.

Method Summary

Modifier and Type	Method and Description
boolean	canDecode(java.lang.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 SOURCE.
FEATURE_TYPE	decode(SOURCE source) Decode a single Feature from the SOURCE, 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.
java.lang.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 SOURCE has more data.
LocationAware	makeIndexableSourceFromStream(java.io.InputStream bufferedInputStream) Generates a LocationAware reader of type SOURCE.
SOURCE	makeSourceFromStream(java.io.InputStream bufferedInputStream) Generates a reader of type SOURCE 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 java.io.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:

java.io.IOException

decode

FEATURE_TYPE decode(SOURCE source)
             throws java.io.IOException

Decode a single Feature from the SOURCE, 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:

java.io.IOException

readHeader

FeatureCodecHeader readHeader(SOURCE source)
                       throws java.io.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 SOURCE 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:

java.io.IOException

getFeatureType

java.lang.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(java.io.InputStream bufferedInputStream)

Generates a reader of type SOURCE appropriate for use by this codec from the generic input stream. Implementers should assume the stream is buffered.

makeIndexableSourceFromStream

LocationAware makeIndexableSourceFromStream(java.io.InputStream bufferedInputStream)

Generates a LocationAware reader of type SOURCE. 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 SOURCE. 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 SOURCE when applicable.

isDone

boolean isDone(SOURCE source)

Adapter method that assesses whether the provided SOURCE has more data. True if it does, false otherwise.

close

void close(SOURCE source)

Adapter method that closes the provided SOURCE.

canDecode

boolean canDecode(java.lang.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)

Returns:

the format to use with tabix

Throws:

TribbleException - if the format is not defined