Package htsjdk.tribble
Interface FeatureCodec<FEATURE_TYPE extends Feature,SOURCE>
- Type Parameters:
FEATURE_TYPE
- The type ofFeature
this codec generatesSOURCE
- The type of the data source this codec reads from
- All Known Implementing Classes:
AbstractFeatureCodec
,AbstractVCFCodec
,AsciiFeatureCodec
,BCF2Codec
,BEDCodec
,BinaryFeatureCodec
,ExampleBinaryCodec
,Gff3Codec
,IntervalListCodec
,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 aFeatureCodec
for thisFeatureCodec
given an input stream that is buffered.makeIndexableSourceFromStream(java.io.InputStream)
Return aFeatureCodec
for thisFeatureCodec
that implementsLocationAware
, and is thus suitable for use during indexing. During the indexing process, the indexer passes theFeatureCodec
to the codec to consume Features from the underlyingFeatureCodec
, one at a time, recording the Feature location via theFeatureCodec
'sLocationAware
interface. Therefore, it is essential that theFeatureCodec
implementation, thereadHeader(SOURCE)
method, and thedecodeLoc(SOURCE)
method, not introduce any buffering that would that would advance theFeatureCodec
more than a single feature (or the more than the size of the header, in the case ofreadHeader(SOURCE)
). Otherwise the index will be corrupt.readHeader(SOURCE)
- Reads the header, provided aFeatureCodec
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 aFeature
record, provided aFeatureCodec
pointing at the beginning of a record within the source input.decodeLoc(SOURCE)
- Reads aFeature
record, provided aFeatureCodec
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 theFeature
returned.
FeatureCodec
within the codec. There's no guarantee about its
state between calls.-
Method Summary
Modifier and TypeMethodDescriptionboolean
This function returns true iff the File potentialInput can be parsed by this codec.void
Adapter method that closes the providedFeatureCodec
.Decode a singleFeature
from theFeatureCodec
, reading no further in the underlying source than beyond that feature.Decode a line to obtain just its FeatureLoc for indexing -- contig, start, and stop.This function returns the object the codec generates.default String
getPathToDataFile
(String path) Codecs may override this method if the file that they recognize withcanDecode(String)
is different than the file that contains the data they parse.default TabixFormat
Define the tabix format for the feature, used for indexing.boolean
Adapter method that assesses whether the providedFeatureCodec
has more data.makeIndexableSourceFromStream
(InputStream inputStream) Return aFeatureCodec
for thisFeatureCodec
that implementsLocationAware
, and is thus suitable for use during indexing.makeSourceFromStream
(InputStream bufferedInputStream) Generates a reader of typeFeatureCodec
appropriate for use by this codec from the generic input stream.readHeader
(SOURCE source) Read and return the header, or null if there is no header.
-
Method Details
-
decodeLoc
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
Decode a singleFeature
from theFeatureCodec
, 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
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 fromFeatureCodec
as needed to parse the header, and no more. Otherwise, data that might otherwise be fed into parsing aFeature
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
Generates a reader of typeFeatureCodec
appropriate for use by this codec from the generic input stream. Implementers should assume the stream is buffered. -
makeIndexableSourceFromStream
Return aFeatureCodec
for thisFeatureCodec
that implementsLocationAware
, and is thus suitable for use during indexing. LikemakeSourceFromStream(java.io.InputStream)
, except theLocationAware
compatibility is required for creating indexes. Implementers of this method must return a type that is bothLocationAware
as well asFeatureCodec
. 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 aFeatureCodec
when applicable. NOTE: During the indexing process, the indexer passes theFeatureCodec
to the codec to consume Features from the underlyingFeatureCodec
, one at a time, recording the Feature location via theFeatureCodec
'sLocationAware
interface. Therefore, it is essential that theFeatureCodec
implementation, thereadHeader(SOURCE)
method, and thedecodeLoc(SOURCE)
method, which are used during indexing, not introduce any buffering that would that would advance theFeatureCodec
more than a single feature (or the more than the size of the header, in the case ofreadHeader(SOURCE)
). -
isDone
Adapter method that assesses whether the providedFeatureCodec
has more data. True if it does, false otherwise. -
close
Adapter method that closes the providedFeatureCodec
. -
canDecode
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
Define the tabix format for the feature, used for indexing. Default implementation throws an exception. Note that onlyAsciiFeatureCodec
could read tabix files as defined inAbstractFeatureReader.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
-
getPathToDataFile
Codecs may override this method if the file that they recognize withcanDecode(String)
is different than the file that contains the data they parse. This enables a class of codecs where the input file is a configuration that defines how to locate and handle the datafile. The default implementation returns the same path which was passed in.- Parameters:
path
- the path to a file that this codeccanDecode(java.lang.String)
- Returns:
- the path to the data file that should be parsed by this codec to produce Features.
- Throws:
TribbleException
- codecs may throw if they cannot decode the path.
-