Class GZIIndex
The .gzi index is a mapping between the offset of each block in the gzipped file and the
uncompressed offset that that block starts with. This mapping is represented by GZIIndex.IndexEntry
.
An example of usage for this index for random access a bgzip file using an index generated
from raw data. For example, for indexing a compressed FASTA file the .gzi index can be used in
conjunction with the FastaSequenceIndex
to seek concrete
sequences.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Helper class for constructing the GZIindex.static final class
Index entry mapping the block-offset (compressed offset) to the uncompressed offset where the block starts. -
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionstatic final GZIIndex
buildIndex
(Path bgzipFile) Builds aGZIIndex
on the fly from a BGZIP file.static GZIIndex
createIndex
(Path bgzipFile, boolean overwrite) Creates aGZIIndex
from a BGZIP file and store it in memory and disk.boolean
Gets an unmodifiable list with the index entries.int
Gets the number of blocks on the file.long
getVirtualOffsetForSeek
(long uncompressedOffset) Gets the virtual offset for seek withBlockCompressedInputStream.seek(long)
.int
hashCode()
static final GZIIndex
loadIndex
(String source, InputStream indexIn) Loads the index from the provided input stream.static final GZIIndex
loadIndex
(String source, ReadableByteChannel channel) Loads the index from the provided channel.static final GZIIndex
Loads the index from the provided file.static Path
resolveIndexNameForBgzipFile
(Path bgzipFile) Gets the default index path for the bgzip file.toString()
void
writeIndex
(OutputStream output) Writes this index into the requested path.void
writeIndex
(Path output) Writes this index into the requested path.
-
Field Details
-
DEFAULT_EXTENSION
Deprecated.since June 2019 UseFileExtensions.GZI
instead.- See Also:
-
-
Method Details
-
getNumberOfBlocks
public int getNumberOfBlocks()Gets the number of blocks on the file.- Returns:
- the number of blocks.
-
getIndexEntries
Gets an unmodifiable list with the index entries.Note: because the first block corresponds to a dummy index entry (0, 0), the returned list does not include it. Thus, the size of the list is
getNumberOfBlocks() - 1
.- Returns:
- index entries.
-
getVirtualOffsetForSeek
public long getVirtualOffsetForSeek(long uncompressedOffset) Gets the virtual offset for seek withBlockCompressedInputStream.seek(long)
.BlockCompressedInputStream.seek(long)
parameter is not a byte-offset, but a special virtual file pointer that specifies the block-offset within the file (BlockCompressedFilePointerUtil.getBlockAddress(long)
), and the offset within the block (BlockCompressedFilePointerUtil.getBlockOffset(long)
).This methods converts the provided byte-offset on the file to the special file pointer used to seek a block-compressed file, using this index to find the block where the byte-offset is located.
- Parameters:
uncompressedOffset
- the file-offset.- Returns:
- virtual offset for
BlockCompressedInputStream
. - See Also:
-
equals
-
hashCode
public int hashCode() -
toString
-
writeIndex
Writes this index into the requested path.- Parameters:
output
- the output path.- Throws:
IOException
- if an I/O error occurs.
-
writeIndex
Writes this index into the requested path. NOTE: This method will close out the provided output stream when it finishes writing the index- Parameters:
output
- the output file.- Throws:
IOException
- if an I/O error occurs.
-
loadIndex
Loads the index from the provided file.- Parameters:
indexPath
- the path for the index to load.- Returns:
- loaded index.
- Throws:
IOException
- if an I/O error occurs.
-
loadIndex
Loads the index from the provided input stream.- Parameters:
source
- The named source of the reference file (used in error messages). May be null if unknown.indexIn
- the input stream for the index to load.- Returns:
- loaded index.
- Throws:
IOException
- if an I/O error occurs.
-
loadIndex
public static final GZIIndex loadIndex(String source, ReadableByteChannel channel) throws IOException Loads the index from the provided channel.- Parameters:
source
- The named source of the reference file (used in error messages). May be null if unknown.channel
- the channel to read the index from.- Returns:
- loaded index.
- Throws:
IOException
- if an I/O error occurs.
-
buildIndex
Builds aGZIIndex
on the fly from a BGZIP file.Note that this method does not write the index on disk. Use
writeIndex(OutputStream)
on the returned object to save the index.- Parameters:
bgzipFile
- the bgzip file.- Returns:
- in-memory .gzi index.
- Throws:
IOException
- if an I/O error occurs.
-
createIndex
Creates aGZIIndex
from a BGZIP file and store it in memory and disk.- Parameters:
bgzipFile
- the bgzip file.overwrite
- if the .fai index already exists override it iftrue
; otherwise, throws aIOException
.- Returns:
- the in-memory representation for the created index.
- Throws:
IOException
- if an IO error occurs.
-
resolveIndexNameForBgzipFile
Gets the default index path for the bgzip file.
-
FileExtensions.GZI
instead.