1 /*
2 * Copyright (C) 2012, Google Inc. and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Distribution License v. 1.0 which is available at
6 * https://www.eclipse.org/org/documents/edl-v10.php.
7 *
8 * SPDX-License-Identifier: BSD-3-Clause
9 */
10
11 package org.eclipse.jgit.internal.storage.file;
12
13 import java.io.File;
14 import java.io.IOException;
15 import java.io.InputStream;
16 import java.text.MessageFormat;
17
18 import org.eclipse.jgit.errors.CorruptObjectException;
19 import org.eclipse.jgit.internal.JGitText;
20 import org.eclipse.jgit.lib.AnyObjectId;
21 import org.eclipse.jgit.lib.ObjectId;
22 import org.eclipse.jgit.util.io.SilentFileInputStream;
23
24 import com.googlecode.javaewah.EWAHCompressedBitmap;
25
26 /**
27 * Logical representation of the bitmap data stored in the pack index.
28 * {@link org.eclipse.jgit.lib.ObjectId}s are encoded as a single integer in the
29 * range [0, {@link #getObjectCount()}). Compressed bitmaps are available at
30 * certain {@code ObjectId}s, which represent all of the objects reachable from
31 * that {@code ObjectId} (include the {@code ObjectId} itself). The meaning of
32 * the positions in the bitmaps can be decoded using {@link #getObject(int)} and
33 * {@link #ofObjectType(EWAHCompressedBitmap, int)}. Furthermore,
34 * {@link #findPosition(AnyObjectId)} can be used to build other bitmaps that a
35 * compatible with the encoded bitmaps available from the index.
36 */
37 public abstract class PackBitmapIndex {
38 /** Flag bit denoting the bitmap should be reused during index creation. */
39 public static final int FLAG_REUSE = 1;
40
41 /**
42 * Read an existing pack bitmap index file from a buffered stream.
43 * <p>
44 * The format of the file will be automatically detected and a proper access
45 * implementation for that format will be constructed and returned to the
46 * caller. The file may or may not be held open by the returned instance.
47 *
48 * @param idxFile
49 * existing pack .bitmap to read.
50 * @param packIndex
51 * the pack index for the corresponding pack file.
52 * @param reverseIndex
53 * the pack reverse index for the corresponding pack file.
54 * @return a copy of the index in-memory.
55 * @throws java.io.IOException
56 * the stream cannot be read.
57 * @throws CorruptObjectException
58 * the stream does not contain a valid pack bitmap index.
59 */
60 public static PackBitmapIndex open(
61 File idxFile, PackIndex packIndex, PackReverseIndex reverseIndex)
62 throws IOException {
63 try (SilentFileInputStreamleInputStream.html#SilentFileInputStream">SilentFileInputStream fd = new SilentFileInputStream(
64 idxFile)) {
65 try {
66 return read(fd, packIndex, reverseIndex);
67 } catch (IOException ioe) {
68 throw new IOException(
69 MessageFormat.format(JGitText.get().unreadablePackIndex,
70 idxFile.getAbsolutePath()),
71 ioe);
72 }
73 }
74 }
75
76 /**
77 * Read an existing pack bitmap index file from a buffered stream.
78 * <p>
79 * The format of the file will be automatically detected and a proper access
80 * implementation for that format will be constructed and returned to the
81 * caller. The file may or may not be held open by the returned instance.
82 *
83 * @param fd
84 * stream to read the bitmap index file from. The stream must be
85 * buffered as some small IOs are performed against the stream.
86 * The caller is responsible for closing the stream.
87 * @param packIndex
88 * the pack index for the corresponding pack file.
89 * @param reverseIndex
90 * the pack reverse index for the corresponding pack file.
91 * @return a copy of the index in-memory.
92 * @throws java.io.IOException
93 * the stream cannot be read.
94 * @throws CorruptObjectException
95 * the stream does not contain a valid pack bitmap index.
96 */
97 public static PackBitmapIndex read(
98 InputStream fd, PackIndex packIndex, PackReverseIndex reverseIndex)
99 throws IOException {
100 return new PackBitmapIndexV1(fd, packIndex, reverseIndex);
101 }
102
103 /** Footer checksum applied on the bottom of the pack file. */
104 byte[] packChecksum;
105
106 /**
107 * Finds the position in the bitmap of the object.
108 *
109 * @param objectId
110 * the id for which the bitmap position will be found.
111 * @return the bitmap id or -1 if the object was not found.
112 */
113 public abstract int findPosition(AnyObjectId objectId);
114
115 /**
116 * Get the object at the bitmap position.
117 *
118 * @param position
119 * the id for which the object will be found.
120 * @return the ObjectId.
121 * @throws java.lang.IllegalArgumentException
122 * when the item is not found.
123 */
124 public abstract ObjectId getObject(int position) throws IllegalArgumentException;
125
126 /**
127 * Returns a bitmap containing positions for objects that have the given Git
128 * type.
129 *
130 * @param bitmap
131 * the object bitmap.
132 * @param type
133 * the Git type.
134 * @return the object bitmap with only objects of the Git type.
135 */
136 public abstract EWAHCompressedBitmap ofObjectType(
137 EWAHCompressedBitmap bitmap, int type);
138
139 /**
140 * Returns the previously constructed bitmap for the object.
141 *
142 * @param objectId
143 * the id for which the bitmap will be found.
144 * @return the bitmap or null if the object was not found.
145 */
146 public abstract EWAHCompressedBitmap getBitmap(AnyObjectId objectId);
147
148 /**
149 * Obtain the total number of objects described by this index.
150 * {@code getObjectCount() - 1} is the largest bit that will be set in a
151 * bitmap.
152 *
153 * @return number of objects in this index, and likewise in the associated
154 * pack that this index was generated from.
155 */
156 public abstract int getObjectCount();
157
158 /**
159 * Returns the number of bitmaps in this bitmap index.
160 *
161 * @return the number of bitmaps in this bitmap index.
162 */
163 public abstract int getBitmapCount();
164 }