/*
 * Copyright (C) 2012, Google Inc. and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0 which is available at
 * https://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.eclipse.jgit.internal.storage.file;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.text.MessageFormat;

import org.eclipse.jgit.errors.CorruptObjectException;
import org.eclipse.jgit.internal.JGitText;
import org.eclipse.jgit.lib.AnyObjectId;
import org.eclipse.jgit.lib.ObjectId;
import org.eclipse.jgit.util.io.SilentFileInputStream;

import com.googlecode.javaewah.EWAHCompressedBitmap;

Logical representation of the bitmap data stored in the pack index. ObjectIds are encoded as a single integer in the range [0, getObjectCount()). Compressed bitmaps are available at certain ObjectIds, which represent all of the objects reachable from that ObjectId (include the ObjectId itself). The meaning of the positions in the bitmaps can be decoded using getObject(int) and ofObjectType(EWAHCompressedBitmap, int). Furthermore, findPosition(AnyObjectId) can be used to build other bitmaps that a compatible with the encoded bitmaps available from the index. /**
 * Logical representation of the bitmap data stored in the pack index.
 * {@link org.eclipse.jgit.lib.ObjectId}s are encoded as a single integer in the
 * range [0, {@link #getObjectCount()}). Compressed bitmaps are available at
 * certain {@code ObjectId}s, which represent all of the objects reachable from
 * that {@code ObjectId} (include the {@code ObjectId} itself). The meaning of
 * the positions in the bitmaps can be decoded using {@link #getObject(int)} and
 * {@link #ofObjectType(EWAHCompressedBitmap, int)}. Furthermore,
 * {@link #findPosition(AnyObjectId)} can be used to build other bitmaps that a
 * compatible with the encoded bitmaps available from the index.
 */
public abstract class PackBitmapIndex {
	
Flag bit denoting the bitmap should be reused during index creation. /** Flag bit denoting the bitmap should be reused during index creation. */
	public static final int FLAG_REUSE = 1;

	
Read an existing pack bitmap index file from a buffered stream.

The format of the file will be automatically detected and a proper access
implementation for that format will be constructed and returned to the
caller. The file may or may not be held open by the returned instance.
Params:
idxFile – 
           existing pack .bitmap to read.
packIndex – 
           the pack index for the corresponding pack file.
reverseIndex – 
           the pack reverse index for the corresponding pack file.
Throws:
IOException – 
            the stream cannot be read.
CorruptObjectException – 
            the stream does not contain a valid pack bitmap index.
Returns:
a copy of the index in-memory./**
	 * Read an existing pack bitmap index file from a buffered stream.
	 * <p>
	 * The format of the file will be automatically detected and a proper access
	 * implementation for that format will be constructed and returned to the
	 * caller. The file may or may not be held open by the returned instance.
	 *
	 * @param idxFile
	 *            existing pack .bitmap to read.
	 * @param packIndex
	 *            the pack index for the corresponding pack file.
	 * @param reverseIndex
	 *            the pack reverse index for the corresponding pack file.
	 * @return a copy of the index in-memory.
	 * @throws java.io.IOException
	 *             the stream cannot be read.
	 * @throws CorruptObjectException
	 *             the stream does not contain a valid pack bitmap index.
	 */
	public static PackBitmapIndex open(
			File idxFile, PackIndex packIndex, PackReverseIndex reverseIndex)
			throws IOException {
		try (SilentFileInputStream fd = new SilentFileInputStream(
				idxFile)) {
			try {
				return read(fd, packIndex, reverseIndex);
			} catch (IOException ioe) {
				throw new IOException(
						MessageFormat.format(JGitText.get().unreadablePackIndex,
								idxFile.getAbsolutePath()),
						ioe);
			}
		}
	}

	
Read an existing pack bitmap index file from a buffered stream.

The format of the file will be automatically detected and a proper access
implementation for that format will be constructed and returned to the
caller. The file may or may not be held open by the returned instance.
Params:
fd – 
           stream to read the bitmap index file from. The stream must be
           buffered as some small IOs are performed against the stream.
           The caller is responsible for closing the stream.
packIndex – 
           the pack index for the corresponding pack file.
reverseIndex – 
           the pack reverse index for the corresponding pack file.
Throws:
IOException – 
            the stream cannot be read.
CorruptObjectException – 
            the stream does not contain a valid pack bitmap index.
Returns:
a copy of the index in-memory./**
	 * Read an existing pack bitmap index file from a buffered stream.
	 * <p>
	 * The format of the file will be automatically detected and a proper access
	 * implementation for that format will be constructed and returned to the
	 * caller. The file may or may not be held open by the returned instance.
	 *
	 * @param fd
	 *            stream to read the bitmap index file from. The stream must be
	 *            buffered as some small IOs are performed against the stream.
	 *            The caller is responsible for closing the stream.
	 * @param packIndex
	 *            the pack index for the corresponding pack file.
	 * @param reverseIndex
	 *            the pack reverse index for the corresponding pack file.
	 * @return a copy of the index in-memory.
	 * @throws java.io.IOException
	 *             the stream cannot be read.
	 * @throws CorruptObjectException
	 *             the stream does not contain a valid pack bitmap index.
	 */
	public static PackBitmapIndex read(
			InputStream fd, PackIndex packIndex, PackReverseIndex reverseIndex)
			throws IOException {
		return new PackBitmapIndexV1(fd, packIndex, reverseIndex);
	}

	
Footer checksum applied on the bottom of the pack file. /** Footer checksum applied on the bottom of the pack file. */
	byte[] packChecksum;

	
Finds the position in the bitmap of the object.
Params:
objectId – 
           the id for which the bitmap position will be found.
Returns:
the bitmap id or -1 if the object was not found./**
	 * Finds the position in the bitmap of the object.
	 *
	 * @param objectId
	 *            the id for which the bitmap position will be found.
	 * @return the bitmap id or -1 if the object was not found.
	 */
	public abstract int findPosition(AnyObjectId objectId);

	
Get the object at the bitmap position.
Params:
position – 
           the id for which the object will be found.
Throws:
IllegalArgumentException – 
            when the item is not found.
Returns:
the ObjectId./**
	 * Get the object at the bitmap position.
	 *
	 * @param position
	 *            the id for which the object will be found.
	 * @return the ObjectId.
	 * @throws java.lang.IllegalArgumentException
	 *             when the item is not found.
	 */
	public abstract ObjectId getObject(int position) throws IllegalArgumentException;

	
Returns a bitmap containing positions for objects that have the given Git
type.
Params:
bitmap – 
           the object bitmap.
type – 
           the Git type.
Returns:
the object bitmap with only objects of the Git type./**
	 * Returns a bitmap containing positions for objects that have the given Git
	 * type.
	 *
	 * @param bitmap
	 *            the object bitmap.
	 * @param type
	 *            the Git type.
	 * @return the object bitmap with only objects of the Git type.
	 */
	public abstract EWAHCompressedBitmap ofObjectType(
			EWAHCompressedBitmap bitmap, int type);

	
Returns the previously constructed bitmap for the object.
Params:
objectId – 
           the id for which the bitmap will be found.
Returns:
the bitmap or null if the object was not found./**
	 * Returns the previously constructed bitmap for the object.
	 *
	 * @param objectId
	 *            the id for which the bitmap will be found.
	 * @return the bitmap or null if the object was not found.
	 */
	public abstract EWAHCompressedBitmap getBitmap(AnyObjectId objectId);

	
Obtain the total number of objects described by this index. getObjectCount() - 1 is the largest bit that will be set in a bitmap. 
Returns:
number of objects in this index, and likewise in the associated
        pack that this index was generated from./**
	 * Obtain the total number of objects described by this index.
	 * {@code getObjectCount() - 1} is the largest bit that will be set in a
	 * bitmap.
	 *
	 * @return number of objects in this index, and likewise in the associated
	 *         pack that this index was generated from.
	 */
	public abstract int getObjectCount();

	
Returns the number of bitmaps in this bitmap index.
Returns:
the number of bitmaps in this bitmap index./**
	 * Returns the number of bitmaps in this bitmap index.
	 *
	 * @return the number of bitmaps in this bitmap index.
	 */
	public abstract int getBitmapCount();
}