1 /*
2 * Copyright (C) 2010, 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.notes;
12
13 import java.io.IOException;
14 import java.util.Iterator;
15
16 import org.eclipse.jgit.errors.CorruptObjectException;
17 import org.eclipse.jgit.errors.IncorrectObjectTypeException;
18 import org.eclipse.jgit.errors.LargeObjectException;
19 import org.eclipse.jgit.errors.MissingObjectException;
20 import org.eclipse.jgit.lib.AbbreviatedObjectId;
21 import org.eclipse.jgit.lib.AnyObjectId;
22 import org.eclipse.jgit.lib.Constants;
23 import org.eclipse.jgit.lib.MutableObjectId;
24 import org.eclipse.jgit.lib.ObjectId;
25 import org.eclipse.jgit.lib.ObjectInserter;
26 import org.eclipse.jgit.lib.ObjectReader;
27 import org.eclipse.jgit.revwalk.RevCommit;
28 import org.eclipse.jgit.revwalk.RevTree;
29
30 /**
31 * Index of notes from a note branch.
32 *
33 * This class is not thread-safe, and relies on an
34 * {@link org.eclipse.jgit.lib.ObjectReader} that it borrows/shares with the
35 * caller. The reader can be used during any call, and is not released by this
36 * class. The caller should arrange for releasing the shared
37 * {@code ObjectReader} at the proper times.
38 */
39 public class NoteMap implements Iterable<Note> {
40 /**
41 * Construct a new empty note map.
42 *
43 * @return an empty note map.
44 */
45 public static NoteMap newEmptyMap() {
46 NoteMap r = new NoteMap(null /* no reader */);
47 r.root = new LeafBucket(0);
48 return r;
49 }
50
51 /**
52 * Shorten the note ref name by trimming off the
53 * {@link org.eclipse.jgit.lib.Constants#R_NOTES} prefix if it exists.
54 *
55 * @param noteRefName
56 * a {@link java.lang.String} object.
57 * @return a more user friendly note name
58 */
59 public static String shortenRefName(String noteRefName) {
60 if (noteRefName.startsWith(Constants.R_NOTES))
61 return noteRefName.substring(Constants.R_NOTES.length());
62 return noteRefName;
63 }
64
65 /**
66 * Load a collection of notes from a branch.
67 *
68 * @param reader
69 * reader to scan the note branch with. This reader may be
70 * retained by the NoteMap for the life of the map in order to
71 * support lazy loading of entries.
72 * @param commit
73 * the revision of the note branch to read.
74 * @return the note map read from the commit.
75 * @throws java.io.IOException
76 * the repository cannot be accessed through the reader.
77 * @throws org.eclipse.jgit.errors.CorruptObjectException
78 * a tree object is corrupt and cannot be read.
79 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
80 * a tree object wasn't actually a tree.
81 * @throws org.eclipse.jgit.errors.MissingObjectException
82 * a reference tree object doesn't exist.
83 */
84 public static NoteMap read(ObjectReader reader, RevCommit commit)
85 throws MissingObjectException, IncorrectObjectTypeException,
86 CorruptObjectException, IOException {
87 return read(reader, commit.getTree());
88 }
89
90 /**
91 * Load a collection of notes from a tree.
92 *
93 * @param reader
94 * reader to scan the note branch with. This reader may be
95 * retained by the NoteMap for the life of the map in order to
96 * support lazy loading of entries.
97 * @param tree
98 * the note tree to read.
99 * @return the note map read from the tree.
100 * @throws java.io.IOException
101 * the repository cannot be accessed through the reader.
102 * @throws org.eclipse.jgit.errors.CorruptObjectException
103 * a tree object is corrupt and cannot be read.
104 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
105 * a tree object wasn't actually a tree.
106 * @throws org.eclipse.jgit.errors.MissingObjectException
107 * a reference tree object doesn't exist.
108 */
109 public static NoteMap read(ObjectReader reader, RevTree tree)
110 throws MissingObjectException, IncorrectObjectTypeException,
111 CorruptObjectException, IOException {
112 return readTree(reader, tree);
113 }
114
115 /**
116 * Load a collection of notes from a tree.
117 *
118 * @param reader
119 * reader to scan the note branch with. This reader may be
120 * retained by the NoteMap for the life of the map in order to
121 * support lazy loading of entries.
122 * @param treeId
123 * the note tree to read.
124 * @return the note map read from the tree.
125 * @throws java.io.IOException
126 * the repository cannot be accessed through the reader.
127 * @throws org.eclipse.jgit.errors.CorruptObjectException
128 * a tree object is corrupt and cannot be read.
129 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
130 * a tree object wasn't actually a tree.
131 * @throws org.eclipse.jgit.errors.MissingObjectException
132 * a reference tree object doesn't exist.
133 */
134 public static NoteMap readTree(ObjectReader reader, ObjectId treeId)
135 throws MissingObjectException, IncorrectObjectTypeException,
136 CorruptObjectException, IOException {
137 NoteMap map = new NoteMap(reader);
138 map.load(treeId);
139 return map;
140 }
141
142 /**
143 * Construct a new note map from an existing note bucket.
144 *
145 * @param root
146 * the root bucket of this note map
147 * @param reader
148 * reader to scan the note branch with. This reader may be
149 * retained by the NoteMap for the life of the map in order to
150 * support lazy loading of entries.
151 * @return the note map built from the note bucket
152 */
153 static NoteMap newMap(InMemoryNoteBucket root, ObjectReader reader) {
154 NoteMap map = new NoteMap(reader);
155 map.root = root;
156 return map;
157 }
158
159 /** Borrowed reader to access the repository. */
160 private final ObjectReader reader;
161
162 /** All of the notes that have been loaded. */
163 private InMemoryNoteBucket root;
164
165 private NoteMap(ObjectReader reader) {
166 this.reader = reader;
167 }
168
169 /** {@inheritDoc} */
170 @Override
171 public Iterator<Note> iterator() {
172 try {
173 return root.iterator(new MutableObjectId(), reader);
174 } catch (IOException e) {
175 throw new RuntimeException(e);
176 }
177 }
178
179 /**
180 * Lookup a note for a specific ObjectId.
181 *
182 * @param id
183 * the object to look for.
184 * @return the note's blob ObjectId, or null if no note exists.
185 * @throws java.io.IOException
186 * a portion of the note space is not accessible.
187 */
188 public ObjectId get(AnyObjectId id) throws IOException {
189 Note n = root.getNote(id, reader);
190 return n == null ? null : n.getData();
191 }
192
193 /**
194 * Lookup a note for a specific ObjectId.
195 *
196 * @param id
197 * the object to look for.
198 * @return the note for the given object id, or null if no note exists.
199 * @throws java.io.IOException
200 * a portion of the note space is not accessible.
201 */
202 public Note getNote(AnyObjectId id) throws IOException {
203 return root.getNote(id, reader);
204 }
205
206 /**
207 * Determine if a note exists for the specified ObjectId.
208 *
209 * @param id
210 * the object to look for.
211 * @return true if a note exists; false if there is no note.
212 * @throws java.io.IOException
213 * a portion of the note space is not accessible.
214 */
215 public boolean contains(AnyObjectId id) throws IOException {
216 return get(id) != null;
217 }
218
219 /**
220 * Open and return the content of an object's note.
221 *
222 * This method assumes the note is fairly small and can be accessed
223 * efficiently. Larger notes should be accessed by streaming:
224 *
225 * <pre>
226 * ObjectId dataId = thisMap.get(id);
227 * if (dataId != null)
228 * reader.open(dataId).openStream();
229 * </pre>
230 *
231 * @param id
232 * object to lookup the note of.
233 * @param sizeLimit
234 * maximum number of bytes to return. If the note data size is
235 * larger than this limit, LargeObjectException will be thrown.
236 * @return if a note is defined for {@code id}, the note content. If no note
237 * is defined, null.
238 * @throws org.eclipse.jgit.errors.LargeObjectException
239 * the note data is larger than {@code sizeLimit}.
240 * @throws org.eclipse.jgit.errors.MissingObjectException
241 * the note's blob does not exist in the repository.
242 * @throws java.io.IOException
243 * the note's blob cannot be read from the repository
244 */
245 public byte[] getCachedBytes(AnyObjectId id, int sizeLimit)
246 throws LargeObjectException, MissingObjectException, IOException {
247 ObjectId dataId = get(id);
248 if (dataId != null) {
249 return reader.open(dataId).getCachedBytes(sizeLimit);
250 }
251 return null;
252 }
253
254 /**
255 * Attach (or remove) a note on an object.
256 *
257 * If no note exists, a new note is stored. If a note already exists for the
258 * given object, it is replaced (or removed).
259 *
260 * This method only updates the map in memory.
261 *
262 * If the caller wants to attach a UTF-8 encoded string message to an
263 * object, {@link #set(AnyObjectId, String, ObjectInserter)} is a convenient
264 * way to encode and update a note in one step.
265 *
266 * @param noteOn
267 * the object to attach the note to. This same ObjectId can later
268 * be used as an argument to {@link #get(AnyObjectId)} or
269 * {@link #getCachedBytes(AnyObjectId, int)} to read back the
270 * {@code noteData}.
271 * @param noteData
272 * data to associate with the note. This must be the ObjectId of
273 * a blob that already exists in the repository. If null the note
274 * will be deleted, if present.
275 * @throws java.io.IOException
276 * a portion of the note space is not accessible.
277 */
278 public void set(AnyObjectId noteOn, ObjectId noteData) throws IOException {
279 InMemoryNoteBucket newRoot = root.set(noteOn, noteData, reader);
280 if (newRoot == null) {
281 newRoot = new LeafBucket(0);
282 newRoot.nonNotes = root.nonNotes;
283 }
284 root = newRoot;
285 }
286
287 /**
288 * Attach a note to an object.
289 *
290 * If no note exists, a new note is stored. If a note already exists for the
291 * given object, it is replaced (or removed).
292 *
293 * @param noteOn
294 * the object to attach the note to. This same ObjectId can later
295 * be used as an argument to {@link #get(AnyObjectId)} or
296 * {@link #getCachedBytes(AnyObjectId, int)} to read back the
297 * {@code noteData}.
298 * @param noteData
299 * text to store in the note. The text will be UTF-8 encoded when
300 * stored in the repository. If null the note will be deleted, if
301 * the empty string a note with the empty string will be stored.
302 * @param ins
303 * inserter to write the encoded {@code noteData} out as a blob.
304 * The caller must ensure the inserter is flushed before the
305 * updated note map is made available for reading.
306 * @throws java.io.IOException
307 * the note data could not be stored in the repository.
308 */
309 public void set(AnyObjectId noteOn, String noteData, ObjectInserter ins)
310 throws IOException {
311 ObjectId dataId;
312 if (noteData != null) {
313 byte[] dataUTF8 = Constants.encode(noteData);
314 dataId = ins.insert(Constants.OBJ_BLOB, dataUTF8);
315 } else {
316 dataId = null;
317 }
318 set(noteOn, dataId);
319 }
320
321 /**
322 * Remove a note from an object.
323 *
324 * If no note exists, no action is performed.
325 *
326 * This method only updates the map in memory.
327 *
328 * @param noteOn
329 * the object to remove the note from.
330 * @throws java.io.IOException
331 * a portion of the note space is not accessible.
332 */
333 public void remove(AnyObjectId noteOn) throws IOException {
334 set(noteOn, null);
335 }
336
337 /**
338 * Write this note map as a tree.
339 *
340 * @param inserter
341 * inserter to use when writing trees to the object database.
342 * Caller is responsible for flushing the inserter before trying
343 * to read the objects, or exposing them through a reference.
344 * @return the top level tree.
345 * @throws java.io.IOException
346 * a tree could not be written.
347 */
348 public ObjectId writeTree(ObjectInserter inserter) throws IOException {
349 return root.writeTree(inserter);
350 }
351
352 /** @return the root note bucket */
353 InMemoryNoteBucket getRoot() {
354 return root;
355 }
356
357 private void load(ObjectId rootTree) throws MissingObjectException,
358 IncorrectObjectTypeException, CorruptObjectException, IOException {
359 AbbreviatedObjectId none = AbbreviatedObjectId.fromString(""); //$NON-NLS-1$
360 root = NoteParser.parse(none, rootTree, reader);
361 }
362 }