Browse Source

Fix javadoc in org.eclipse.jgit revwalk package

Change-Id: I3fabab8afa284b1919ab7bc656cab19e56ed474e
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
stable-4.10
Matthias Sohn 7 years ago
parent
commit
0cba440277
  1. 16
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AbstractRevQueue.java
  2. 4
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AsyncRevObjectQueue.java
  3. 22
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BitmapWalker.java
  4. 9
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BlockRevQueue.java
  5. 12
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DateRevQueue.java
  6. 21
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DepthWalk.java
  7. 12
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FIFORevQueue.java
  8. 16
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FollowFilter.java
  9. 11
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterKey.java
  10. 7
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterLine.java
  11. 12
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/LIFORevQueue.java
  12. 101
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/ObjectWalk.java
  13. 5
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RenameCallback.java
  14. 5
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevBlob.java
  15. 31
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommit.java
  16. 39
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommitList.java
  17. 6
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlag.java
  18. 13
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlagSet.java
  19. 9
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObject.java
  20. 11
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObjectList.java
  21. 5
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevSort.java
  22. 27
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTag.java
  23. 5
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTree.java
  24. 166
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java
  25. 38
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalkUtils.java
  26. 18
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/TreeRevFilter.java
  27. 7
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AndRevFilter.java
  28. 4
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AuthorRevFilter.java
  29. 6
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitTimeRevFilter.java
  30. 4
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitterRevFilter.java
  31. 2
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MaxCountRevFilter.java
  32. 4
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MessageRevFilter.java
  33. 9
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/NotRevFilter.java
  34. 9
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/ObjectFilter.java
  35. 7
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/OrRevFilter.java
  36. 12
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/PatternMatchRevFilter.java
  37. 37
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFilter.java
  38. 6
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFlagFilter.java
  39. 2
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SkipRevFilter.java
  40. 11
      org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SubStringRevFilter.java

16
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AbstractRevQueue.java

@ -103,14 +103,16 @@ abstract class AbstractRevQueue extends Generator {
} }
/** /**
* {@inheritDoc}
* <p>
* Remove the first commit from the queue. * Remove the first commit from the queue.
*
* @return the first commit of this queue.
*/ */
@Override @Override
public abstract RevCommit next(); public abstract RevCommit next();
/** Remove all entries from this queue. */ /**
* Remove all entries from this queue.
*/
public abstract void clear(); public abstract void clear();
abstract boolean everbodyHasFlag(int f); abstract boolean everbodyHasFlag(int f);
@ -122,6 +124,14 @@ abstract class AbstractRevQueue extends Generator {
return outputType; return outputType;
} }
/**
* Describe this queue
*
* @param s
* a StringBuilder
* @param c
* a {@link org.eclipse.jgit.revwalk.RevCommit}
*/
protected static void describe(final StringBuilder s, final RevCommit c) { protected static void describe(final StringBuilder s, final RevCommit c) {
s.append(c.toString()); s.append(c.toString());
s.append('\n'); s.append('\n');

4
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AsyncRevObjectQueue.java

@ -59,11 +59,11 @@ public interface AsyncRevObjectQueue extends AsyncOperation {
* Obtain the next object. * Obtain the next object.
* *
* @return the object; null if there are no more objects remaining. * @return the object; null if there are no more objects remaining.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the object does not exist. There may be more objects * the object does not exist. There may be more objects
* remaining in the iteration, the application should call * remaining in the iteration, the application should call
* {@link #next()} again. * {@link #next()} again.
* @throws IOException * @throws java.io.IOException
* the object store cannot be accessed. * the object store cannot be accessed.
*/ */
public RevObject next() throws MissingObjectException, IOException; public RevObject next() throws MissingObjectException, IOException;

22
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BitmapWalker.java

@ -102,21 +102,27 @@ public final class BitmapWalker {
/** /**
* Return, as a bitmap, the objects reachable from the objects in start. * Return, as a bitmap, the objects reachable from the objects in start.
* *
* @param start the objects to start the object traversal from. * @param start
* @param seen the objects to skip if encountered during traversal. * the objects to start the object traversal from.
* @param ignoreMissing true to ignore missing objects, false otherwise. * @param seen
* the objects to skip if encountered during traversal.
* @param ignoreMissing
* true to ignore missing objects, false otherwise.
* @return as a bitmap, the objects reachable from the objects in start. * @return as a bitmap, the objects reachable from the objects in start.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the object supplied is not available from the object * the object supplied is not available from the object
* database. This usually indicates the supplied object is * database. This usually indicates the supplied object is
* invalid, but the reference was constructed during an earlier * invalid, but the reference was constructed during an earlier
* invocation to {@link RevWalk#lookupAny(AnyObjectId, int)}. * invocation to
* @throws IncorrectObjectTypeException * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}.
* @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the object was not parsed yet and it was discovered during * the object was not parsed yet and it was discovered during
* parsing that it is not actually the type of the instance * parsing that it is not actually the type of the instance
* passed in. This usually indicates the caller used the wrong * passed in. This usually indicates the caller used the wrong
* type in a {@link RevWalk#lookupAny(AnyObjectId, int)} call. * type in a
* @throws IOException * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}
* call.
* @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public BitmapBuilder findObjects(Iterable<? extends ObjectId> start, BitmapBuilder seen, public BitmapBuilder findObjects(Iterable<? extends ObjectId> start, BitmapBuilder seen,

9
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BlockRevQueue.java

@ -51,7 +51,9 @@ import org.eclipse.jgit.errors.MissingObjectException;
abstract class BlockRevQueue extends AbstractRevQueue { abstract class BlockRevQueue extends AbstractRevQueue {
protected BlockFreeList free; protected BlockFreeList free;
/** Create an empty revision queue. */ /**
* Create an empty revision queue.
*/
protected BlockRevQueue() { protected BlockRevQueue() {
free = new BlockFreeList(); free = new BlockFreeList();
} }
@ -70,6 +72,8 @@ abstract class BlockRevQueue extends AbstractRevQueue {
} }
/** /**
* {@inheritDoc}
* <p>
* Reconfigure this queue to share the same free list as another. * Reconfigure this queue to share the same free list as another.
* <p> * <p>
* Multiple revision queues can be connected to the same free list, making * Multiple revision queues can be connected to the same free list, making
@ -79,9 +83,6 @@ abstract class BlockRevQueue extends AbstractRevQueue {
* <p> * <p>
* Free lists are not thread-safe. Applications must ensure that all queues * Free lists are not thread-safe. Applications must ensure that all queues
* sharing the same free list are doing so from only a single thread. * sharing the same free list are doing so from only a single thread.
*
* @param q
* the other queue we will steal entries from.
*/ */
@Override @Override
public void shareFreeList(final BlockRevQueue q) { public void shareFreeList(final BlockRevQueue q) {

12
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DateRevQueue.java

@ -49,7 +49,9 @@ import java.io.IOException;
import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.IncorrectObjectTypeException;
import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.errors.MissingObjectException;
/** A queue of commits sorted by commit time order. */ /**
* A queue of commits sorted by commit time order.
*/
public class DateRevQueue extends AbstractRevQueue { public class DateRevQueue extends AbstractRevQueue {
private static final int REBUILD_INDEX_COUNT = 1000; private static final int REBUILD_INDEX_COUNT = 1000;
@ -67,7 +69,9 @@ public class DateRevQueue extends AbstractRevQueue {
private int last = -1; private int last = -1;
/** Create an empty date queue. */ /**
* Create an empty date queue.
*/
public DateRevQueue() { public DateRevQueue() {
super(); super();
} }
@ -82,6 +86,7 @@ public class DateRevQueue extends AbstractRevQueue {
} }
} }
/** {@inheritDoc} */
@Override @Override
public void add(final RevCommit c) { public void add(final RevCommit c) {
sinceLastIndex++; sinceLastIndex++;
@ -127,6 +132,7 @@ public class DateRevQueue extends AbstractRevQueue {
} }
} }
/** {@inheritDoc} */
@Override @Override
public RevCommit next() { public RevCommit next() {
final Entry q = head; final Entry q = head;
@ -163,6 +169,7 @@ public class DateRevQueue extends AbstractRevQueue {
return head != null ? head.commit : null; return head != null ? head.commit : null;
} }
/** {@inheritDoc} */
@Override @Override
public void clear() { public void clear() {
head = null; head = null;
@ -196,6 +203,7 @@ public class DateRevQueue extends AbstractRevQueue {
return outputType | SORT_COMMIT_TIME_DESC; return outputType | SORT_COMMIT_TIME_DESC;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder s = new StringBuilder(); final StringBuilder s = new StringBuilder();

21
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DepthWalk.java

@ -52,15 +52,30 @@ import org.eclipse.jgit.lib.AnyObjectId;
import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ObjectReader;
import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.lib.Repository;
/** Interface for revision walkers that perform depth filtering. */ /**
* Interface for revision walkers that perform depth filtering.
*/
public interface DepthWalk { public interface DepthWalk {
/** @return Depth to filter to. */ /**
* Get depth to filter to.
*
* @return Depth to filter to.
*/
public int getDepth(); public int getDepth();
/** @return flag marking commits that should become unshallow. */ /** @return flag marking commits that should become unshallow. */
/**
* Get flag marking commits that should become unshallow.
*
* @return flag marking commits that should become unshallow.
*/
public RevFlag getUnshallowFlag(); public RevFlag getUnshallowFlag();
/** @return flag marking commits that are interesting again. */ /**
* Get flag marking commits that are interesting again.
*
* @return flag marking commits that are interesting again.
*/
public RevFlag getReinterestingFlag(); public RevFlag getReinterestingFlag();
/** RevCommit with a depth (in commits) from a root. */ /** RevCommit with a depth (in commits) from a root. */

12
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FIFORevQueue.java

@ -48,13 +48,17 @@ import java.io.IOException;
import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.IncorrectObjectTypeException;
import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.errors.MissingObjectException;
/** A queue of commits in FIFO order. */ /**
* A queue of commits in FIFO order.
*/
public class FIFORevQueue extends BlockRevQueue { public class FIFORevQueue extends BlockRevQueue {
private Block head; private Block head;
private Block tail; private Block tail;
/** Create an empty FIFO queue. */ /**
* Create an empty FIFO queue.
*/
public FIFORevQueue() { public FIFORevQueue() {
super(); super();
} }
@ -64,6 +68,7 @@ public class FIFORevQueue extends BlockRevQueue {
super(s); super(s);
} }
/** {@inheritDoc} */
@Override @Override
public void add(final RevCommit c) { public void add(final RevCommit c) {
Block b = tail; Block b = tail;
@ -108,6 +113,7 @@ public class FIFORevQueue extends BlockRevQueue {
head = b; head = b;
} }
/** {@inheritDoc} */
@Override @Override
public RevCommit next() { public RevCommit next() {
final Block b = head; final Block b = head;
@ -124,6 +130,7 @@ public class FIFORevQueue extends BlockRevQueue {
return c; return c;
} }
/** {@inheritDoc} */
@Override @Override
public void clear() { public void clear() {
head = null; head = null;
@ -159,6 +166,7 @@ public class FIFORevQueue extends BlockRevQueue {
} }
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder s = new StringBuilder(); final StringBuilder s = new StringBuilder();

16
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FollowFilter.java

@ -59,7 +59,8 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter;
* triggers rename detection so that the path node is updated to include a prior * triggers rename detection so that the path node is updated to include a prior
* file name as the RevWalk traverses history. * file name as the RevWalk traverses history.
* *
* The renames found will be reported to a {@link RenameCallback} if one is set. * The renames found will be reported to a
* {@link org.eclipse.jgit.revwalk.RenameCallback} if one is set.
* <p> * <p>
* Results with this filter are unpredictable if the path being followed is a * Results with this filter are unpredictable if the path being followed is a
* subdirectory. * subdirectory.
@ -81,7 +82,7 @@ public class FollowFilter extends TreeFilter {
* @param cfg * @param cfg
* diff config specifying rename detection options. * diff config specifying rename detection options.
* @return a new filter for the requested path. * @return a new filter for the requested path.
* @throws IllegalArgumentException * @throws java.lang.IllegalArgumentException
* the path supplied was the empty string. * the path supplied was the empty string.
* @since 3.0 * @since 3.0
*/ */
@ -100,10 +101,16 @@ public class FollowFilter extends TreeFilter {
} }
/** @return the path this filter matches. */ /** @return the path this filter matches. */
/**
* Get the path this filter matches.
*
* @return the path this filter matches.
*/
public String getPath() { public String getPath() {
return path.getPath(); return path.getPath();
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(final TreeWalk walker) public boolean include(final TreeWalk walker)
throws MissingObjectException, IncorrectObjectTypeException, throws MissingObjectException, IncorrectObjectTypeException,
@ -111,16 +118,19 @@ public class FollowFilter extends TreeFilter {
return path.include(walker) && ANY_DIFF.include(walker); return path.include(walker) && ANY_DIFF.include(walker);
} }
/** {@inheritDoc} */
@Override @Override
public boolean shouldBeRecursive() { public boolean shouldBeRecursive() {
return path.shouldBeRecursive() || ANY_DIFF.shouldBeRecursive(); return path.shouldBeRecursive() || ANY_DIFF.shouldBeRecursive();
} }
/** {@inheritDoc} */
@Override @Override
public TreeFilter clone() { public TreeFilter clone() {
return new FollowFilter(path.clone(), cfg); return new FollowFilter(path.clone(), cfg);
} }
/** {@inheritDoc} */
@SuppressWarnings("nls") @SuppressWarnings("nls")
@Override @Override
public String toString() { public String toString() {
@ -130,6 +140,8 @@ public class FollowFilter extends TreeFilter {
} }
/** /**
* Get the callback to which renames are reported.
*
* @return the callback to which renames are reported, or <code>null</code> * @return the callback to which renames are reported, or <code>null</code>
* if none * if none
*/ */

11
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterKey.java

@ -47,7 +47,9 @@ import java.util.Locale;
import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Constants;
/** Case insensitive key for a {@link FooterLine}. */ /**
* Case insensitive key for a {@link org.eclipse.jgit.revwalk.FooterLine}.
*/
public final class FooterKey { public final class FooterKey {
/** Standard {@code Signed-off-by} */ /** Standard {@code Signed-off-by} */
public static final FooterKey SIGNED_OFF_BY = new FooterKey("Signed-off-by"); //$NON-NLS-1$ public static final FooterKey SIGNED_OFF_BY = new FooterKey("Signed-off-by"); //$NON-NLS-1$
@ -73,11 +75,16 @@ public final class FooterKey {
raw = Constants.encode(keyName.toLowerCase(Locale.ROOT)); raw = Constants.encode(keyName.toLowerCase(Locale.ROOT));
} }
/** @return name of this footer line. */ /**
* Get name of this footer line.
*
* @return name of this footer line.
*/
public String getName() { public String getName() {
return name; return name;
} }
/** {@inheritDoc} */
@SuppressWarnings("nls") @SuppressWarnings("nls")
@Override @Override
public String toString() { public String toString() {

7
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterLine.java

@ -80,6 +80,8 @@ public final class FooterLine {
} }
/** /**
* Whether keys match
*
* @param key * @param key
* key to test this line's key name against. * key to test this line's key name against.
* @return true if {@code key.getName().equalsIgnorecase(getKey())}. * @return true if {@code key.getName().equalsIgnorecase(getKey())}.
@ -101,6 +103,8 @@ public final class FooterLine {
} }
/** /**
* Get key name of this footer.
*
* @return key name of this footer; that is the text before the ":" on the * @return key name of this footer; that is the text before the ":" on the
* line footer's line. The text is decoded according to the commit's * line footer's line. The text is decoded according to the commit's
* specified (or assumed) character encoding. * specified (or assumed) character encoding.
@ -110,6 +114,8 @@ public final class FooterLine {
} }
/** /**
* Get value of this footer.
*
* @return value of this footer; that is the text after the ":" and any * @return value of this footer; that is the text after the ":" and any
* leading whitespace has been skipped. May be the empty string if * leading whitespace has been skipped. May be the empty string if
* the footer has no value (line ended with ":"). The text is * the footer has no value (line ended with ":"). The text is
@ -144,6 +150,7 @@ public final class FooterLine {
return RawParseUtils.decode(enc, buffer, lt, gt - 1); return RawParseUtils.decode(enc, buffer, lt, gt - 1);
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return getKey() + ": " + getValue(); //$NON-NLS-1$ return getKey() + ": " + getValue(); //$NON-NLS-1$

12
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/LIFORevQueue.java

@ -49,11 +49,15 @@ import java.io.IOException;
import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.IncorrectObjectTypeException;
import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.errors.MissingObjectException;
/** A queue of commits in LIFO order. */ /**
* A queue of commits in LIFO order.
*/
public class LIFORevQueue extends BlockRevQueue { public class LIFORevQueue extends BlockRevQueue {
private Block head; private Block head;
/** Create an empty LIFO queue. */ /**
* Create an empty LIFO queue.
*/
public LIFORevQueue() { public LIFORevQueue() {
super(); super();
} }
@ -63,6 +67,7 @@ public class LIFORevQueue extends BlockRevQueue {
super(s); super(s);
} }
/** {@inheritDoc} */
@Override @Override
public void add(final RevCommit c) { public void add(final RevCommit c) {
Block b = head; Block b = head;
@ -75,6 +80,7 @@ public class LIFORevQueue extends BlockRevQueue {
b.unpop(c); b.unpop(c);
} }
/** {@inheritDoc} */
@Override @Override
public RevCommit next() { public RevCommit next() {
final Block b = head; final Block b = head;
@ -89,6 +95,7 @@ public class LIFORevQueue extends BlockRevQueue {
return c; return c;
} }
/** {@inheritDoc} */
@Override @Override
public void clear() { public void clear() {
head = null; head = null;
@ -115,6 +122,7 @@ public class LIFORevQueue extends BlockRevQueue {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder s = new StringBuilder(); final StringBuilder s = new StringBuilder();

101
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/ObjectWalk.java

@ -76,8 +76,9 @@ import org.eclipse.jgit.util.RawParseUtils;
* scheduled for inclusion in the results of {@link #nextObject()}, returning * scheduled for inclusion in the results of {@link #nextObject()}, returning
* each object exactly once. Objects are sorted and returned according to the * each object exactly once. Objects are sorted and returned according to the
* the commits that reference them and the order they appear within a tree. * the commits that reference them and the order they appear within a tree.
* Ordering can be affected by changing the {@link RevSort} used to order the * Ordering can be affected by changing the
* commits that are returned first. * {@link org.eclipse.jgit.revwalk.RevSort} used to order the commits that are
* returned first.
*/ */
public class ObjectWalk extends RevWalk { public class ObjectWalk extends RevWalk {
private static final int ID_SZ = 20; private static final int ID_SZ = 20;
@ -142,34 +143,39 @@ public class ObjectWalk extends RevWalk {
/** /**
* Mark an object or commit to start graph traversal from. * Mark an object or commit to start graph traversal from.
* <p> * <p>
* Callers are encouraged to use {@link RevWalk#parseAny(AnyObjectId)} * Callers are encouraged to use
* instead of {@link RevWalk#lookupAny(AnyObjectId, int)}, as this method * {@link org.eclipse.jgit.revwalk.RevWalk#parseAny(AnyObjectId)} instead of
* requires the object to be parsed before it can be added as a root for the * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}, as
* traversal. * this method requires the object to be parsed before it can be added as a
* root for the traversal.
* <p> * <p>
* The method will automatically parse an unparsed object, but error * The method will automatically parse an unparsed object, but error
* handling may be more difficult for the application to explain why a * handling may be more difficult for the application to explain why a
* RevObject is not actually valid. The object pool of this walker would * RevObject is not actually valid. The object pool of this walker would
* also be 'poisoned' by the invalid RevObject. * also be 'poisoned' by the invalid RevObject.
* <p> * <p>
* This method will automatically call {@link RevWalk#markStart(RevCommit)} * This method will automatically call
* if passed RevCommit instance, or a RevTag that directly (or indirectly) * {@link org.eclipse.jgit.revwalk.RevWalk#markStart(RevCommit)} if passed
* references a RevCommit. * RevCommit instance, or a RevTag that directly (or indirectly) references
* a RevCommit.
* *
* @param o * @param o
* the object to start traversing from. The object passed must be * the object to start traversing from. The object passed must be
* from this same revision walker. * from this same revision walker.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the object supplied is not available from the object * the object supplied is not available from the object
* database. This usually indicates the supplied object is * database. This usually indicates the supplied object is
* invalid, but the reference was constructed during an earlier * invalid, but the reference was constructed during an earlier
* invocation to {@link RevWalk#lookupAny(AnyObjectId, int)}. * invocation to
* @throws IncorrectObjectTypeException * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}.
* @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the object was not parsed yet and it was discovered during * the object was not parsed yet and it was discovered during
* parsing that it is not actually the type of the instance * parsing that it is not actually the type of the instance
* passed in. This usually indicates the caller used the wrong * passed in. This usually indicates the caller used the wrong
* type in a {@link RevWalk#lookupAny(AnyObjectId, int)} call. * type in a
* @throws IOException * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}
* call.
* @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void markStart(RevObject o) throws MissingObjectException, public void markStart(RevObject o) throws MissingObjectException,
@ -193,33 +199,38 @@ public class ObjectWalk extends RevWalk {
* reachable chain, back until the merge base of an uninteresting commit and * reachable chain, back until the merge base of an uninteresting commit and
* an otherwise interesting commit. * an otherwise interesting commit.
* <p> * <p>
* Callers are encouraged to use {@link RevWalk#parseAny(AnyObjectId)} * Callers are encouraged to use
* instead of {@link RevWalk#lookupAny(AnyObjectId, int)}, as this method * {@link org.eclipse.jgit.revwalk.RevWalk#parseAny(AnyObjectId)} instead of
* requires the object to be parsed before it can be added as a root for the * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}, as
* traversal. * this method requires the object to be parsed before it can be added as a
* root for the traversal.
* <p> * <p>
* The method will automatically parse an unparsed object, but error * The method will automatically parse an unparsed object, but error
* handling may be more difficult for the application to explain why a * handling may be more difficult for the application to explain why a
* RevObject is not actually valid. The object pool of this walker would * RevObject is not actually valid. The object pool of this walker would
* also be 'poisoned' by the invalid RevObject. * also be 'poisoned' by the invalid RevObject.
* <p> * <p>
* This method will automatically call {@link RevWalk#markStart(RevCommit)} * This method will automatically call
* if passed RevCommit instance, or a RevTag that directly (or indirectly) * {@link org.eclipse.jgit.revwalk.RevWalk#markStart(RevCommit)} if passed
* references a RevCommit. * RevCommit instance, or a RevTag that directly (or indirectly) references
* a RevCommit.
* *
* @param o * @param o
* the object to start traversing from. The object passed must be * the object to start traversing from. The object passed must be
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the object supplied is not available from the object * the object supplied is not available from the object
* database. This usually indicates the supplied object is * database. This usually indicates the supplied object is
* invalid, but the reference was constructed during an earlier * invalid, but the reference was constructed during an earlier
* invocation to {@link RevWalk#lookupAny(AnyObjectId, int)}. * invocation to
* @throws IncorrectObjectTypeException * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}.
* @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the object was not parsed yet and it was discovered during * the object was not parsed yet and it was discovered during
* parsing that it is not actually the type of the instance * parsing that it is not actually the type of the instance
* passed in. This usually indicates the caller used the wrong * passed in. This usually indicates the caller used the wrong
* type in a {@link RevWalk#lookupAny(AnyObjectId, int)} call. * type in a
* @throws IOException * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}
* call.
* @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void markUninteresting(RevObject o) throws MissingObjectException, public void markUninteresting(RevObject o) throws MissingObjectException,
@ -243,12 +254,14 @@ public class ObjectWalk extends RevWalk {
addObject(o); addObject(o);
} }
/** {@inheritDoc} */
@Override @Override
public void sort(RevSort s) { public void sort(RevSort s) {
super.sort(s); super.sort(s);
boundary = hasRevSort(RevSort.BOUNDARY); boundary = hasRevSort(RevSort.BOUNDARY);
} }
/** {@inheritDoc} */
@Override @Override
public void sort(RevSort s, boolean use) { public void sort(RevSort s, boolean use) {
super.sort(s, use); super.sort(s, use);
@ -259,7 +272,6 @@ public class ObjectWalk extends RevWalk {
* Get the currently configured object filter. * Get the currently configured object filter.
* *
* @return the current filter. Never null as a filter is always needed. * @return the current filter. Never null as a filter is always needed.
*
* @since 4.0 * @since 4.0
*/ */
public ObjectFilter getObjectFilter() { public ObjectFilter getObjectFilter() {
@ -268,8 +280,8 @@ public class ObjectWalk extends RevWalk {
/** /**
* Set the object filter for this walker. This filter affects the objects * Set the object filter for this walker. This filter affects the objects
* visited by {@link #nextObject()}. It does not affect the commits * visited by {@link #nextObject()}. It does not affect the commits listed
* listed by {@link #next()}. * by {@link #next()}.
* <p> * <p>
* If the filter returns false for an object, then that object is skipped * If the filter returns false for an object, then that object is skipped
* and objects reachable from it are not enqueued to be walked recursively. * and objects reachable from it are not enqueued to be walked recursively.
@ -277,9 +289,9 @@ public class ObjectWalk extends RevWalk {
* are known to be uninteresting. * are known to be uninteresting.
* *
* @param newFilter * @param newFilter
* the new filter. If null the special {@link ObjectFilter#ALL} * the new filter. If null the special
* {@link org.eclipse.jgit.revwalk.filter.ObjectFilter#ALL}
* filter will be used instead, as it matches every object. * filter will be used instead, as it matches every object.
*
* @since 4.0 * @since 4.0
*/ */
public void setObjectFilter(ObjectFilter newFilter) { public void setObjectFilter(ObjectFilter newFilter) {
@ -287,6 +299,7 @@ public class ObjectWalk extends RevWalk {
objectFilter = newFilter != null ? newFilter : ObjectFilter.ALL; objectFilter = newFilter != null ? newFilter : ObjectFilter.ALL;
} }
/** {@inheritDoc} */
@Override @Override
public RevCommit next() throws MissingObjectException, public RevCommit next() throws MissingObjectException,
IncorrectObjectTypeException, IOException { IncorrectObjectTypeException, IOException {
@ -316,14 +329,14 @@ public class ObjectWalk extends RevWalk {
* Pop the next most recent object. * Pop the next most recent object.
* *
* @return next most recent object; null if traversal is over. * @return next most recent object; null if traversal is over.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* one or or more of the next objects are not available from the * one or or more of the next objects are not available from the
* object database, but were thought to be candidates for * object database, but were thought to be candidates for
* traversal. This usually indicates a broken link. * traversal. This usually indicates a broken link.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* one or or more of the objects in a tree do not match the type * one or or more of the objects in a tree do not match the type
* indicated. * indicated.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevObject nextObject() throws MissingObjectException, public RevObject nextObject() throws MissingObjectException,
@ -520,14 +533,14 @@ public class ObjectWalk extends RevWalk {
* exception if there is a connectivity problem. The exception message * exception if there is a connectivity problem. The exception message
* provides some detail about the connectivity failure. * provides some detail about the connectivity failure.
* *
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* one or or more of the next objects are not available from the * one or or more of the next objects are not available from the
* object database, but were thought to be candidates for * object database, but were thought to be candidates for
* traversal. This usually indicates a broken link. * traversal. This usually indicates a broken link.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* one or or more of the objects in a tree do not match the type * one or or more of the objects in a tree do not match the type
* indicated. * indicated.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void checkConnectivity() throws MissingObjectException, public void checkConnectivity() throws MissingObjectException,
@ -618,14 +631,22 @@ public class ObjectWalk extends RevWalk {
return hash; return hash;
} }
/** @return the internal buffer holding the current path. */ /**
* Get the internal buffer holding the current path.
*
* @return the internal buffer holding the current path.
*/
public byte[] getPathBuffer() { public byte[] getPathBuffer() {
if (pathLen == 0) if (pathLen == 0)
pathLen = updatePathBuf(currVisit); pathLen = updatePathBuf(currVisit);
return pathBuf; return pathBuf;
} }
/** @return length of the path in {@link #getPathBuffer()}. */ /**
* Get length of the path in {@link #getPathBuffer()}.
*
* @return length of the path in {@link #getPathBuffer()}.
*/
public int getPathLength() { public int getPathLength() {
if (pathLen == 0) if (pathLen == 0)
pathLen = updatePathBuf(currVisit); pathLen = updatePathBuf(currVisit);
@ -667,6 +688,7 @@ public class ObjectWalk extends RevWalk {
pathBuf = newBuf; pathBuf = newBuf;
} }
/** {@inheritDoc} */
@Override @Override
public void dispose() { public void dispose() {
super.dispose(); super.dispose();
@ -675,6 +697,7 @@ public class ObjectWalk extends RevWalk {
freeVisit = null; freeVisit = null;
} }
/** {@inheritDoc} */
@Override @Override
protected void reset(final int retainFlags) { protected void reset(final int retainFlags) {
super.reset(retainFlags); super.reset(retainFlags);

5
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RenameCallback.java

@ -46,8 +46,9 @@ import org.eclipse.jgit.diff.DiffEntry;
/** /**
* An instance of this class can be used in conjunction with a * An instance of this class can be used in conjunction with a
* {@link FollowFilter}. Whenever a rename has been detected during a revision * {@link org.eclipse.jgit.revwalk.FollowFilter}. Whenever a rename has been
* walk, it will be reported here. * detected during a revision walk, it will be reported here.
*
* @see FollowFilter#setRenameCallback(RenameCallback) * @see FollowFilter#setRenameCallback(RenameCallback)
*/ */
public abstract class RenameCallback { public abstract class RenameCallback {

5
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevBlob.java

@ -52,7 +52,9 @@ import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.AnyObjectId;
import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Constants;
/** A binary file, or a symbolic link. */ /**
* A binary file, or a symbolic link.
*/
public class RevBlob extends RevObject { public class RevBlob extends RevObject {
/** /**
* Create a new blob reference. * Create a new blob reference.
@ -64,6 +66,7 @@ public class RevBlob extends RevObject {
super(id); super(id);
} }
/** {@inheritDoc} */
@Override @Override
public final int getType() { public final int getType() {
return Constants.OBJ_BLOB; return Constants.OBJ_BLOB;

31
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommit.java

@ -66,7 +66,9 @@ import org.eclipse.jgit.lib.PersonIdent;
import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.RawParseUtils;
import org.eclipse.jgit.util.StringUtils; import org.eclipse.jgit.util.StringUtils;
/** A commit reference to a commit in the DAG. */ /**
* A commit reference to a commit in the DAG.
*/
public class RevCommit extends RevObject { public class RevCommit extends RevObject {
private static final int STACK_DEPTH = 500; private static final int STACK_DEPTH = 500;
@ -79,7 +81,8 @@ public class RevCommit extends RevObject {
* will not have their headers loaded. * will not have their headers loaded.
* *
* Applications are discouraged from using this API. Callers usually need * Applications are discouraged from using this API. Callers usually need
* more than one commit. Use {@link RevWalk#parseCommit(AnyObjectId)} to * more than one commit. Use
* {@link org.eclipse.jgit.revwalk.RevWalk#parseCommit(AnyObjectId)} to
* obtain a RevCommit from an existing repository. * obtain a RevCommit from an existing repository.
* *
* @param raw * @param raw
@ -115,7 +118,7 @@ public class RevCommit extends RevObject {
* modified by the caller. * modified by the caller.
* @return the parsed commit, in an isolated revision pool that is not * @return the parsed commit, in an isolated revision pool that is not
* available to the caller. * available to the caller.
* @throws IOException * @throws java.io.IOException
* in case of RevWalk initialization fails * in case of RevWalk initialization fails
*/ */
public static RevCommit parse(RevWalk rw, byte[] raw) throws IOException { public static RevCommit parse(RevWalk rw, byte[] raw) throws IOException {
@ -220,6 +223,7 @@ public class RevCommit extends RevObject {
flags |= PARSED; flags |= PARSED;
} }
/** {@inheritDoc} */
@Override @Override
public final int getType() { public final int getType() {
return Constants.OBJ_COMMIT; return Constants.OBJ_COMMIT;
@ -315,7 +319,7 @@ public class RevCommit extends RevObject {
/** /**
* Time from the "committer " line of the buffer. * Time from the "committer " line of the buffer.
* *
* @return time, expressed as seconds since the epoch. * @return commit time
*/ */
public final int getCommitTime() { public final int getCommitTime() {
return commitTime; return commitTime;
@ -346,7 +350,7 @@ public class RevCommit extends RevObject {
* parent index to obtain. Must be in the range 0 through * parent index to obtain. Must be in the range 0 through
* {@link #getParentCount()}-1. * {@link #getParentCount()}-1.
* @return the specified parent. * @return the specified parent.
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* an invalid parent index was specified. * an invalid parent index was specified.
*/ */
public final RevCommit getParent(final int nth) { public final RevCommit getParent(final int nth) {
@ -394,9 +398,10 @@ public class RevCommit extends RevObject {
* should cache the return value for as long as necessary to use all * should cache the return value for as long as necessary to use all
* information from it. * information from it.
* <p> * <p>
* RevFilter implementations should try to use {@link RawParseUtils} to scan * RevFilter implementations should try to use
* the {@link #getRawBuffer()} instead, as this will allow faster evaluation * {@link org.eclipse.jgit.util.RawParseUtils} to scan the
* of commits. * {@link #getRawBuffer()} instead, as this will allow faster evaluation of
* commits.
* *
* @return identity of the author (name, email) and the time the commit was * @return identity of the author (name, email) and the time the commit was
* made by the author; null if no author line was found. * made by the author; null if no author line was found.
@ -420,9 +425,10 @@ public class RevCommit extends RevObject {
* should cache the return value for as long as necessary to use all * should cache the return value for as long as necessary to use all
* information from it. * information from it.
* <p> * <p>
* RevFilter implementations should try to use {@link RawParseUtils} to scan * RevFilter implementations should try to use
* the {@link #getRawBuffer()} instead, as this will allow faster evaluation * {@link org.eclipse.jgit.util.RawParseUtils} to scan the
* of commits. * {@link #getRawBuffer()} instead, as this will allow faster evaluation of
* commits.
* *
* @return identity of the committer (name, email) and the time the commit * @return identity of the committer (name, email) and the time the commit
* was made by the committer; null if no committer line was found. * was made by the committer; null if no committer line was found.
@ -654,7 +660,7 @@ public class RevCommit extends RevObject {
* time in {@link #getCommitTime()}. Accessing other properties such as * time in {@link #getCommitTime()}. Accessing other properties such as
* {@link #getAuthorIdent()}, {@link #getCommitterIdent()} or either message * {@link #getAuthorIdent()}, {@link #getCommitterIdent()} or either message
* function requires reloading the buffer by invoking * function requires reloading the buffer by invoking
* {@link RevWalk#parseBody(RevObject)}. * {@link org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject)}.
* *
* @since 4.0 * @since 4.0
*/ */
@ -662,6 +668,7 @@ public class RevCommit extends RevObject {
buffer = null; buffer = null;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder s = new StringBuilder(); final StringBuilder s = new StringBuilder();

39
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommitList.java

@ -50,7 +50,7 @@ import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.revwalk.filter.RevFilter; import org.eclipse.jgit.revwalk.filter.RevFilter;
/** /**
* An ordered list of {@link RevCommit} subclasses. * An ordered list of {@link org.eclipse.jgit.revwalk.RevCommit} subclasses.
* *
* @param <E> * @param <E>
* type of subclass of RevCommit the list is storing. * type of subclass of RevCommit the list is storing.
@ -58,6 +58,7 @@ import org.eclipse.jgit.revwalk.filter.RevFilter;
public class RevCommitList<E extends RevCommit> extends RevObjectList<E> { public class RevCommitList<E extends RevCommit> extends RevObjectList<E> {
private RevWalk walker; private RevWalk walker;
/** {@inheritDoc} */
@Override @Override
public void clear() { public void clear() {
super.clear(); super.clear();
@ -77,15 +78,15 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> {
* @param flag * @param flag
* the flag to apply (or remove). Applications are responsible * the flag to apply (or remove). Applications are responsible
* for allocating this flag from the source RevWalk. * for allocating this flag from the source RevWalk.
* @throws IOException * @throws java.io.IOException
* revision filter needed to read additional objects, but an * revision filter needed to read additional objects, but an
* error occurred while reading the pack files or loose objects * error occurred while reading the pack files or loose objects
* of the repository. * of the repository.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* revision filter needed to read additional objects, but an * revision filter needed to read additional objects, but an
* object was not of the correct type. Repository corruption may * object was not of the correct type. Repository corruption may
* have occurred. * have occurred.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* revision filter needed to read additional objects, but an * revision filter needed to read additional objects, but an
* object that should be present was not found. Repository * object that should be present was not found. Repository
* corruption may have occurred. * corruption may have occurred.
@ -117,15 +118,15 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> {
* last commit within the list to end testing at, exclusive. If * last commit within the list to end testing at, exclusive. If
* smaller than or equal to <code>rangeBegin</code> then no * smaller than or equal to <code>rangeBegin</code> then no
* commits will be tested. * commits will be tested.
* @throws IOException * @throws java.io.IOException
* revision filter needed to read additional objects, but an * revision filter needed to read additional objects, but an
* error occurred while reading the pack files or loose objects * error occurred while reading the pack files or loose objects
* of the repository. * of the repository.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* revision filter needed to read additional objects, but an * revision filter needed to read additional objects, but an
* object was not of the correct type. Repository corruption may * object was not of the correct type. Repository corruption may
* have occurred. * have occurred.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* revision filter needed to read additional objects, but an * revision filter needed to read additional objects, but an
* object that should be present was not found. Repository * object that should be present was not found. Repository
* corruption may have occurred. * corruption may have occurred.
@ -290,12 +291,12 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> {
* @param highMark * @param highMark
* number of commits the caller wants this list to contain when * number of commits the caller wants this list to contain when
* the fill operation is complete. * the fill operation is complete.
* @throws IOException * @throws java.io.IOException
* see {@link RevWalk#next()} * see {@link org.eclipse.jgit.revwalk.RevWalk#next()}
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* see {@link RevWalk#next()} * see {@link org.eclipse.jgit.revwalk.RevWalk#next()}
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* see {@link RevWalk#next()} * see {@link org.eclipse.jgit.revwalk.RevWalk#next()}
*/ */
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public void fillTo(final int highMark) throws MissingObjectException, public void fillTo(final int highMark) throws MissingObjectException,
@ -355,12 +356,12 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> {
* contain when the fill operation is complete. If highMark is 0 * contain when the fill operation is complete. If highMark is 0
* the walk is pumped until the specified commit or the end of * the walk is pumped until the specified commit or the end of
* the walk is reached. * the walk is reached.
* @throws IOException * @throws java.io.IOException
* see {@link RevWalk#next()} * see {@link org.eclipse.jgit.revwalk.RevWalk#next()}
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* see {@link RevWalk#next()} * see {@link org.eclipse.jgit.revwalk.RevWalk#next()}
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* see {@link RevWalk#next()} * see {@link org.eclipse.jgit.revwalk.RevWalk#next()}
*/ */
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public void fillTo(final RevCommit commitToLoad, int highMark) public void fillTo(final RevCommit commitToLoad, int highMark)

6
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlag.java

@ -48,9 +48,10 @@ import java.text.MessageFormat;
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** /**
* Application level mark bit for {@link RevObject}s. * Application level mark bit for {@link org.eclipse.jgit.revwalk.RevObject}s.
* <p> * <p>
* To create a flag use {@link RevWalk#newFlag(String)}. * To create a flag use
* {@link org.eclipse.jgit.revwalk.RevWalk#newFlag(String)}.
*/ */
public class RevFlag { public class RevFlag {
/** /**
@ -99,6 +100,7 @@ public class RevFlag {
return walker; return walker;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return name; return name;

13
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlagSet.java

@ -50,7 +50,8 @@ import java.util.Iterator;
import java.util.List; import java.util.List;
/** /**
* Multiple application level mark bits for {@link RevObject}s. * Multiple application level mark bits for
* {@link org.eclipse.jgit.revwalk.RevObject}s.
* *
* @see RevFlag * @see RevFlag
*/ */
@ -59,7 +60,9 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
private final List<RevFlag> active; private final List<RevFlag> active;
/** Create an empty set of flags. */ /**
* Create an empty set of flags.
*/
public RevFlagSet() { public RevFlagSet() {
active = new ArrayList<>(); active = new ArrayList<>();
} }
@ -86,6 +89,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
addAll(s); addAll(s);
} }
/** {@inheritDoc} */
@Override @Override
public boolean contains(final Object o) { public boolean contains(final Object o) {
if (o instanceof RevFlag) if (o instanceof RevFlag)
@ -93,6 +97,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean containsAll(final Collection<?> c) { public boolean containsAll(final Collection<?> c) {
if (c instanceof RevFlagSet) { if (c instanceof RevFlagSet) {
@ -102,6 +107,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
return super.containsAll(c); return super.containsAll(c);
} }
/** {@inheritDoc} */
@Override @Override
public boolean add(final RevFlag flag) { public boolean add(final RevFlag flag) {
if ((mask & flag.mask) != 0) if ((mask & flag.mask) != 0)
@ -114,6 +120,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public boolean remove(final Object o) { public boolean remove(final Object o) {
final RevFlag flag = (RevFlag) o; final RevFlag flag = (RevFlag) o;
@ -126,6 +133,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public Iterator<RevFlag> iterator() { public Iterator<RevFlag> iterator() {
final Iterator<RevFlag> i = active.iterator(); final Iterator<RevFlag> i = active.iterator();
@ -150,6 +158,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> {
}; };
} }
/** {@inheritDoc} */
@Override @Override
public int size() { public int size() {
return active.size(); return active.size();

9
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObject.java

@ -52,7 +52,9 @@ import org.eclipse.jgit.lib.Constants;
import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectId;
import org.eclipse.jgit.lib.ObjectIdOwnerMap; import org.eclipse.jgit.lib.ObjectIdOwnerMap;
/** Base object type accessed during revision walking. */ /**
* Base object type accessed during revision walking.
*/
public abstract class RevObject extends ObjectIdOwnerMap.Entry { public abstract class RevObject extends ObjectIdOwnerMap.Entry {
static final int PARSED = 1; static final int PARSED = 1;
@ -69,7 +71,7 @@ public abstract class RevObject extends ObjectIdOwnerMap.Entry {
IncorrectObjectTypeException, IOException; IncorrectObjectTypeException, IOException;
/** /**
* Get Git object type. See {@link Constants}. * Get Git object type. See {@link org.eclipse.jgit.lib.Constants}.
* *
* @return object type * @return object type
*/ */
@ -163,6 +165,7 @@ public abstract class RevObject extends ObjectIdOwnerMap.Entry {
flags &= ~set.mask; flags &= ~set.mask;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder s = new StringBuilder(); final StringBuilder s = new StringBuilder();
@ -175,6 +178,8 @@ public abstract class RevObject extends ObjectIdOwnerMap.Entry {
} }
/** /**
* Append a debug description of core RevFlags to a buffer.
*
* @param s * @param s
* buffer to append a debug description of core RevFlags onto. * buffer to append a debug description of core RevFlags onto.
*/ */

11
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObjectList.java

@ -51,7 +51,7 @@ import java.util.AbstractList;
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** /**
* An ordered list of {@link RevObject} subclasses. * An ordered list of {@link org.eclipse.jgit.revwalk.RevObject} subclasses.
* *
* @param <E> * @param <E>
* type of subclass of RevObject the list is storing. * type of subclass of RevObject the list is storing.
@ -73,11 +73,14 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> {
/** Current number of elements in the list. */ /** Current number of elements in the list. */
protected int size = 0; protected int size = 0;
/** Create an empty object list. */ /**
* Create an empty object list.
*/
public RevObjectList() { public RevObjectList() {
// Initialized above. // Initialized above.
} }
/** {@inheritDoc} */
@Override @Override
public void add(final int index, final E element) { public void add(final int index, final E element) {
if (index != size) if (index != size)
@ -88,6 +91,7 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> {
size++; size++;
} }
/** {@inheritDoc} */
@Override @Override
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public E set(int index, E element) { public E set(int index, E element) {
@ -109,6 +113,7 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> {
return (E) old; return (E) old;
} }
/** {@inheritDoc} */
@Override @Override
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public E get(int index) { public E get(int index) {
@ -123,11 +128,13 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> {
return s != null ? (E) s.contents[index] : null; return s != null ? (E) s.contents[index] : null;
} }
/** {@inheritDoc} */
@Override @Override
public int size() { public int size() {
return size; return size;
} }
/** {@inheritDoc} */
@Override @Override
public void clear() { public void clear() {
contents = new Block(0); contents = new Block(0);

5
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevSort.java

@ -44,7 +44,10 @@
package org.eclipse.jgit.revwalk; package org.eclipse.jgit.revwalk;
/** Sorting strategies supported by {@link RevWalk} and {@link ObjectWalk}. */ /**
* Sorting strategies supported by {@link org.eclipse.jgit.revwalk.RevWalk} and
* {@link org.eclipse.jgit.revwalk.ObjectWalk}.
*/
public enum RevSort { public enum RevSort {
/** /**
* No specific sorting is requested. * No specific sorting is requested.

27
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTag.java

@ -64,7 +64,9 @@ import org.eclipse.jgit.util.MutableInteger;
import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.RawParseUtils;
import org.eclipse.jgit.util.StringUtils; import org.eclipse.jgit.util.StringUtils;
/** An annotated tag. */ /**
* An annotated tag.
*/
public class RevTag extends RevObject { public class RevTag extends RevObject {
/** /**
* Parse an annotated tag from its canonical format. * Parse an annotated tag from its canonical format.
@ -75,14 +77,15 @@ public class RevTag extends RevObject {
* not have its headers loaded. * not have its headers loaded.
* *
* Applications are discouraged from using this API. Callers usually need * Applications are discouraged from using this API. Callers usually need
* more than one object. Use {@link RevWalk#parseTag(AnyObjectId)} to obtain * more than one object. Use
* {@link org.eclipse.jgit.revwalk.RevWalk#parseTag(AnyObjectId)} to obtain
* a RevTag from an existing repository. * a RevTag from an existing repository.
* *
* @param raw * @param raw
* the canonical formatted tag to be parsed. * the canonical formatted tag to be parsed.
* @return the parsed tag, in an isolated revision pool that is not * @return the parsed tag, in an isolated revision pool that is not
* available to the caller. * available to the caller.
* @throws CorruptObjectException * @throws org.eclipse.jgit.errors.CorruptObjectException
* the tag contains a malformed header that cannot be handled. * the tag contains a malformed header that cannot be handled.
*/ */
public static RevTag parse(byte[] raw) throws CorruptObjectException { public static RevTag parse(byte[] raw) throws CorruptObjectException {
@ -109,7 +112,7 @@ public class RevTag extends RevObject {
* modified by the caller. * modified by the caller.
* @return the parsed tag, in an isolated revision pool that is not * @return the parsed tag, in an isolated revision pool that is not
* available to the caller. * available to the caller.
* @throws CorruptObjectException * @throws org.eclipse.jgit.errors.CorruptObjectException
* the tag contains a malformed header that cannot be handled. * the tag contains a malformed header that cannot be handled.
*/ */
public static RevTag parse(RevWalk rw, byte[] raw) public static RevTag parse(RevWalk rw, byte[] raw)
@ -173,6 +176,7 @@ public class RevTag extends RevObject {
flags |= PARSED; flags |= PARSED;
} }
/** {@inheritDoc} */
@Override @Override
public final int getType() { public final int getType() {
return Constants.OBJ_TAG; return Constants.OBJ_TAG;
@ -261,12 +265,15 @@ public class RevTag extends RevObject {
* Get a reference to the object this tag was placed on. * Get a reference to the object this tag was placed on.
* <p> * <p>
* Note that the returned object has only been looked up (see * Note that the returned object has only been looked up (see
* {@link RevWalk#lookupAny(AnyObjectId, int)}. To access the contents it * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}. To
* needs to be parsed, see {@link RevWalk#parseHeaders(RevObject)} and * access the contents it needs to be parsed, see
* {@link RevWalk#parseBody(RevObject)}. * {@link org.eclipse.jgit.revwalk.RevWalk#parseHeaders(RevObject)} and
* {@link org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject)}.
* <p> * <p>
* As an alternative, use {@link RevWalk#peel(RevObject)} and pass this * As an alternative, use
* {@link RevTag} to peel it until the first non-tag object. * {@link org.eclipse.jgit.revwalk.RevWalk#peel(RevObject)} and pass this
* {@link org.eclipse.jgit.revwalk.RevTag} to peel it until the first
* non-tag object.
* *
* @return object this tag refers to (only looked up, not parsed) * @return object this tag refers to (only looked up, not parsed)
*/ */
@ -290,7 +297,7 @@ public class RevTag extends RevObject {
* only the {@link #getObject()} pointer and {@link #getTagName()}. * only the {@link #getObject()} pointer and {@link #getTagName()}.
* Accessing other properties such as {@link #getTaggerIdent()} or either * Accessing other properties such as {@link #getTaggerIdent()} or either
* message function requires reloading the buffer by invoking * message function requires reloading the buffer by invoking
* {@link RevWalk#parseBody(RevObject)}. * {@link org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject)}.
* *
* @since 4.0 * @since 4.0
*/ */

5
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTree.java

@ -52,7 +52,9 @@ import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.AnyObjectId;
import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Constants;
/** A reference to a tree of subtrees/files. */ /**
* A reference to a tree of subtrees/files.
*/
public class RevTree extends RevObject { public class RevTree extends RevObject {
/** /**
* Create a new tree reference. * Create a new tree reference.
@ -64,6 +66,7 @@ public class RevTree extends RevObject {
super(id); super(id);
} }
/** {@inheritDoc} */
@Override @Override
public final int getType() { public final int getType() {
return Constants.OBJ_TREE; return Constants.OBJ_TREE;

166
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java

@ -84,10 +84,12 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter;
* usage of a RevWalk instance to a single thread, or implement their own * usage of a RevWalk instance to a single thread, or implement their own
* synchronization at a higher level. * synchronization at a higher level.
* <p> * <p>
* Multiple simultaneous RevWalk instances per {@link Repository} are permitted, * Multiple simultaneous RevWalk instances per
* even from concurrent threads. Equality of {@link RevCommit}s from two * {@link org.eclipse.jgit.lib.Repository} are permitted, even from concurrent
* different RevWalk instances is never true, even if their {@link ObjectId}s * threads. Equality of {@link org.eclipse.jgit.revwalk.RevCommit}s from two
* are equal (and thus they describe the same commit). * different RevWalk instances is never true, even if their
* {@link org.eclipse.jgit.lib.ObjectId}s are equal (and thus they describe the
* same commit).
* <p> * <p>
* The offered iterator is over the list of RevCommits described by the * The offered iterator is over the list of RevCommits described by the
* configuration of this instance. Applications should restrict themselves to * configuration of this instance. Applications should restrict themselves to
@ -236,12 +238,18 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
this.closeReader = closeReader; this.closeReader = closeReader;
} }
/** @return the reader this walker is using to load objects. */ /**
* Get the reader this walker is using to load objects.
*
* @return the reader this walker is using to load objects.
*/
public ObjectReader getObjectReader() { public ObjectReader getObjectReader() {
return reader; return reader;
} }
/** /**
* {@inheritDoc}
* <p>
* Release any resources used by this walker's reader. * Release any resources used by this walker's reader.
* <p> * <p>
* A walker that has been released can be used again, but may need to be * A walker that has been released can be used again, but may need to be
@ -272,17 +280,17 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param c * @param c
* the commit to start traversing from. The commit passed must be * the commit to start traversing from. The commit passed must be
* from this same revision walker. * from this same revision walker.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the commit supplied is not available from the object * the commit supplied is not available from the object
* database. This usually indicates the supplied commit is * database. This usually indicates the supplied commit is
* invalid, but the reference was constructed during an earlier * invalid, but the reference was constructed during an earlier
* invocation to {@link #lookupCommit(AnyObjectId)}. * invocation to {@link #lookupCommit(AnyObjectId)}.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the object was not parsed yet and it was discovered during * the object was not parsed yet and it was discovered during
* parsing that it is not actually a commit. This usually * parsing that it is not actually a commit. This usually
* indicates the caller supplied a non-commit SHA-1 to * indicates the caller supplied a non-commit SHA-1 to
* {@link #lookupCommit(AnyObjectId)}. * {@link #lookupCommit(AnyObjectId)}.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void markStart(final RevCommit c) throws MissingObjectException, public void markStart(final RevCommit c) throws MissingObjectException,
@ -302,17 +310,17 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param list * @param list
* commits to start traversing from. The commits passed must be * commits to start traversing from. The commits passed must be
* from this same revision walker. * from this same revision walker.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* one of the commits supplied is not available from the object * one of the commits supplied is not available from the object
* database. This usually indicates the supplied commit is * database. This usually indicates the supplied commit is
* invalid, but the reference was constructed during an earlier * invalid, but the reference was constructed during an earlier
* invocation to {@link #lookupCommit(AnyObjectId)}. * invocation to {@link #lookupCommit(AnyObjectId)}.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the object was not parsed yet and it was discovered during * the object was not parsed yet and it was discovered during
* parsing that it is not actually a commit. This usually * parsing that it is not actually a commit. This usually
* indicates the caller supplied a non-commit SHA-1 to * indicates the caller supplied a non-commit SHA-1 to
* {@link #lookupCommit(AnyObjectId)}. * {@link #lookupCommit(AnyObjectId)}.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void markStart(final Collection<RevCommit> list) public void markStart(final Collection<RevCommit> list)
@ -342,17 +350,17 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param c * @param c
* the commit to start traversing from. The commit passed must be * the commit to start traversing from. The commit passed must be
* from this same revision walker. * from this same revision walker.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the commit supplied is not available from the object * the commit supplied is not available from the object
* database. This usually indicates the supplied commit is * database. This usually indicates the supplied commit is
* invalid, but the reference was constructed during an earlier * invalid, but the reference was constructed during an earlier
* invocation to {@link #lookupCommit(AnyObjectId)}. * invocation to {@link #lookupCommit(AnyObjectId)}.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the object was not parsed yet and it was discovered during * the object was not parsed yet and it was discovered during
* parsing that it is not actually a commit. This usually * parsing that it is not actually a commit. This usually
* indicates the caller supplied a non-commit SHA-1 to * indicates the caller supplied a non-commit SHA-1 to
* {@link #lookupCommit(AnyObjectId)}. * {@link #lookupCommit(AnyObjectId)}.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void markUninteresting(final RevCommit c) public void markUninteresting(final RevCommit c)
@ -383,14 +391,14 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @return true if there is a path directly from <code>tip</code> to * @return true if there is a path directly from <code>tip</code> to
* <code>base</code> (and thus <code>base</code> is fully merged * <code>base</code> (and thus <code>base</code> is fully merged
* into <code>tip</code>); false otherwise. * into <code>tip</code>); false otherwise.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* one or or more of the next commit's parents are not available * one or or more of the next commit's parents are not available
* from the object database, but were thought to be candidates * from the object database, but were thought to be candidates
* for traversal. This usually indicates a broken link. * for traversal. This usually indicates a broken link.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* one or or more of the next commit's parents are not actually * one or or more of the next commit's parents are not actually
* commit objects. * commit objects.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public boolean isMergedInto(final RevCommit base, final RevCommit tip) public boolean isMergedInto(final RevCommit base, final RevCommit tip)
@ -420,14 +428,14 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Pop the next most recent commit. * Pop the next most recent commit.
* *
* @return next most recent commit; null if traversal is over. * @return next most recent commit; null if traversal is over.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* one or or more of the next commit's parents are not available * one or or more of the next commit's parents are not available
* from the object database, but were thought to be candidates * from the object database, but were thought to be candidates
* for traversal. This usually indicates a broken link. * for traversal. This usually indicates a broken link.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* one or or more of the next commit's parents are not actually * one or or more of the next commit's parents are not actually
* commit objects. * commit objects.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevCommit next() throws MissingObjectException, public RevCommit next() throws MissingObjectException,
@ -439,7 +447,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Obtain the sort types applied to the commits returned. * Obtain the sort types applied to the commits returned.
* *
* @return the sorting strategies employed. At least one strategy is always * @return the sorting strategies employed. At least one strategy is always
* used, but that strategy may be {@link RevSort#NONE}. * used, but that strategy may be
* {@link org.eclipse.jgit.revwalk.RevSort#NONE}.
*/ */
public EnumSet<RevSort> getRevSort() { public EnumSet<RevSort> getRevSort() {
return sorting.clone(); return sorting.clone();
@ -475,8 +484,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Add or remove a sorting strategy for the returned commits. * Add or remove a sorting strategy for the returned commits.
* <p> * <p>
* Multiple strategies can be applied at once, in which case some strategies * Multiple strategies can be applied at once, in which case some strategies
* may take precedence over others. As an example, {@link RevSort#TOPO} must * may take precedence over others. As an example,
* take precedence over {@link RevSort#COMMIT_TIME_DESC}, otherwise it * {@link org.eclipse.jgit.revwalk.RevSort#TOPO} must take precedence over
* {@link org.eclipse.jgit.revwalk.RevSort#COMMIT_TIME_DESC}, otherwise it
* cannot enforce its ordering. * cannot enforce its ordering.
* *
* @param s * @param s
@ -518,12 +528,14 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Note that filters are not thread-safe and may not be shared by concurrent * Note that filters are not thread-safe and may not be shared by concurrent
* RevWalk instances. Every RevWalk must be supplied its own unique filter, * RevWalk instances. Every RevWalk must be supplied its own unique filter,
* unless the filter implementation specifically states it is (and always * unless the filter implementation specifically states it is (and always
* will be) thread-safe. Callers may use {@link RevFilter#clone()} to create * will be) thread-safe. Callers may use
* a unique filter tree for this RevWalk instance. * {@link org.eclipse.jgit.revwalk.filter.RevFilter#clone()} to create a
* unique filter tree for this RevWalk instance.
* *
* @param newFilter * @param newFilter
* the new filter. If null the special {@link RevFilter#ALL} * the new filter. If null the special
* filter will be used instead, as it matches every commit. * {@link org.eclipse.jgit.revwalk.filter.RevFilter#ALL} filter
* will be used instead, as it matches every commit.
* @see org.eclipse.jgit.revwalk.filter.AndRevFilter * @see org.eclipse.jgit.revwalk.filter.AndRevFilter
* @see org.eclipse.jgit.revwalk.filter.OrRevFilter * @see org.eclipse.jgit.revwalk.filter.OrRevFilter
*/ */
@ -536,7 +548,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Get the tree filter used to simplify commits by modified paths. * Get the tree filter used to simplify commits by modified paths.
* *
* @return the current filter. Never null as a filter is always needed. If * @return the current filter. Never null as a filter is always needed. If
* no filter is being applied {@link TreeFilter#ALL} is returned. * no filter is being applied
* {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} is
* returned.
*/ */
public TreeFilter getTreeFilter() { public TreeFilter getTreeFilter() {
return treeFilter; return treeFilter;
@ -545,20 +559,23 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
/** /**
* Set the tree filter used to simplify commits by modified paths. * Set the tree filter used to simplify commits by modified paths.
* <p> * <p>
* If null or {@link TreeFilter#ALL} the path limiter is removed. Commits * If null or {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} the
* will not be simplified. * path limiter is removed. Commits will not be simplified.
* <p> * <p>
* If non-null and not {@link TreeFilter#ALL} then the tree filter will be * If non-null and not
* installed. Commits will have their ancestry simplified to hide commits that * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} then the tree
* do not contain tree entries matched by the filter, unless * filter will be installed. Commits will have their ancestry simplified to
* {@code setRewriteParents(false)} is called. * hide commits that do not contain tree entries matched by the filter,
* unless {@code setRewriteParents(false)} is called.
* <p> * <p>
* Usually callers should be inserting a filter graph including * Usually callers should be inserting a filter graph including
* {@link TreeFilter#ANY_DIFF} along with one or more * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} along with
* {@link org.eclipse.jgit.treewalk.filter.PathFilter} instances. * one or more {@link org.eclipse.jgit.treewalk.filter.PathFilter}
* instances.
* *
* @param newFilter * @param newFilter
* new filter. If null the special {@link TreeFilter#ALL} filter * new filter. If null the special
* {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} filter
* will be used instead, as it matches everything. * will be used instead, as it matches everything.
* @see org.eclipse.jgit.treewalk.filter.PathFilter * @see org.eclipse.jgit.treewalk.filter.PathFilter
*/ */
@ -571,9 +588,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Set whether to rewrite parent pointers when filtering by modified paths. * Set whether to rewrite parent pointers when filtering by modified paths.
* <p> * <p>
* By default, when {@link #setTreeFilter(TreeFilter)} is called with non- * By default, when {@link #setTreeFilter(TreeFilter)} is called with non-
* null and non-{@link TreeFilter#ALL} filter, commits will have their * null and non-{@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL}
* ancestry simplified and parents rewritten to hide commits that do not match * filter, commits will have their ancestry simplified and parents rewritten
* the filter. * to hide commits that do not match the filter.
* <p> * <p>
* This behavior can be bypassed by passing false to this method. * This behavior can be bypassed by passing false to this method.
* *
@ -596,8 +613,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* care and would prefer to discard the body of a commit as early as * care and would prefer to discard the body of a commit as early as
* possible, to reduce memory usage. * possible, to reduce memory usage.
* <p> * <p>
* True by default on {@link RevWalk} and false by default for * True by default on {@link org.eclipse.jgit.revwalk.RevWalk} and false by
* {@link ObjectWalk}. * default for {@link org.eclipse.jgit.revwalk.ObjectWalk}.
* *
* @return true if the body should be retained; false it is discarded. * @return true if the body should be retained; false it is discarded.
*/ */
@ -608,14 +625,15 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
/** /**
* Set whether or not the body of a commit or tag is retained. * Set whether or not the body of a commit or tag is retained.
* <p> * <p>
* If a body of a commit or tag is not retained, the application must * If a body of a commit or tag is not retained, the application must call
* call {@link #parseBody(RevObject)} before the body can be safely * {@link #parseBody(RevObject)} before the body can be safely accessed
* accessed through the type specific access methods. * through the type specific access methods.
* <p> * <p>
* True by default on {@link RevWalk} and false by default for * True by default on {@link org.eclipse.jgit.revwalk.RevWalk} and false by
* {@link ObjectWalk}. * default for {@link org.eclipse.jgit.revwalk.ObjectWalk}.
* *
* @param retain true to retain bodies; false to discard them early. * @param retain
* true to retain bodies; false to discard them early.
*/ */
public void setRetainBody(final boolean retain) { public void setRetainBody(final boolean retain) {
retainBody = retain; retainBody = retain;
@ -759,11 +777,11 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param id * @param id
* name of the commit object. * name of the commit object.
* @return reference to the commit object. Never null. * @return reference to the commit object. Never null.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the supplied commit does not exist. * the supplied commit does not exist.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the supplied id is not a commit or an annotated tag. * the supplied id is not a commit or an annotated tag.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevCommit parseCommit(final AnyObjectId id) public RevCommit parseCommit(final AnyObjectId id)
@ -786,11 +804,11 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* name of the tree object, or a commit or annotated tag that may * name of the tree object, or a commit or annotated tag that may
* reference a tree. * reference a tree.
* @return reference to the tree object. Never null. * @return reference to the tree object. Never null.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the supplied tree does not exist. * the supplied tree does not exist.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the supplied id is not a tree, a commit or an annotated tag. * the supplied id is not a tree, a commit or an annotated tag.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevTree parseTree(final AnyObjectId id) public RevTree parseTree(final AnyObjectId id)
@ -820,11 +838,11 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param id * @param id
* name of the tag object. * name of the tag object.
* @return reference to the tag object. Never null. * @return reference to the tag object. Never null.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the supplied tag does not exist. * the supplied tag does not exist.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* the supplied id is not a tag or an annotated tag. * the supplied id is not a tag or an annotated tag.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevTag parseTag(final AnyObjectId id) throws MissingObjectException, public RevTag parseTag(final AnyObjectId id) throws MissingObjectException,
@ -847,9 +865,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param id * @param id
* name of the object. * name of the object.
* @return reference to the object. Never null. * @return reference to the object. Never null.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the supplied does not exist. * the supplied does not exist.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevObject parseAny(final AnyObjectId id) public RevObject parseAny(final AnyObjectId id)
@ -916,8 +934,6 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
/** /**
* Asynchronous object parsing. * Asynchronous object parsing.
* *
* @param <T>
* any ObjectId type.
* @param objectIds * @param objectIds
* objects to open from the object store. The supplied collection * objects to open from the object store. The supplied collection
* must not be modified until the queue has finished. * must not be modified until the queue has finished.
@ -1007,9 +1023,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* *
* @param obj * @param obj
* the object the caller needs to be parsed. * the object the caller needs to be parsed.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the supplied does not exist. * the supplied does not exist.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void parseHeaders(final RevObject obj) public void parseHeaders(final RevObject obj)
@ -1026,9 +1042,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* *
* @param obj * @param obj
* the object the caller needs to be parsed. * the object the caller needs to be parsed.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* the supplied does not exist. * the supplied does not exist.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public void parseBody(final RevObject obj) public void parseBody(final RevObject obj)
@ -1044,9 +1060,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @return If {@code obj} is not an annotated tag, {@code obj}. Otherwise * @return If {@code obj} is not an annotated tag, {@code obj}. Otherwise
* the first non-tag object that {@code obj} references. The * the first non-tag object that {@code obj} references. The
* returned object's headers have been parsed. * returned object's headers have been parsed.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* a referenced object cannot be found. * a referenced object cannot be found.
* @throws IOException * @throws java.io.IOException
* a pack file or loose object could not be read. * a pack file or loose object could not be read.
*/ */
public RevObject peel(RevObject obj) throws MissingObjectException, public RevObject peel(RevObject obj) throws MissingObjectException,
@ -1069,7 +1085,7 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* @param name * @param name
* description of the flag, primarily useful for debugging. * description of the flag, primarily useful for debugging.
* @return newly constructed flag instance. * @return newly constructed flag instance.
* @throws IllegalArgumentException * @throws java.lang.IllegalArgumentException
* too many flags have been reserved on this revision walker. * too many flags have been reserved on this revision walker.
*/ */
public RevFlag newFlag(final String name) { public RevFlag newFlag(final String name) {
@ -1308,6 +1324,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
} }
/** /**
* {@inheritDoc}
* <p>
* Returns an Iterator over the commits of this walker. * Returns an Iterator over the commits of this walker.
* <p> * <p>
* The returned iterator is only useful for one walk. If this RevWalk gets * The returned iterator is only useful for one walk. If this RevWalk gets
@ -1316,10 +1334,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
* Applications must not use both the Iterator and the {@link #next()} API * Applications must not use both the Iterator and the {@link #next()} API
* at the same time. Pick one API and use that for the entire walk. * at the same time. Pick one API and use that for the entire walk.
* <p> * <p>
* If a checked exception is thrown during the walk (see {@link #next()}) * If a checked exception is thrown during the walk (see {@link #next()}) it
* it is rethrown from the Iterator as a {@link RevWalkException}. * is rethrown from the Iterator as a {@link RevWalkException}.
* *
* @return an iterator over this walker's commits.
* @see RevWalkException * @see RevWalkException
*/ */
@Override @Override
@ -1365,7 +1382,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
}; };
} }
/** Throws an exception if we have started producing output. */ /**
* Throws an exception if we have started producing output.
*/
protected void assertNotStarted() { protected void assertNotStarted() {
if (isNotStarted()) if (isNotStarted())
return; return;
@ -1377,7 +1396,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable {
} }
/** /**
* Create and return an {@link ObjectWalk} using the same objects. * Create and return an {@link org.eclipse.jgit.revwalk.ObjectWalk} using
* the same objects.
* <p> * <p>
* Prior to using this method, the caller must reset this RevWalk to clean * Prior to using this method, the caller must reset this RevWalk to clean
* any flags that were used during the last traversal. * any flags that were used during the last traversal.

38
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalkUtils.java

@ -53,7 +53,7 @@ import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.lib.Ref; import org.eclipse.jgit.lib.Ref;
/** /**
* Utility methods for {@link RevWalk}. * Utility methods for {@link org.eclipse.jgit.revwalk.RevWalk}.
*/ */
public final class RevWalkUtils { public final class RevWalkUtils {
@ -67,9 +67,10 @@ public final class RevWalkUtils {
* other words, count the number of commits that are in <code>start</code>, * other words, count the number of commits that are in <code>start</code>,
* but not in <code>end</code>. * but not in <code>end</code>.
* <p> * <p>
* Note that this method calls {@link RevWalk#reset()} at the beginning. * Note that this method calls
* Also note that the existing rev filter on the walk is left as-is, so be * {@link org.eclipse.jgit.revwalk.RevWalk#reset()} at the beginning. Also
* sure to set the right rev filter before calling this method. * note that the existing rev filter on the walk is left as-is, so be sure
* to set the right rev filter before calling this method.
* *
* @param walk * @param walk
* the rev walk to use * the rev walk to use
@ -78,11 +79,10 @@ public final class RevWalkUtils {
* @param end * @param end
* the commit where counting should end, or null if counting * the commit where counting should end, or null if counting
* should be done until there are no more commits * should be done until there are no more commits
*
* @return the number of commits * @return the number of commits
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* @throws IOException * @throws java.io.IOException
*/ */
public static int count(final RevWalk walk, final RevCommit start, public static int count(final RevWalk walk, final RevCommit start,
final RevCommit end) throws MissingObjectException, final RevCommit end) throws MissingObjectException,
@ -96,9 +96,10 @@ public final class RevWalkUtils {
* Find of commits that are in <code>start</code>, but not in * Find of commits that are in <code>start</code>, but not in
* <code>end</code>. * <code>end</code>.
* <p> * <p>
* Note that this method calls {@link RevWalk#reset()} at the beginning. * Note that this method calls
* Also note that the existing rev filter on the walk is left as-is, so be * {@link org.eclipse.jgit.revwalk.RevWalk#reset()} at the beginning. Also
* sure to set the right rev filter before calling this method. * note that the existing rev filter on the walk is left as-is, so be sure
* to set the right rev filter before calling this method.
* *
* @param walk * @param walk
* the rev walk to use * the rev walk to use
@ -108,9 +109,9 @@ public final class RevWalkUtils {
* the commit where counting should end, or null if counting * the commit where counting should end, or null if counting
* should be done until there are no more commits * should be done until there are no more commits
* @return the commits found * @return the commits found
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* @throws IOException * @throws java.io.IOException
*/ */
public static List<RevCommit> find(final RevWalk walk, public static List<RevCommit> find(final RevWalk walk,
final RevCommit start, final RevCommit end) final RevCommit start, final RevCommit end)
@ -131,7 +132,8 @@ public final class RevWalkUtils {
* Find the list of branches a given commit is reachable from when following * Find the list of branches a given commit is reachable from when following
* parent.s * parent.s
* <p> * <p>
* Note that this method calls {@link RevWalk#reset()} at the beginning. * Note that this method calls
* {@link org.eclipse.jgit.revwalk.RevWalk#reset()} at the beginning.
* <p> * <p>
* In order to improve performance this method assumes clock skew among * In order to improve performance this method assumes clock skew among
* committers is never larger than 24 hours. * committers is never larger than 24 hours.
@ -143,9 +145,9 @@ public final class RevWalkUtils {
* @param refs * @param refs
* the set of branches we want to see reachability from * the set of branches we want to see reachability from
* @return the list of branches a given commit is reachable from * @return the list of branches a given commit is reachable from
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* @throws IOException * @throws java.io.IOException
*/ */
public static List<Ref> findBranchesReachableFrom(RevCommit commit, public static List<Ref> findBranchesReachableFrom(RevCommit commit,
RevWalk revWalk, Collection<Ref> refs) RevWalk revWalk, Collection<Ref> refs)

18
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/TreeRevFilter.java

@ -60,10 +60,12 @@ import org.eclipse.jgit.treewalk.TreeWalk;
import org.eclipse.jgit.treewalk.filter.TreeFilter; import org.eclipse.jgit.treewalk.filter.TreeFilter;
/** /**
* Filter applying a {@link TreeFilter} against changed paths in each commit. * Filter applying a {@link org.eclipse.jgit.treewalk.filter.TreeFilter} against
* changed paths in each commit.
* <p> * <p>
* Each commit is differenced concurrently against all of its parents to look * Each commit is differenced concurrently against all of its parents to look
* for tree entries that are interesting to the {@link TreeFilter}. * for tree entries that are interesting to the
* {@link org.eclipse.jgit.treewalk.filter.TreeFilter}.
* *
* @since 3.5 * @since 3.5
*/ */
@ -76,14 +78,15 @@ public class TreeRevFilter extends RevFilter {
private final TreeWalk pathFilter; private final TreeWalk pathFilter;
/** /**
* Create a {@link RevFilter} from a {@link TreeFilter}. * Create a {@link org.eclipse.jgit.revwalk.filter.RevFilter} from a
* {@link org.eclipse.jgit.treewalk.filter.TreeFilter}.
* *
* @param walker * @param walker
* walker used for reading trees. * walker used for reading trees.
* @param t * @param t
* filter to compare against any changed paths in each commit. If a * filter to compare against any changed paths in each commit. If
* {@link FollowFilter}, will be replaced with a new filter * a {@link org.eclipse.jgit.revwalk.FollowFilter}, will be
* following new paths after a rename. * replaced with a new filter following new paths after a rename.
* @since 3.5 * @since 3.5
*/ */
public TreeRevFilter(final RevWalk walker, final TreeFilter t) { public TreeRevFilter(final RevWalk walker, final TreeFilter t) {
@ -121,11 +124,13 @@ public class TreeRevFilter extends RevFilter {
this.rewriteFlag = rewriteFlag; this.rewriteFlag = rewriteFlag;
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
throw new UnsupportedOperationException(); throw new UnsupportedOperationException();
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(final RevWalk walker, final RevCommit c) public boolean include(final RevWalk walker, final RevCommit c)
throws StopWalkException, MissingObjectException, throws StopWalkException, MissingObjectException,
@ -260,6 +265,7 @@ public class TreeRevFilter extends RevFilter {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean requiresCommitBody() { public boolean requiresCommitBody() {
return false; return false;

7
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AndRevFilter.java

@ -57,9 +57,10 @@ import org.eclipse.jgit.revwalk.RevWalk;
* Includes a commit only if all subfilters include the same commit. * Includes a commit only if all subfilters include the same commit.
* <p> * <p>
* Classic shortcut behavior is used, so evaluation of the * Classic shortcut behavior is used, so evaluation of the
* {@link RevFilter#include(RevWalk, RevCommit)} method stops as soon as a false * {@link org.eclipse.jgit.revwalk.filter.RevFilter#include(RevWalk, RevCommit)}
* result is obtained. Applications can improve filtering performance by placing * method stops as soon as a false result is obtained. Applications can improve
* faster filters that are more likely to reject a result earlier in the list. * filtering performance by placing faster filters that are more likely to
* reject a result earlier in the list.
*/ */
public abstract class AndRevFilter extends RevFilter { public abstract class AndRevFilter extends RevFilter {
/** /**

4
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AuthorRevFilter.java

@ -50,7 +50,9 @@ import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawCharSequence;
import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.RawParseUtils;
/** Matches only commits whose author name matches the pattern. */ /**
* Matches only commits whose author name matches the pattern.
*/
public class AuthorRevFilter { public class AuthorRevFilter {
/** /**
* Create a new author filter. * Create a new author filter.

6
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitTimeRevFilter.java

@ -53,7 +53,9 @@ import org.eclipse.jgit.errors.StopWalkException;
import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.revwalk.RevWalk; import org.eclipse.jgit.revwalk.RevWalk;
/** Selects commits based upon the commit time field. */ /**
* Selects commits based upon the commit time field.
*/
public abstract class CommitTimeRevFilter extends RevFilter { public abstract class CommitTimeRevFilter extends RevFilter {
/** /**
* Create a new filter to select commits before a given date/time. * Create a new filter to select commits before a given date/time.
@ -129,11 +131,13 @@ public abstract class CommitTimeRevFilter extends RevFilter {
when = (int) (ts / 1000); when = (int) (ts / 1000);
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
return this; return this;
} }
/** {@inheritDoc} */
@Override @Override
public boolean requiresCommitBody() { public boolean requiresCommitBody() {
return false; return false;

4
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitterRevFilter.java

@ -50,7 +50,9 @@ import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawCharSequence;
import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.RawParseUtils;
/** Matches only commits whose committer name matches the pattern. */ /**
* Matches only commits whose committer name matches the pattern.
*/
public class CommitterRevFilter { public class CommitterRevFilter {
/** /**
* Create a new committer filter. * Create a new committer filter.

2
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MaxCountRevFilter.java

@ -79,6 +79,7 @@ public class MaxCountRevFilter extends RevFilter {
this.maxCount = maxCount; this.maxCount = maxCount;
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(RevWalk walker, RevCommit cmit) public boolean include(RevWalk walker, RevCommit cmit)
throws StopWalkException, MissingObjectException, throws StopWalkException, MissingObjectException,
@ -89,6 +90,7 @@ public class MaxCountRevFilter extends RevFilter {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
return new MaxCountRevFilter(maxCount); return new MaxCountRevFilter(maxCount);

4
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MessageRevFilter.java

@ -50,7 +50,9 @@ import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawCharSequence;
import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.RawParseUtils;
/** Matches only commits whose message matches the pattern. */ /**
* Matches only commits whose message matches the pattern.
*/
public class MessageRevFilter { public class MessageRevFilter {
/** /**
* Create a message filter. * Create a message filter.

9
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/NotRevFilter.java

@ -50,7 +50,9 @@ import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.revwalk.RevWalk; import org.eclipse.jgit.revwalk.RevWalk;
/** Includes a commit only if the subfilter does not include the commit. */ /**
* Includes a commit only if the subfilter does not include the commit.
*/
public class NotRevFilter extends RevFilter { public class NotRevFilter extends RevFilter {
/** /**
* Create a filter that negates the result of another filter. * Create a filter that negates the result of another filter.
@ -69,11 +71,13 @@ public class NotRevFilter extends RevFilter {
a = one; a = one;
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter negate() { public RevFilter negate() {
return a; return a;
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(final RevWalk walker, final RevCommit c) public boolean include(final RevWalk walker, final RevCommit c)
throws MissingObjectException, IncorrectObjectTypeException, throws MissingObjectException, IncorrectObjectTypeException,
@ -81,16 +85,19 @@ public class NotRevFilter extends RevFilter {
return !a.include(walker, c); return !a.include(walker, c);
} }
/** {@inheritDoc} */
@Override @Override
public boolean requiresCommitBody() { public boolean requiresCommitBody() {
return a.requiresCommitBody(); return a.requiresCommitBody();
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
return new NotRevFilter(a.clone()); return new NotRevFilter(a.clone());
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return "NOT " + a.toString(); //$NON-NLS-1$ return "NOT " + a.toString(); //$NON-NLS-1$

9
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/ObjectFilter.java

@ -54,7 +54,8 @@ import org.eclipse.jgit.revwalk.ObjectWalk;
* Selects interesting objects when walking. * Selects interesting objects when walking.
* <p> * <p>
* Applications should install the filter on an ObjectWalk by * Applications should install the filter on an ObjectWalk by
* {@link ObjectWalk#setObjectFilter(ObjectFilter)} prior to starting traversal. * {@link org.eclipse.jgit.revwalk.ObjectWalk#setObjectFilter(ObjectFilter)}
* prior to starting traversal.
* *
* @since 4.0 * @since 4.0
*/ */
@ -77,13 +78,13 @@ public abstract class ObjectFilter {
* @param objid * @param objid
* the object currently being tested. * the object currently being tested.
* @return {@code true} if the named object should be included in the walk. * @return {@code true} if the named object should be included in the walk.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* an object the filter needed to consult to determine its * an object the filter needed to consult to determine its
* answer was missing * answer was missing
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* an object the filter needed to consult to determine its * an object the filter needed to consult to determine its
* answer was of the wrong type * answer was of the wrong type
* @throws IOException * @throws java.io.IOException
* an object the filter needed to consult to determine its * an object the filter needed to consult to determine its
* answer could not be read. * answer could not be read.
*/ */

7
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/OrRevFilter.java

@ -57,9 +57,10 @@ import org.eclipse.jgit.revwalk.RevWalk;
* Includes a commit if any subfilters include the same commit. * Includes a commit if any subfilters include the same commit.
* <p> * <p>
* Classic shortcut behavior is used, so evaluation of the * Classic shortcut behavior is used, so evaluation of the
* {@link RevFilter#include(RevWalk, RevCommit)} method stops as soon as a true * {@link org.eclipse.jgit.revwalk.filter.RevFilter#include(RevWalk, RevCommit)}
* result is obtained. Applications can improve filtering performance by placing * method stops as soon as a true result is obtained. Applications can improve
* faster filters that are more likely to accept a result earlier in the list. * filtering performance by placing faster filters that are more likely to
* accept a result earlier in the list.
*/ */
public abstract class OrRevFilter extends RevFilter { public abstract class OrRevFilter extends RevFilter {
/** /**

12
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/PatternMatchRevFilter.java

@ -56,7 +56,9 @@ import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.revwalk.RevWalk; import org.eclipse.jgit.revwalk.RevWalk;
import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawCharSequence;
/** Abstract filter that searches text using extended regular expressions. */ /**
* Abstract filter that searches text using extended regular expressions.
*/
public abstract class PatternMatchRevFilter extends RevFilter { public abstract class PatternMatchRevFilter extends RevFilter {
/** /**
* Encode a string pattern for faster matching on byte arrays. * Encode a string pattern for faster matching on byte arrays.
@ -69,7 +71,7 @@ public abstract class PatternMatchRevFilter extends RevFilter {
* original pattern string supplied by the user or the * original pattern string supplied by the user or the
* application. * application.
* @return same pattern, but re-encoded to match our funny raw UTF-8 * @return same pattern, but re-encoded to match our funny raw UTF-8
* character sequence {@link RawCharSequence}. * character sequence {@link org.eclipse.jgit.util.RawCharSequence}.
*/ */
protected static final String forceToRaw(final String patternText) { protected static final String forceToRaw(final String patternText) {
final byte[] b = Constants.encode(patternText); final byte[] b = Constants.encode(patternText);
@ -97,7 +99,8 @@ public abstract class PatternMatchRevFilter extends RevFilter {
* should {@link #forceToRaw(String)} be applied to the pattern * should {@link #forceToRaw(String)} be applied to the pattern
* before compiling it? * before compiling it?
* @param flags * @param flags
* flags from {@link Pattern} to control how matching performs. * flags from {@link java.util.regex.Pattern} to control how
* matching performs.
*/ */
protected PatternMatchRevFilter(String pattern, final boolean innerString, protected PatternMatchRevFilter(String pattern, final boolean innerString,
final boolean rawEncoding, final int flags) { final boolean rawEncoding, final int flags) {
@ -124,6 +127,7 @@ public abstract class PatternMatchRevFilter extends RevFilter {
return patternText; return patternText;
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(final RevWalk walker, final RevCommit cmit) public boolean include(final RevWalk walker, final RevCommit cmit)
throws MissingObjectException, IncorrectObjectTypeException, throws MissingObjectException, IncorrectObjectTypeException,
@ -131,6 +135,7 @@ public abstract class PatternMatchRevFilter extends RevFilter {
return compiledPattern.reset(text(cmit)).matches(); return compiledPattern.reset(text(cmit)).matches();
} }
/** {@inheritDoc} */
@Override @Override
public boolean requiresCommitBody() { public boolean requiresCommitBody() {
return true; return true;
@ -145,6 +150,7 @@ public abstract class PatternMatchRevFilter extends RevFilter {
*/ */
protected abstract CharSequence text(RevCommit cmit); protected abstract CharSequence text(RevCommit cmit);
/** {@inheritDoc} */
@SuppressWarnings("nls") @SuppressWarnings("nls")
@Override @Override
public String toString() { public String toString() {

37
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFilter.java

@ -61,7 +61,8 @@ import org.eclipse.jgit.revwalk.RevWalk;
* <code>OrRevFilter</code> to create complex boolean expressions. * <code>OrRevFilter</code> to create complex boolean expressions.
* <p> * <p>
* Applications should install the filter on a RevWalk by * Applications should install the filter on a RevWalk by
* {@link RevWalk#setRevFilter(RevFilter)} prior to starting traversal. * {@link org.eclipse.jgit.revwalk.RevWalk#setRevFilter(RevFilter)} prior to
* starting traversal.
* <p> * <p>
* Unless specifically noted otherwise a RevFilter implementation is not thread * Unless specifically noted otherwise a RevFilter implementation is not thread
* safe and may not be shared by different RevWalk instances at the same time. * safe and may not be shared by different RevWalk instances at the same time.
@ -73,9 +74,12 @@ import org.eclipse.jgit.revwalk.RevWalk;
* <p> * <p>
* <b>Message filters:</b> * <b>Message filters:</b>
* <ul> * <ul>
* <li>Author name/email: {@link AuthorRevFilter}</li> * <li>Author name/email:
* <li>Committer name/email: {@link CommitterRevFilter}</li> * {@link org.eclipse.jgit.revwalk.filter.AuthorRevFilter}</li>
* <li>Message body: {@link MessageRevFilter}</li> * <li>Committer name/email:
* {@link org.eclipse.jgit.revwalk.filter.CommitterRevFilter}</li>
* <li>Message body:
* {@link org.eclipse.jgit.revwalk.filter.MessageRevFilter}</li>
* </ul> * </ul>
* *
* <p> * <p>
@ -88,9 +92,9 @@ import org.eclipse.jgit.revwalk.RevWalk;
* <p> * <p>
* <b>Boolean modifiers:</b> * <b>Boolean modifiers:</b>
* <ul> * <ul>
* <li>AND: {@link AndRevFilter}</li> * <li>AND: {@link org.eclipse.jgit.revwalk.filter.AndRevFilter}</li>
* <li>OR: {@link OrRevFilter}</li> * <li>OR: {@link org.eclipse.jgit.revwalk.filter.OrRevFilter}</li>
* <li>NOT: {@link NotRevFilter}</li> * <li>NOT: {@link org.eclipse.jgit.revwalk.filter.NotRevFilter}</li>
* </ul> * </ul>
*/ */
public abstract class RevFilter { public abstract class RevFilter {
@ -241,7 +245,11 @@ public abstract class RevFilter {
return NotRevFilter.create(this); return NotRevFilter.create(this);
} }
/** @return true if the filter needs the commit body to be parsed. */ /**
* Whether the filter needs the commit body to be parsed.
*
* @return true if the filter needs the commit body to be parsed.
*/
public boolean requiresCommitBody() { public boolean requiresCommitBody() {
// Assume true to be backward compatible with prior behavior. // Assume true to be backward compatible with prior behavior.
return true; return true;
@ -258,19 +266,19 @@ public abstract class RevFilter {
* returns true from {@link #requiresCommitBody()}. * returns true from {@link #requiresCommitBody()}.
* @return true to include this commit in the results; false to have this * @return true to include this commit in the results; false to have this
* commit be omitted entirely from the results. * commit be omitted entirely from the results.
* @throws StopWalkException * @throws org.eclipse.jgit.errors.StopWalkException
* the filter knows for certain that no additional commits can * the filter knows for certain that no additional commits can
* ever match, and the current commit doesn't match either. The * ever match, and the current commit doesn't match either. The
* walk is halted and no more results are provided. * walk is halted and no more results are provided.
* @throws MissingObjectException * @throws org.eclipse.jgit.errors.MissingObjectException
* an object the filter needs to consult to determine its answer * an object the filter needs to consult to determine its answer
* does not exist in the Git repository the walker is operating * does not exist in the Git repository the walker is operating
* on. Filtering this commit is impossible without the object. * on. Filtering this commit is impossible without the object.
* @throws IncorrectObjectTypeException * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
* an object the filter needed to consult was not of the * an object the filter needed to consult was not of the
* expected object type. This usually indicates a corrupt * expected object type. This usually indicates a corrupt
* repository, as an object link is referencing the wrong type. * repository, as an object link is referencing the wrong type.
* @throws IOException * @throws java.io.IOException
* a loose object or pack file could not be read to obtain data * a loose object or pack file could not be read to obtain data
* necessary for the filter to make its decision. * necessary for the filter to make its decision.
*/ */
@ -279,16 +287,17 @@ public abstract class RevFilter {
IncorrectObjectTypeException, IOException; IncorrectObjectTypeException, IOException;
/** /**
* {@inheritDoc}
* <p>
* Clone this revision filter, including its parameters. * Clone this revision filter, including its parameters.
* <p> * <p>
* This is a deep clone. If this filter embeds objects or other filters it * This is a deep clone. If this filter embeds objects or other filters it
* must also clone those, to ensure the instances do not share mutable data. * must also clone those, to ensure the instances do not share mutable data.
*
* @return another copy of this filter, suitable for another thread.
*/ */
@Override @Override
public abstract RevFilter clone(); public abstract RevFilter clone();
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
String n = getClass().getName(); String n = getClass().getName();

6
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFlagFilter.java

@ -52,7 +52,9 @@ import org.eclipse.jgit.revwalk.RevFlag;
import org.eclipse.jgit.revwalk.RevFlagSet; import org.eclipse.jgit.revwalk.RevFlagSet;
import org.eclipse.jgit.revwalk.RevWalk; import org.eclipse.jgit.revwalk.RevWalk;
/** Matches only commits with some/all RevFlags already set. */ /**
* Matches only commits with some/all RevFlags already set.
*/
public abstract class RevFlagFilter extends RevFilter { public abstract class RevFlagFilter extends RevFilter {
/** /**
* Create a new filter that tests for a single flag. * Create a new filter that tests for a single flag.
@ -123,11 +125,13 @@ public abstract class RevFlagFilter extends RevFilter {
flags = m; flags = m;
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
return this; return this;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return super.toString() + flags; return super.toString() + flags;

2
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SkipRevFilter.java

@ -78,6 +78,7 @@ public class SkipRevFilter extends RevFilter {
this.skip = skip; this.skip = skip;
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(RevWalk walker, RevCommit cmit) public boolean include(RevWalk walker, RevCommit cmit)
throws StopWalkException, MissingObjectException, throws StopWalkException, MissingObjectException,
@ -87,6 +88,7 @@ public class SkipRevFilter extends RevFilter {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
return new SkipRevFilter(skip); return new SkipRevFilter(skip);

11
org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SubStringRevFilter.java

@ -52,7 +52,9 @@ import org.eclipse.jgit.revwalk.RevWalk;
import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawCharSequence;
import org.eclipse.jgit.util.RawSubStringPattern; import org.eclipse.jgit.util.RawSubStringPattern;
/** Abstract filter that searches text using only substring search. */ /**
* Abstract filter that searches text using only substring search.
*/
public abstract class SubStringRevFilter extends RevFilter { public abstract class SubStringRevFilter extends RevFilter {
/** /**
* Can this string be safely handled by a substring filter? * Can this string be safely handled by a substring filter?
@ -60,7 +62,8 @@ public abstract class SubStringRevFilter extends RevFilter {
* @param pattern * @param pattern
* the pattern text proposed by the user. * the pattern text proposed by the user.
* @return true if a substring filter can perform this pattern match; false * @return true if a substring filter can perform this pattern match; false
* if {@link PatternMatchRevFilter} must be used instead. * if {@link org.eclipse.jgit.revwalk.filter.PatternMatchRevFilter}
* must be used instead.
*/ */
public static boolean safe(final String pattern) { public static boolean safe(final String pattern) {
for (int i = 0; i < pattern.length(); i++) { for (int i = 0; i < pattern.length(); i++) {
@ -97,6 +100,7 @@ public abstract class SubStringRevFilter extends RevFilter {
pattern = new RawSubStringPattern(patternText); pattern = new RawSubStringPattern(patternText);
} }
/** {@inheritDoc} */
@Override @Override
public boolean include(final RevWalk walker, final RevCommit cmit) public boolean include(final RevWalk walker, final RevCommit cmit)
throws MissingObjectException, IncorrectObjectTypeException, throws MissingObjectException, IncorrectObjectTypeException,
@ -104,6 +108,7 @@ public abstract class SubStringRevFilter extends RevFilter {
return pattern.match(text(cmit)) >= 0; return pattern.match(text(cmit)) >= 0;
} }
/** {@inheritDoc} */
@Override @Override
public boolean requiresCommitBody() { public boolean requiresCommitBody() {
return true; return true;
@ -118,11 +123,13 @@ public abstract class SubStringRevFilter extends RevFilter {
*/ */
protected abstract RawCharSequence text(RevCommit cmit); protected abstract RawCharSequence text(RevCommit cmit);
/** {@inheritDoc} */
@Override @Override
public RevFilter clone() { public RevFilter clone() {
return this; // Typically we are actually thread-safe. return this; // Typically we are actually thread-safe.
} }
/** {@inheritDoc} */
@SuppressWarnings("nls") @SuppressWarnings("nls")
@Override @Override
public String toString() { public String toString() {

Loading…
Cancel
Save