Top Description Inners Fields Constructors Methods
org.eclipse.jgit.revwalk

public Class ObjectWalk

extends RevWalk
Class Inheritance
Known Direct Subclasses
org.eclipse.jgit.revwalk.DepthWalk.ObjectWalk
Static Imports
java.util.Objects.requireNonNull, org.eclipse.jgit.lib.Constants.OBJ_BLOB, .Constants.OBJ_COMMIT, .Constants.OBJ_TREE

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 commits that reference them and the order they appear within a tree. Ordering can be affected by changing the org.eclipse.jgit.revwalk.RevSort used to order the commits that are returned first.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
public static interface
ObjectWalk.VisitationPolicy

When walking over a tree and blob graph, objects are usually marked as seen as they are visited and this "seen" status is checked upon the next visit.

Field Summary

Modifier and TypeField and Description
private boolean
private ObjectWalk.TreeVisit
private ObjectWalk.TreeVisit
private static final int
private static final int
IN_PENDING

Indicates a non-RevCommit is in pendingObjects.

private ObjectFilter
private byte[]
private int
private BlockObjQueue
private List<RevObject>
public static final ObjectWalk.VisitationPolicy
SIMPLE_VISITATION_POLICY

The default visitation policy: causes all objects to be visited exactly once.

private static final int
private static final int
private static final int
private static final int
private static final int
private ObjectWalk.VisitationPolicy
Inherited from org.eclipse.jgit.revwalk.RevWalk:
carryFlagsfreeFlagsidBufferobjectsPARSEDpendingqueuereaderRESERVED_FLAGSREWRITErootsSEENshallowCommitsInitializedTEMP_MARKTOPO_DELAYTOPO_QUEUEDTREE_REV_FILTER_APPLIEDUNINTERESTING

Constructor Summary

AccessConstructor and Description
public
ObjectWalk(Repository
the repository the walker will obtain data from.
repo
)

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

public
ObjectWalk(ObjectReader
the reader the walker will obtain data from. The reader should be released by the caller when the walker is no longer required.
or
)

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

private
ObjectWalk(ObjectReader or, boolean closeReader)

Method Summary

Modifier and TypeMethod and Description
private void
public void
checkConnectivity()

Verify all interesting objects are available, and reachable.

public void
dispose()

Overrides org.eclipse.jgit.revwalk.RevWalk.dispose.

Dispose all internal state and invalidate all RevObject instances.

private static int
findObjectId(byte[] buf, int ptr)

public ObjectFilter

Returns:

the current filter. Never null as a filter is always needed.
getObjectFilter
()

Get the currently configured object filter.

public byte[]

Returns:

the internal buffer holding the current path.
getPathBuffer
()

Get the internal buffer holding the current path.

public int

Returns:

path hash code; any integer may be returned.
getPathHashCode
()

Get the current object's path hash code.

public int

Returns:

length of the path in getPathBuffer().
getPathLength
()

Get length of the path in getPathBuffer().

public String

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.
getPathString
()

Get the current object's complete path.

public int

Returns:

the current traversal depth from the root tree object
getTreeDepth
()

Get the current traversal depth from the root tree object

private void
growPathBuf(int ptr)

public void
markStart(RevObject
the object to start traversing from. The object passed must be from this same revision walker.
o
)

Mark an object or commit to start graph traversal from.

private void
public void
markUninteresting(RevObject
the object to start traversing from. The object passed must be
o
)

Mark an object to not produce in the output.

public RevCommit
next()

Overrides org.eclipse.jgit.revwalk.RevWalk.next.

Pop the next most recent commit.

public RevObject

Returns:

next most recent object; null if traversal is over.
nextObject
()

Pop the next most recent object.

private static int
parseMode(byte[] buf, int startPtr, int recEndPtr, ObjectWalk.TreeVisit tv)

private RevObject
private void
protected void
reset(int
application flags that should not be cleared from existing commit objects.
retainFlags
)

Overrides org.eclipse.jgit.revwalk.RevWalk.reset.

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

public void
setObjectFilter(ObjectFilter
the new filter. If null the special org.eclipse.jgit.revwalk.filter.ObjectFilter#ALL filter will be used instead, as it matches every object.
newFilter
)

Set the object filter for this walker.

public void
setVisitationPolicy(ObjectWalk.VisitationPolicy
the VisitationPolicy to use
policy
)

Sets the visitation policy to use during this walk.

public void
skipTree()

Skips the current tree such that nextObject() does not return any objects inside it.

public void
sort(RevSort
a sorting strategy to enable.
s
)

Overrides org.eclipse.jgit.revwalk.RevWalk.sort.

Select a single sorting strategy for the returned commits.

public void
sort(RevSort
a sorting strategy to enable or disable.
s
,
boolean
true if this strategy should be used, false if it should be removed.
use
)

Overrides org.eclipse.jgit.revwalk.RevWalk.sort.

Add or remove a sorting strategy for the returned commits.

private int
Inherited from org.eclipse.jgit.revwalk.RevWalk:
allocFlagassertNoCommitsMarkedStartassertNotStartedassumeShallowcarrycarrycarryFlagsImplclosecommitGraphcreateCommitdisposeFlagfreeFlaggetCachedBytesgetCachedBytesgetMergedIntogetMergedIntogetObjectReadergetRevFiltergetRevSortgetRewriteParentsgetTreeFilterhasRevSortinitializeShallowCommitsisFirstParentisMergedIntoisMergedIntoAllisMergedIntoAnyisMergedIntoAnyCommitisRetainBodyiteratorlookupAnylookupBloblookupCommitlookupCommitlookupOrNulllookupTaglookupTreemarkStartmarkStartmarkUninterestingnewDateRevQueuenewDateRevQueuenewFlagparseAnyparseAnyparseBodyparseCommitparseHeadersparseTagparseTreepeelresetresetRetainresetRetainretainOnResetretainOnResetsetFirstParentsetRetainBodysetRevFiltersetRewriteParentssetTreeFiltertoObjectWalkWithSameObjects

Field Detail

boundaryback to summary
private boolean boundary
currVisitback to summary
private ObjectWalk.TreeVisit currVisit
freeVisitback to summary
private ObjectWalk.TreeVisit freeVisit
ID_SZback to summary
private static final int ID_SZ
IN_PENDINGback to summary
private static final int IN_PENDING

Indicates a non-RevCommit is in pendingObjects.

We can safely reuse RevWalk#REWRITE here for the same value as it is only set on RevCommit and pendingObjects never has RevCommit instances inserted into it.

objectFilterback to summary
private ObjectFilter objectFilter
pathBufback to summary
private byte[] pathBuf
pathLenback to summary
private int pathLen
pendingObjectsback to summary
private BlockObjQueue pendingObjects
rootObjectsback to summary
private List<RevObject> rootObjects
SIMPLE_VISITATION_POLICYback to summary
public static final ObjectWalk.VisitationPolicy SIMPLE_VISITATION_POLICY

The default visitation policy: causes all objects to be visited exactly once.

Since
5.4
TYPE_FILEback to summary
private static final int TYPE_FILE
TYPE_SHIFTback to summary
private static final int TYPE_SHIFT
TYPE_TREEback to summary
private static final int TYPE_TREE
visitationPolicyback to summary
private ObjectWalk.VisitationPolicy visitationPolicy

Constructor Detail

ObjectWalkback to summary
public ObjectWalk(Repository repo)

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

Parameters
repo:Repository

the repository the walker will obtain data from.

ObjectWalkback to summary
public ObjectWalk(ObjectReader or)

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

Parameters
or:ObjectReader

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

ObjectWalkback to summary
private ObjectWalk(ObjectReader or, boolean closeReader)

Method Detail

addObjectback to summary
private void addObject(RevObject o)
checkConnectivityback to summary
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.

Exceptions
MissingObjectException:
one 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 more of the objects in a tree do not match the type indicated.
IOException:
a pack file or loose object could not be read.
disposeback to summary
public void dispose()

Overrides org.eclipse.jgit.revwalk.RevWalk.dispose.

Doc from org.eclipse.jgit.revwalk.RevWalk.dispose.

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.

Annotations
@Override
findObjectIdback to summary
private static int findObjectId(byte[] buf, int ptr)
getObjectFilterback to summary
public ObjectFilter getObjectFilter()

Get the currently configured object filter.

Returns:ObjectFilter

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

Since
4.0
getPathBufferback to summary
public byte[] getPathBuffer()

Get the internal buffer holding the current path.

Returns:byte[]

the internal buffer holding the current path.

getPathHashCodeback to summary
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:int

path hash code; any integer may be returned.

getPathLengthback to summary
public int getPathLength()

Get length of the path in getPathBuffer().

Returns:int

length of the path in getPathBuffer().

getPathStringback to summary
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:String

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.

getTreeDepthback to summary
public int getTreeDepth()

Get the current traversal depth from the root tree object

Returns:int

the current traversal depth from the root tree object

Since
5.4
growPathBufback to summary
private void growPathBuf(int ptr)
markStartback to summary
public void markStart(RevObject o) throws MissingObjectException, IncorrectObjectTypeException, IOException

Mark an object or commit to start graph traversal from.

Callers are encouraged to use org.eclipse.jgit.revwalk.RevWalk#parseAny(AnyObjectId) instead of org.eclipse.jgit.revwalk.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 org.eclipse.jgit.revwalk.RevWalk#markStart(RevCommit) if passed RevCommit instance, or a RevTag that directly (or indirectly) references a RevCommit.

Parameters
o:RevObject

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

Exceptions
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 org.eclipse.jgit.revwalk.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 org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int) call.
IOException:
a pack file or loose object could not be read.
markTreeUninterestingback to summary
private void markTreeUninteresting(RevTree tree) throws MissingObjectException, IncorrectObjectTypeException, IOException
markUninterestingback to summary
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 org.eclipse.jgit.revwalk.RevWalk#parseAny(AnyObjectId) instead of org.eclipse.jgit.revwalk.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 org.eclipse.jgit.revwalk.RevWalk#markStart(RevCommit) if passed RevCommit instance, or a RevTag that directly (or indirectly) references a RevCommit.

Parameters
o:RevObject

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

Exceptions
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 org.eclipse.jgit.revwalk.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 org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int) call.
IOException:
a pack file or loose object could not be read.
nextback to summary
public RevCommit next() throws MissingObjectException, IncorrectObjectTypeException, IOException

Overrides org.eclipse.jgit.revwalk.RevWalk.next.

Doc from org.eclipse.jgit.revwalk.RevWalk.next.

Pop the next most recent commit.

Returns:RevCommit

next most recent commit; null if traversal is over.

Annotations
@Override
Exceptions
MissingObjectException:
one 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 more of the next commit's parents are not actually commit objects.
IOException:
a pack file or loose object could not be read.
nextObjectback to summary
public RevObject nextObject() throws MissingObjectException, IncorrectObjectTypeException, IOException

Pop the next most recent object.

Returns:RevObject

next most recent object; null if traversal is over.

Exceptions
MissingObjectException:
one 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 more of the objects in a tree do not match the type indicated.
IOException:
a pack file or loose object could not be read.
parseModeback to summary
private static int parseMode(byte[] buf, int startPtr, int recEndPtr, ObjectWalk.TreeVisit tv)
pushTreeback to summary
private RevObject pushTree(RevObject obj) throws LargeObjectException, MissingObjectException, IncorrectObjectTypeException, IOException
releaseTreeVisitback to summary
private void releaseTreeVisit(ObjectWalk.TreeVisit tv)
resetback to summary
protected void reset(int retainFlags)

Overrides org.eclipse.jgit.revwalk.RevWalk.reset.

Doc from org.eclipse.jgit.revwalk.RevWalk.reset.

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

Unlike dispose() previously acquired RevObject (and RevCommit) instances are not invalidated. RevFlag instances are not invalidated, but are removed from all RevObjects. The value of firstParent is retained.

Parameters
retainFlags:int

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

Annotations
@Override
setObjectFilterback to summary
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:ObjectFilter

the new filter. If null the special org.eclipse.jgit.revwalk.filter.ObjectFilter#ALL filter will be used instead, as it matches every object.

Since
4.0
setVisitationPolicyback to summary
public void setVisitationPolicy(ObjectWalk.VisitationPolicy policy)

Sets the visitation policy to use during this walk.

Parameters
policy:ObjectWalk.VisitationPolicy

the VisitationPolicy to use

Since
5.4
skipTreeback to summary
public void skipTree()

Skips the current tree such that nextObject() does not return any objects inside it. This should be called right after nextObject() returns the tree.

Since
5.4
sortback to summary
public void sort(RevSort s)

Overrides org.eclipse.jgit.revwalk.RevWalk.sort.

Doc from org.eclipse.jgit.revwalk.RevWalk.sort.

Select a single sorting strategy for the returned commits.

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

Parameters
s:RevSort

a sorting strategy to enable.

Annotations
@Override
sortback to summary
public void sort(RevSort s, boolean use)

Overrides org.eclipse.jgit.revwalk.RevWalk.sort.

Doc from org.eclipse.jgit.revwalk.RevWalk.sort.

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, org.eclipse.jgit.revwalk.RevSort#TOPO must take precedence over org.eclipse.jgit.revwalk.RevSort#COMMIT_TIME_DESC, otherwise it cannot enforce its ordering.

Parameters
s:RevSort

a sorting strategy to enable or disable.

use:boolean

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

Annotations
@Override
updatePathBufback to summary
private int updatePathBuf(ObjectWalk.TreeVisit tv)
org.eclipse.jgit.revwalk back to summary

private Class ObjectWalk.TreeVisit

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
pack-priv byte[]
buf

Canonical encoding of the tree named by obj.

pack-priv int
depth

Number of levels deep from the root tree.

pack-priv int
nameEnd

One past end of name, nameEnd - namePtr is the length.

pack-priv int
namePtr

Start of the current name entry in buf.

pack-priv RevObject
obj

The RevTree currently being iterated through.

pack-priv ObjectWalk.TreeVisit
parent

Parent tree visit that entered this tree, null if root tree.

pack-priv int
pathLen

Number of bytes in the path leading up to this tree.

pack-priv int
ptr

Index of next entry to parse in buf.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

bufback to summary
pack-priv byte[] buf

Canonical encoding of the tree named by obj.

depthback to summary
pack-priv int depth

Number of levels deep from the root tree. 0 for root tree.

nameEndback to summary
pack-priv int nameEnd

One past end of name, nameEnd - namePtr is the length.

namePtrback to summary
pack-priv int namePtr

Start of the current name entry in buf.

objback to summary
pack-priv RevObject obj

The RevTree currently being iterated through.

parentback to summary
pack-priv ObjectWalk.TreeVisit parent

Parent tree visit that entered this tree, null if root tree.

pathLenback to summary
pack-priv int pathLen

Number of bytes in the path leading up to this tree.

ptrback to summary
pack-priv int ptr

Index of next entry to parse in buf.

Constructor Detail

TreeVisitback to summary
private TreeVisit()
org.eclipse.jgit.revwalk back to summary

public Interface ObjectWalk.VisitationPolicy

Known Direct Implementers
org.eclipse.jgit.internal.storage.pack.PackWriter.DepthAwareVisitationPolicy

When walking over a tree and blob graph, objects are usually marked as seen as they are visited and this "seen" status is checked upon the next visit. If they are already "seen" then they are not processed (returned by ObjectWalk#nextObject()) again. However, this behavior can be overridden by supplying a different implementation of this class.
Since
5.4

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the object should be visited
shouldVisit
(RevObject
the object to check if it should be visited
o
)

Whenever the rev or object walk reaches a Git object, if that object already exists as a RevObject, this method is called to determine if that object should be visited.

public void
visited(RevObject
the object that was visited
o
)

Called when an object is visited.

Method Detail

shouldVisitback to summary
public boolean shouldVisit(RevObject o)

Whenever the rev or object walk reaches a Git object, if that object already exists as a RevObject, this method is called to determine if that object should be visited.

Parameters
o:RevObject

the object to check if it should be visited

Returns:boolean

true if the object should be visited

visitedback to summary
public void visited(RevObject o)

Called when an object is visited.

Parameters
o:RevObject

the object that was visited