View Javadoc
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 }