org.eclipse.jgit.revwalk

Class ObjectWalk

java.lang.Object

org.eclipse.jgit.revwalk.RevWalk

org.eclipse.jgit.revwalk.ObjectWalk

All Implemented Interfaces:

AutoCloseable, Iterable<RevCommit>

Direct Known Subclasses:

DepthWalk.ObjectWalk

public class ObjectWalk
extends RevWalk

Specialized subclass of RevWalk to include trees, blobs and tags.

Unlike RevWalk this subclass is able to remember starting roots that include annotated tags, or arbitrary trees or blobs. Once commit generation is complete and all commits have been popped by the application, individual annotated tag, tree and blob objects can be popped through the additional method nextObject().

Tree and blob objects reachable from interesting commits are automatically scheduled for inclusion in the results of nextObject(), returning 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. Ordering can be affected by changing the RevSort used to order the commits that are returned first.

Constructor Summary

Constructors

Constructor and Description
ObjectWalk(ObjectReader or) Create a new revision and object walker for a given repository.
ObjectWalk(Repository repo) Create a new revision and object walker for a given repository.

Method Summary

Methods

Modifier and Type	Method and Description
void	checkConnectivity() Verify all interesting objects are available, and reachable.
void	dispose() Dispose all internal state and invalidate all RevObject instances.
ObjectFilter	getObjectFilter() Get the currently configured object filter.
byte[]	getPathBuffer()
int	getPathHashCode() Get the current object's path hash code.
int	getPathLength()
String	getPathString() Get the current object's complete path.
void	markStart(RevObject o) Mark an object or commit to start graph traversal from.
void	markUninteresting(RevObject o) Mark an object to not produce in the output.
RevCommit	next() Pop the next most recent commit.
RevObject	nextObject() Pop the next most recent object.
protected void	reset(int retainFlags) Resets internal state and allows this instance to be used again.
void	setObjectFilter(ObjectFilter newFilter) Set the object filter for this walker.
void	sort(RevSort s) Select a single sorting strategy for the returned commits.
void	sort(RevSort s, boolean use) Add or remove a sorting strategy for the returned commits.

Methods inherited from class org.eclipse.jgit.revwalk.RevWalk

assertNotStarted, assumeShallow, carry, carry, close, createCommit, disposeFlag, getObjectReader, getRevFilter, getRevSort, getTreeFilter, hasRevSort, isMergedInto, isRetainBody, iterator, lookupAny, lookupBlob, lookupCommit, lookupOrNull, lookupTag, lookupTree, markStart, markStart, markUninteresting, newFlag, parseAny, parseAny, parseBody, parseCommit, parseHeaders, parseTag, parseTree, peel, reset, resetRetain, resetRetain, retainOnReset, retainOnReset, setRetainBody, setRevFilter, setRewriteParents, setTreeFilter, toObjectWalkWithSameObjects

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectWalk

public ObjectWalk(Repository repo)

Create a new revision and object walker for a given repository.

Parameters:

repo - the repository the walker will obtain data from.

ObjectWalk

public ObjectWalk(ObjectReader or)

Create a new revision and object walker for a given repository.

Parameters:

or - the reader the walker will obtain data from. The reader should be released by the caller when the walker is no longer required.

Method Detail

markStart

public void markStart(RevObject o)
               throws MissingObjectException,
                      IncorrectObjectTypeException,
                      IOException

Mark an object or commit to start graph traversal from.

Callers are encouraged to use RevWalk.parseAny(AnyObjectId) instead of RevWalk.lookupAny(AnyObjectId, int), as this method requires the object to be parsed before it can be added as a root for the traversal.

The method will automatically parse an unparsed object, but error handling may be more difficult for the application to explain why a RevObject is not actually valid. The object pool of this walker would also be 'poisoned' by the invalid RevObject.

This method will automatically call RevWalk.markStart(RevCommit) if passed RevCommit instance, or a RevTag that directly (or indirectly) references a RevCommit.

Parameters:

o - the object to start traversing from. The object passed must be from this same revision walker.

Throws:

MissingObjectException - the object supplied is not available from the object database. This usually indicates the supplied object is invalid, but the reference was constructed during an earlier invocation to RevWalk.lookupAny(AnyObjectId, int).

IncorrectObjectTypeException - the object was not parsed yet and it was discovered during parsing that it is not actually the type of the instance passed in. This usually indicates the caller used the wrong type in a RevWalk.lookupAny(AnyObjectId, int) call.

IOException - a pack file or loose object could not be read.

markUninteresting

public void markUninteresting(RevObject o)
                       throws MissingObjectException,
                              IncorrectObjectTypeException,
                              IOException

Mark an object to not produce in the output.

Uninteresting objects denote not just themselves but also their entire reachable chain, back until the merge base of an uninteresting commit and an otherwise interesting commit.

Callers are encouraged to use RevWalk.parseAny(AnyObjectId) instead of RevWalk.lookupAny(AnyObjectId, int), as this method requires the object to be parsed before it can be added as a root for the traversal.

The method will automatically parse an unparsed object, but error handling may be more difficult for the application to explain why a RevObject is not actually valid. The object pool of this walker would also be 'poisoned' by the invalid RevObject.

This method will automatically call RevWalk.markStart(RevCommit) if passed RevCommit instance, or a RevTag that directly (or indirectly) references a RevCommit.

Parameters:

o - the object to start traversing from. The object passed must be

Throws:

MissingObjectException - the object supplied is not available from the object database. This usually indicates the supplied object is invalid, but the reference was constructed during an earlier invocation to RevWalk.lookupAny(AnyObjectId, int).

IncorrectObjectTypeException - the object was not parsed yet and it was discovered during parsing that it is not actually the type of the instance passed in. This usually indicates the caller used the wrong type in a RevWalk.lookupAny(AnyObjectId, int) call.

IOException - a pack file or loose object could not be read.

sort

public void sort(RevSort s)

Description copied from class: RevWalk

Select a single sorting strategy for the returned commits.

Disables all sorting strategies, then enables only the single strategy supplied by the caller.

Overrides:

sort in class RevWalk

Parameters:

s - a sorting strategy to enable.

sort

public void sort(RevSort s,
        boolean use)

Description copied from class: RevWalk

Add or remove a sorting strategy for the returned commits.

Multiple strategies can be applied at once, in which case some strategies may take precedence over others. As an example, RevSort.TOPO must take precedence over RevSort.COMMIT_TIME_DESC, otherwise it cannot enforce its ordering.

Overrides:

sort in class RevWalk

Parameters:

s - a sorting strategy to enable or disable.

use - true if this strategy should be used, false if it should be removed.

getObjectFilter

public ObjectFilter getObjectFilter()

Get the currently configured object filter.

Returns:

the current filter. Never null as a filter is always needed.

Since:

4.0

setObjectFilter

public void setObjectFilter(ObjectFilter newFilter)

Set the object filter for this walker. This filter affects the objects visited by nextObject(). It does not affect the commits listed by next().

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. This can be used to speed up the object walk by skipping subtrees that are known to be uninteresting.

Parameters:

newFilter - the new filter. If null the special ObjectFilter.ALL filter will be used instead, as it matches every object.

Since:

4.0

next

public RevCommit next()
               throws MissingObjectException,
                      IncorrectObjectTypeException,
                      IOException

Description copied from class: RevWalk

Pop the next most recent commit.

Overrides:

next in class RevWalk

Returns:

next most recent commit; null if traversal is over.

Throws:

MissingObjectException - one or or more of the next commit's parents are not available from the object database, but were thought to be candidates for traversal. This usually indicates a broken link.

IncorrectObjectTypeException - one or or more of the next commit's parents are not actually commit objects.

IOException - a pack file or loose object could not be read.

nextObject

public RevObject nextObject()
                     throws MissingObjectException,
                            IncorrectObjectTypeException,
                            IOException

Pop the next most recent object.

Returns:

next most recent object; null if traversal is over.

Throws:

MissingObjectException - one or or more of the next objects are not available from the object database, but were thought to be candidates for traversal. This usually indicates a broken link.

IncorrectObjectTypeException - one or or more of the objects in a tree do not match the type indicated.

IOException - a pack file or loose object could not be read.

checkConnectivity

public void checkConnectivity()
                       throws MissingObjectException,
                              IncorrectObjectTypeException,
                              IOException

Verify all interesting objects are available, and reachable.

Callers should populate starting points and ending points with markStart(RevObject) and markUninteresting(RevObject) and then use this method to verify all objects between those two points exist in the repository and are readable.

This method returns successfully if everything is connected; it throws an exception if there is a connectivity problem. The exception message provides some detail about the connectivity failure.

Throws:

MissingObjectException - one or or more of the next objects are not available from the object database, but were thought to be candidates for traversal. This usually indicates a broken link.

IncorrectObjectTypeException - one or or more of the objects in a tree do not match the type indicated.

IOException - a pack file or loose object could not be read.

getPathString

public String getPathString()

Get the current object's complete path.

This method is not very efficient and is primarily meant for debugging and final output generation. Applications should try to avoid calling it, and if invoked do so only once per interesting entry, where the name is absolutely required for correct function.

Returns:

complete path of the current entry, from the root of the repository. If the current entry is in a subtree there will be at least one '/' in the returned string. Null if the current entry has no path, such as for annotated tags or root level trees.

getPathHashCode

public int getPathHashCode()

Get the current object's path hash code.

This method computes a hash code on the fly for this path, the hash is suitable to cluster objects that may have similar paths together.

Returns:

path hash code; any integer may be returned.

getPathBuffer

public byte[] getPathBuffer()

Returns:

the internal buffer holding the current path.

getPathLength

public int getPathLength()

Returns:

length of the path in getPathBuffer().

dispose

public void dispose()

Description copied from class: RevWalk

Dispose all internal state and invalidate all RevObject instances.

All RevObject (and thus RevCommit, etc.) instances previously acquired from this RevWalk are invalidated by a dispose call. Applications must not retain or use RevObject instances obtained prior to the dispose call. All RevFlag instances are also invalidated, and must not be reused.

Overrides:

dispose in class RevWalk

reset

protected void reset(int retainFlags)

Description copied from class: RevWalk

Resets internal state and allows this instance to be used again.

Unlike RevWalk.dispose() previously acquired RevObject (and RevCommit) instances are not invalidated. RevFlag instances are not invalidated, but are removed from all RevObjects.

Overrides:

reset in class RevWalk

Parameters:

retainFlags - application flags that should not be cleared from existing commit objects.