FEATURE_TYPE
- The type of Feature
this codec generatesSOURCE
- The type of the data source this codec reads fromAbstractFeatureCodec
, AbstractVCFCodec
, AsciiFeatureCodec
, BCF2Codec
, BEDCodec
, BinaryFeatureCodec
, ExampleBinaryCodec
, VCF3Codec
, VCFCodec
public interface FeatureCodec<FEATURE_TYPE extends Feature,SOURCE>
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.
FeatureCodec
within the codec. There's no guarantee about its
state between calls.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.
|
Feature decodeLoc(SOURCE source) throws IOException
source
- the input stream from which to decode the next recordIOException
FEATURE_TYPE decode(SOURCE source) throws IOException
Feature
from the FeatureCodec
, reading no further in the underlying source than beyond that feature.source
- the input stream from which to decode the next recordIOException
FeatureCodecHeader readHeader(SOURCE source) throws IOException
FeatureCodec
as needed to parse the header, and no
more. Otherwise, data that might otherwise be fed into parsing a Feature
may be lost.source
- the source from which to decode the headerIOException
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
SOURCE makeSourceFromStream(InputStream bufferedInputStream)
FeatureCodec
appropriate for use by this codec from the generic input stream. Implementers should
assume the stream is buffered.LocationAware makeIndexableSourceFromStream(InputStream inputStream)
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)
).boolean isDone(SOURCE source)
FeatureCodec
has more data. True if it does, false otherwise.void close(SOURCE source)
FeatureCodec
.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.path
- the file to test for parsability with this codecdefault TabixFormat getTabixFormat()
AsciiFeatureCodec
could read tabix files as defined in
AbstractFeatureReader.getFeatureReader(String, String, FeatureCodec, boolean, java.util.function.Function, java.util.function.Function)
TribbleException
- if the format is not defined