Class GZIIndex


  • public final class GZIIndex
    extends Object
    Represents a .gzi index of a block-compressed file.

    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:
    https://github.com/samtools/htslib/issues/473
    • Method Detail

      • getNumberOfBlocks

        public int getNumberOfBlocks()
        Gets the number of blocks on the file.
        Returns:
        the number of blocks.
      • getIndexEntries

        public List<GZIIndex.IndexEntry> 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.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • writeIndex

        public void writeIndex​(Path output)
                        throws IOException
        Writes this index into the requested path.
        Parameters:
        output - the output path.
        Throws:
        IOException - if an I/O error occurs.
      • writeIndex

        public void writeIndex​(OutputStream output)
                        throws IOException
        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

        public static final GZIIndex loadIndex​(Path indexPath)
                                        throws IOException
        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

        public static final GZIIndex loadIndex​(String source,
                                               InputStream indexIn)
                                        throws IOException
        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

        public static final GZIIndex buildIndex​(Path bgzipFile)
                                         throws IOException
        Builds a GZIIndex 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

        public static GZIIndex createIndex​(Path bgzipFile,
                                           boolean overwrite)
                                    throws IOException
        Creates a GZIIndex 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 if true; otherwise, throws a IOException.
        Returns:
        the in-memory representation for the created index.
        Throws:
        IOException - if an IO error occurs.
      • resolveIndexNameForBgzipFile

        public static Path resolveIndexNameForBgzipFile​(Path bgzipFile)
        Gets the default index path for the bgzip file.