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.lib;
12
13 import java.util.Iterator;
14
15 import org.eclipse.jgit.internal.storage.file.PackBitmapIndex;
16
17 import com.googlecode.javaewah.EWAHCompressedBitmap;
18
19 /**
20 * A compressed bitmap representation of the entire object graph.
21 *
22 * @since 3.0
23 */
24 public interface BitmapIndex {
25 /**
26 * Get the bitmap for the id. The returned bitmap is immutable and the
27 * bitwise operations return the result of the operation in a new Bitmap.
28 *
29 * @param objectId
30 * the object ID
31 * @return the Bitmap for the objectId or null, if one does not exist.
32 */
33 Bitmap getBitmap(AnyObjectId objectId);
34
35 /**
36 * Create a new {@code BitmapBuilder} based on the values in the index.
37 *
38 * @return a new {@code BitmapBuilder} based on the values in the index.
39 */
40 BitmapBuilder newBitmapBuilder();
41
42 /**
43 * A bitmap representation of ObjectIds that can be iterated to return the
44 * underlying {@code ObjectId}s or operated on with other {@code Bitmap}s.
45 */
46 public interface Bitmap extends Iterable<BitmapObject> {
47 /**
48 * Bitwise-OR the current bitmap with the value from the other
49 * bitmap.
50 *
51 * @param other
52 * the other bitmap
53 * @return a bitmap that is the bitwise-OR.
54 */
55 Bitmap or(Bitmap other);
56
57 /**
58 * Bitwise-AND-NOT the current bitmap with the value from the other
59 * bitmap.
60 *
61 * @param other
62 * the other bitmap
63 * @return a bitmap that is the bitwise-AND-NOT.
64 */
65 Bitmap andNot(Bitmap other);
66
67 /**
68 * Bitwise-XOR the current bitmap with the value from the other
69 * bitmap.
70 *
71 * @param other
72 * the other bitmap
73 * @return a bitmap that is the bitwise-XOR.
74 */
75 Bitmap xor(Bitmap other);
76
77 /**
78 * Returns an iterator over a set of elements of type BitmapObject. The
79 * BitmapObject instance is reused across calls to
80 * {@link Iterator#next()} for performance reasons.
81 *
82 * @return an Iterator.
83 */
84 @Override
85 Iterator<BitmapObject> iterator();
86
87 /**
88 * Returns the corresponding raw compressed EWAH bitmap of the bitmap.
89 *
90 * @return the corresponding {@code EWAHCompressedBitmap}
91 * @since 5.8
92 */
93 EWAHCompressedBitmap retrieveCompressed();
94 }
95
96 /**
97 * A builder for a bitmap. The bitwise operations update the builder and
98 * return a reference to the current builder.
99 */
100 public interface BitmapBuilder extends Bitmap {
101
102 /**
103 * Whether the bitmap has the id set.
104 *
105 * @param objectId
106 * the object ID
107 * @return whether the bitmap currently contains the object ID
108 */
109 boolean contains(AnyObjectId objectId);
110
111 /**
112 * Adds the id to the bitmap.
113 *
114 * @param objectId
115 * the object ID
116 * @param type
117 * the Git object type. See {@link Constants}.
118 * @return the current builder.
119 * @since 4.2
120 */
121 BitmapBuilder addObject(AnyObjectId objectId, int type);
122
123 /**
124 * Remove the id from the bitmap.
125 *
126 * @param objectId
127 * the object ID
128 */
129 void remove(AnyObjectId objectId);
130
131 /**
132 * Bitwise-OR the current bitmap with the value from the other bitmap.
133 *
134 * @param other
135 * the other bitmap
136 * @return the current builder.
137 */
138 @Override
139 BitmapBuilder or(Bitmap other);
140
141 /**
142 * Bitwise-AND-NOT the current bitmap with the value from the other
143 * bitmap.
144 *
145 * @param other
146 * the other bitmap
147 * @return the current builder.
148 */
149 @Override
150 BitmapBuilder andNot(Bitmap other);
151
152 /**
153 * Bitwise-XOR the current bitmap with the value from the other bitmap.
154 *
155 * @param other
156 * the other bitmap
157 * @return the current builder.
158 */
159 @Override
160 BitmapBuilder xor(Bitmap other);
161
162 /** @return the fully built immutable bitmap */
163 Bitmap build();
164
165 /**
166 * Determines if the entire bitmap index is contained in the bitmap. If
167 * it is, the matching bits are removed from the bitmap and true is
168 * returned. If the bitmap index is null, false is returned.
169 *
170 * @param bitmapIndex
171 * the bitmap index to check if it is completely contained
172 * inside of the current bitmap.
173 * @return {@code true} if the bitmap index was a complete match.
174 */
175 boolean removeAllOrNone(PackBitmapIndex bitmapIndex);
176
177 /** @return the number of elements in the bitmap. */
178 int cardinality();
179
180 /**
181 * Get the BitmapIndex for this BitmapBuilder.
182 *
183 * @return the BitmapIndex for this BitmapBuilder
184 *
185 * @since 4.2
186 */
187 BitmapIndex getBitmapIndex();
188 }
189 }