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