1 /*
2 * Copyright (C) 2010, Google Inc.
3 * and other copyright owners as documented in the project's IP log.
4 *
5 * This program and the accompanying materials are made available
6 * under the terms of the Eclipse Distribution License v1.0 which
7 * accompanies this distribution, is reproduced below, and is
8 * available at http://www.eclipse.org/org/documents/edl-v10.php
9 *
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
14 * conditions are met:
15 *
16 * - Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * - Redistributions in binary form must reproduce the above
20 * copyright notice, this list of conditions and the following
21 * disclaimer in the documentation and/or other materials provided
22 * with the distribution.
23 *
24 * - Neither the name of the Eclipse Foundation, Inc. nor the
25 * names of its contributors may be used to endorse or promote
26 * products derived from this software without specific prior
27 * written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
30 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
32 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
34 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
35 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
36 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
37 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
38 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
41 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 */
43
44 package org.eclipse.jgit.notes;
45
46 import java.io.IOException;
47 import java.util.Iterator;
48
49 import org.eclipse.jgit.errors.CorruptObjectException;
50 import org.eclipse.jgit.errors.IncorrectObjectTypeException;
51 import org.eclipse.jgit.errors.LargeObjectException;
52 import org.eclipse.jgit.errors.MissingObjectException;
53 import org.eclipse.jgit.lib.AbbreviatedObjectId;
54 import org.eclipse.jgit.lib.AnyObjectId;
55 import org.eclipse.jgit.lib.Constants;
56 import org.eclipse.jgit.lib.MutableObjectId;
57 import org.eclipse.jgit.lib.ObjectId;
58 import org.eclipse.jgit.lib.ObjectInserter;
59 import org.eclipse.jgit.lib.ObjectReader;
60 import org.eclipse.jgit.revwalk.RevCommit;
61 import org.eclipse.jgit.revwalk.RevTree;
62
63 /**
64 * Index of notes from a note branch.
65 *
66 * This class is not thread-safe, and relies on an
67 * {@link org.eclipse.jgit.lib.ObjectReader} that it borrows/shares with the
68 * caller. The reader can be used during any call, and is not released by this
69 * class. The caller should arrange for releasing the shared
70 * {@code ObjectReader} at the proper times.
71 */
72 public class NoteMap implements Iterable<Note> {
73 /**
74 * Construct a new empty note map.
75 *
76 * @return an empty note map.
77 */
78 public static NoteMap newEmptyMap() {
79 NoteMap r = new NoteMap(null /* no reader */);
80 r.root = new LeafBucket(0);
81 return r;
82 }
83
84 /**
85 * Shorten the note ref name by trimming off the
86 * {@link org.eclipse.jgit.lib.Constants#R_NOTES} prefix if it exists.
87 *
88 * @param noteRefName
89 * a {@link java.lang.String} object.
90 * @return a more user friendly note name
91 */
92 public static String shortenRefName(String noteRefName) {
93 if (noteRefName.startsWith(Constants.R_NOTES))
94 return noteRefName.substring(Constants.R_NOTES.length());
95 return noteRefName;
96 }
97
98 /**
99 * Load a collection of notes from a branch.
100 *
101 * @param reader
102 * reader to scan the note branch with. This reader may be
103 * retained by the NoteMap for the life of the map in order to
104 * support lazy loading of entries.
105 * @param commit
106 * the revision of the note branch to read.
107 * @return the note map read from the commit.
108 * @throws java.io.IOException
109 * the repository cannot be accessed through the reader.
110 * @throws org.eclipse.jgit.errors.CorruptObjectException
111 * a tree object is corrupt and cannot be read.
112 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
113 * a tree object wasn't actually a tree.
114 * @throws org.eclipse.jgit.errors.MissingObjectException
115 * a reference tree object doesn't exist.
116 */
117 public static NoteMap read(ObjectReader reader, RevCommit commit)
118 throws MissingObjectException, IncorrectObjectTypeException,
119 CorruptObjectException, IOException {
120 return read(reader, commit.getTree());
121 }
122
123 /**
124 * Load a collection of notes from a tree.
125 *
126 * @param reader
127 * reader to scan the note branch with. This reader may be
128 * retained by the NoteMap for the life of the map in order to
129 * support lazy loading of entries.
130 * @param tree
131 * the note tree to read.
132 * @return the note map read from the tree.
133 * @throws java.io.IOException
134 * the repository cannot be accessed through the reader.
135 * @throws org.eclipse.jgit.errors.CorruptObjectException
136 * a tree object is corrupt and cannot be read.
137 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
138 * a tree object wasn't actually a tree.
139 * @throws org.eclipse.jgit.errors.MissingObjectException
140 * a reference tree object doesn't exist.
141 */
142 public static NoteMap read(ObjectReader reader, RevTree tree)
143 throws MissingObjectException, IncorrectObjectTypeException,
144 CorruptObjectException, IOException {
145 return readTree(reader, tree);
146 }
147
148 /**
149 * Load a collection of notes from a tree.
150 *
151 * @param reader
152 * reader to scan the note branch with. This reader may be
153 * retained by the NoteMap for the life of the map in order to
154 * support lazy loading of entries.
155 * @param treeId
156 * the note tree to read.
157 * @return the note map read from the tree.
158 * @throws java.io.IOException
159 * the repository cannot be accessed through the reader.
160 * @throws org.eclipse.jgit.errors.CorruptObjectException
161 * a tree object is corrupt and cannot be read.
162 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
163 * a tree object wasn't actually a tree.
164 * @throws org.eclipse.jgit.errors.MissingObjectException
165 * a reference tree object doesn't exist.
166 */
167 public static NoteMap readTree(ObjectReader reader, ObjectId treeId)
168 throws MissingObjectException, IncorrectObjectTypeException,
169 CorruptObjectException, IOException {
170 NoteMap map = new NoteMap(reader);
171 map.load(treeId);
172 return map;
173 }
174
175 /**
176 * Construct a new note map from an existing note bucket.
177 *
178 * @param root
179 * the root bucket of this note map
180 * @param reader
181 * reader to scan the note branch with. This reader may be
182 * retained by the NoteMap for the life of the map in order to
183 * support lazy loading of entries.
184 * @return the note map built from the note bucket
185 */
186 static NoteMap newMap(InMemoryNoteBucket root, ObjectReader reader) {
187 NoteMap map = new NoteMap(reader);
188 map.root = root;
189 return map;
190 }
191
192 /** Borrowed reader to access the repository. */
193 private final ObjectReader reader;
194
195 /** All of the notes that have been loaded. */
196 private InMemoryNoteBucket root;
197
198 private NoteMap(ObjectReader reader) {
199 this.reader = reader;
200 }
201
202 /** {@inheritDoc} */
203 @Override
204 public Iterator<Note> iterator() {
205 try {
206 return root.iterator(new MutableObjectId(), reader);
207 } catch (IOException e) {
208 throw new RuntimeException(e);
209 }
210 }
211
212 /**
213 * Lookup a note for a specific ObjectId.
214 *
215 * @param id
216 * the object to look for.
217 * @return the note's blob ObjectId, or null if no note exists.
218 * @throws java.io.IOException
219 * a portion of the note space is not accessible.
220 */
221 public ObjectId get(AnyObjectId id) throws IOException {
222 Note n = root.getNote(id, reader);
223 return n == null ? null : n.getData();
224 }
225
226 /**
227 * Lookup a note for a specific ObjectId.
228 *
229 * @param id
230 * the object to look for.
231 * @return the note for the given object id, or null if no note exists.
232 * @throws java.io.IOException
233 * a portion of the note space is not accessible.
234 */
235 public Note getNote(AnyObjectId id) throws IOException {
236 return root.getNote(id, reader);
237 }
238
239 /**
240 * Determine if a note exists for the specified ObjectId.
241 *
242 * @param id
243 * the object to look for.
244 * @return true if a note exists; false if there is no note.
245 * @throws java.io.IOException
246 * a portion of the note space is not accessible.
247 */
248 public boolean contains(AnyObjectId id) throws IOException {
249 return get(id) != null;
250 }
251
252 /**
253 * Open and return the content of an object's note.
254 *
255 * This method assumes the note is fairly small and can be accessed
256 * efficiently. Larger notes should be accessed by streaming:
257 *
258 * <pre>
259 * ObjectId dataId = thisMap.get(id);
260 * if (dataId != null)
261 * reader.open(dataId).openStream();
262 * </pre>
263 *
264 * @param id
265 * object to lookup the note of.
266 * @param sizeLimit
267 * maximum number of bytes to return. If the note data size is
268 * larger than this limit, LargeObjectException will be thrown.
269 * @return if a note is defined for {@code id}, the note content. If no note
270 * is defined, null.
271 * @throws org.eclipse.jgit.errors.LargeObjectException
272 * the note data is larger than {@code sizeLimit}.
273 * @throws org.eclipse.jgit.errors.MissingObjectException
274 * the note's blob does not exist in the repository.
275 * @throws java.io.IOException
276 * the note's blob cannot be read from the repository
277 */
278 public byte[] getCachedBytes(AnyObjectId id, int sizeLimit)
279 throws LargeObjectException, MissingObjectException, IOException {
280 ObjectId dataId = get(id);
281 if (dataId != null)
282 return reader.open(dataId).getCachedBytes(sizeLimit);
283 else
284 return null;
285 }
286
287 /**
288 * Attach (or remove) a note on 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 * This method only updates the map in memory.
294 *
295 * If the caller wants to attach a UTF-8 encoded string message to an
296 * object, {@link #set(AnyObjectId, String, ObjectInserter)} is a convenient
297 * way to encode and update a note in one step.
298 *
299 * @param noteOn
300 * the object to attach the note to. This same ObjectId can later
301 * be used as an argument to {@link #get(AnyObjectId)} or
302 * {@link #getCachedBytes(AnyObjectId, int)} to read back the
303 * {@code noteData}.
304 * @param noteData
305 * data to associate with the note. This must be the ObjectId of
306 * a blob that already exists in the repository. If null the note
307 * will be deleted, if present.
308 * @throws java.io.IOException
309 * a portion of the note space is not accessible.
310 */
311 public void set(AnyObjectId noteOn, ObjectId noteData) throws IOException {
312 InMemoryNoteBucket newRoot = root.set(noteOn, noteData, reader);
313 if (newRoot == null) {
314 newRoot = new LeafBucket(0);
315 newRoot.nonNotes = root.nonNotes;
316 }
317 root = newRoot;
318 }
319
320 /**
321 * Attach a note to an object.
322 *
323 * If no note exists, a new note is stored. If a note already exists for the
324 * given object, it is replaced (or removed).
325 *
326 * @param noteOn
327 * the object to attach the note to. This same ObjectId can later
328 * be used as an argument to {@link #get(AnyObjectId)} or
329 * {@link #getCachedBytes(AnyObjectId, int)} to read back the
330 * {@code noteData}.
331 * @param noteData
332 * text to store in the note. The text will be UTF-8 encoded when
333 * stored in the repository. If null the note will be deleted, if
334 * the empty string a note with the empty string will be stored.
335 * @param ins
336 * inserter to write the encoded {@code noteData} out as a blob.
337 * The caller must ensure the inserter is flushed before the
338 * updated note map is made available for reading.
339 * @throws java.io.IOException
340 * the note data could not be stored in the repository.
341 */
342 public void set(AnyObjectId noteOn, String noteData, ObjectInserter ins)
343 throws IOException {
344 ObjectId dataId;
345 if (noteData != null) {
346 byte[] dataUTF8 = Constants.encode(noteData);
347 dataId = ins.insert(Constants.OBJ_BLOB, dataUTF8);
348 } else {
349 dataId = null;
350 }
351 set(noteOn, dataId);
352 }
353
354 /**
355 * Remove a note from an object.
356 *
357 * If no note exists, no action is performed.
358 *
359 * This method only updates the map in memory.
360 *
361 * @param noteOn
362 * the object to remove the note from.
363 * @throws java.io.IOException
364 * a portion of the note space is not accessible.
365 */
366 public void remove(AnyObjectId noteOn) throws IOException {
367 set(noteOn, null);
368 }
369
370 /**
371 * Write this note map as a tree.
372 *
373 * @param inserter
374 * inserter to use when writing trees to the object database.
375 * Caller is responsible for flushing the inserter before trying
376 * to read the objects, or exposing them through a reference.
377 * @return the top level tree.
378 * @throws java.io.IOException
379 * a tree could not be written.
380 */
381 public ObjectId writeTree(ObjectInserter inserter) throws IOException {
382 return root.writeTree(inserter);
383 }
384
385 /** @return the root note bucket */
386 InMemoryNoteBucket getRoot() {
387 return root;
388 }
389
390 private void load(ObjectId rootTree) throws MissingObjectException,
391 IncorrectObjectTypeException, CorruptObjectException, IOException {
392 AbbreviatedObjectId none = AbbreviatedObjectId.fromString(""); //$NON-NLS-1$
393 root = NoteParser.parse(none, rootTree, reader);
394 }
395 }