org.eclipse.jgit.treewalk

Class TreeWalk

java.lang.Object

org.eclipse.jgit.treewalk.TreeWalk

Direct Known Subclasses:

NameConflictTreeWalk

public class TreeWalk
extends Object

Walks one or more AbstractTreeIterators in parallel.

This class can perform n-way differences across as many trees as necessary.

Each tree added must have the same root as existing trees in the walk.

A TreeWalk instance can only be used once to generate results. Running a second time requires creating a new TreeWalk instance, or invoking reset() and adding new trees before starting again. Resetting an existing instance may be faster for some applications as some internal buffers may be recycled.

TreeWalk instances are not thread-safe. Applications must either restrict usage of a TreeWalk instance to a single thread, or implement their own synchronization at a higher level.

Multiple simultaneous TreeWalk instances per Repository are permitted, even from concurrent threads.

Constructor Summary

Constructors

Constructor and Description
TreeWalk(ObjectReader or) Create a new tree walker for a given repository.
TreeWalk(Repository repo) Create a new tree walker for a given repository.

Method Summary

Methods

Modifier and Type	Method and Description
int	addTree(AbstractTreeIterator p) Add an already created tree iterator for walking.
int	addTree(AnyObjectId id) Add an already existing tree object for walking.
void	enterSubtree() Enter into the current subtree.
static TreeWalk	forPath(ObjectReader reader, String path, AnyObjectId... trees) Open a tree walk and filter to exactly one path.
static TreeWalk	forPath(Repository db, String path, AnyObjectId... trees) Open a tree walk and filter to exactly one path.
static TreeWalk	forPath(Repository db, String path, RevTree tree) Open a tree walk and filter to exactly one path.
int	getDepth() Get the current subtree depth of this walker.
FileMode	getFileMode(int nth) Obtain the FileMode for the current entry.
TreeFilter	getFilter() Get the currently configured filter.
String	getNameString() Get the current entry's name within its parent tree.
ObjectId	getObjectId(int nth) Obtain the ObjectId for the current entry.
void	getObjectId(MutableObjectId out, int nth) Obtain the ObjectId for the current entry.
ObjectReader	getObjectReader()
int	getPathLength()
String	getPathString() Get the current entry's complete path.
int	getRawMode(int nth) Obtain the raw FileMode bits for the current entry.
byte[]	getRawPath() Get the current entry's complete path as a UTF-8 byte array.
<T extends AbstractTreeIterator> T	getTree(int nth, Class<T> clazz) Obtain the tree iterator for the current entry.
int	getTreeCount() Get the number of trees known to this walker.
boolean	idEqual(int nthA, int nthB) Compare two tree's current ObjectId values for equality.
int	isPathPrefix(byte[] p, int pLen) Test if the supplied path matches the current entry's path.
boolean	isPathSuffix(byte[] p, int pLen) Test if the supplied path matches (being suffix of) the current entry's path.
boolean	isPostChildren() Is the current entry a subtree returned after its children?
boolean	isPostOrderTraversal() Does this walker return a tree entry after it exits the subtree?
boolean	isRecursive() Is this walker automatically entering into subtrees?
boolean	isSubtree() Is the current entry a subtree?
boolean	next() Advance this walker to the next relevant entry.
void	release() Release any resources used by this walker's reader.
void	reset() Reset this walker so new tree iterators can be added to it.
void	reset(AnyObjectId... ids) Reset this walker to run over a set of existing trees.
void	reset(AnyObjectId id) Reset this walker to run over a single existing tree.
void	setFilter(TreeFilter newFilter) Set the tree entry filter for this walker.
void	setPostOrderTraversal(boolean b) Set the walker to return trees after their children.
void	setRecursive(boolean b) Set the walker to enter (or not enter) subtrees automatically.

Methods inherited from class java.lang.Object

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

Constructor Detail

TreeWalk

public TreeWalk(Repository repo)

Create a new tree walker for a given repository.

Parameters:

repo - the repository the walker will obtain data from.

TreeWalk

public TreeWalk(ObjectReader or)

Create a new tree walker for a given repository.

Parameters:

or - the reader the walker will obtain tree data from.

Method Detail

forPath

public static TreeWalk forPath(ObjectReader reader,
               String path,
               AnyObjectId... trees)
                        throws MissingObjectException,
                               IncorrectObjectTypeException,
                               CorruptObjectException,
                               IOException

Open a tree walk and filter to exactly one path.

The returned tree walk is already positioned on the requested path, so the caller should not need to invoke next() unless they are looking for a possible directory/file name conflict.

Parameters:

reader - the reader the walker will obtain tree data from.

path - single path to advance the tree walk instance into.

trees - one or more trees to walk through, all with the same root.

Returns:

a new tree walk configured for exactly this one path; null if no path was found in any of the trees.

Throws:

IOException - reading a pack file or loose object failed.

CorruptObjectException - an tree object could not be read as its data stream did not appear to be a tree, or could not be inflated.

IncorrectObjectTypeException - an object we expected to be a tree was not a tree.

MissingObjectException - a tree object was not found.

forPath

public static TreeWalk forPath(Repository db,
               String path,
               AnyObjectId... trees)
                        throws MissingObjectException,
                               IncorrectObjectTypeException,
                               CorruptObjectException,
                               IOException

Open a tree walk and filter to exactly one path.

The returned tree walk is already positioned on the requested path, so the caller should not need to invoke next() unless they are looking for a possible directory/file name conflict.

Parameters:

db - repository to read tree object data from.

path - single path to advance the tree walk instance into.

trees - one or more trees to walk through, all with the same root.

Returns:

a new tree walk configured for exactly this one path; null if no path was found in any of the trees.

Throws:

IOException - reading a pack file or loose object failed.

CorruptObjectException - an tree object could not be read as its data stream did not appear to be a tree, or could not be inflated.

IncorrectObjectTypeException - an object we expected to be a tree was not a tree.

MissingObjectException - a tree object was not found.

forPath

public static TreeWalk forPath(Repository db,
               String path,
               RevTree tree)
                        throws MissingObjectException,
                               IncorrectObjectTypeException,
                               CorruptObjectException,
                               IOException

Open a tree walk and filter to exactly one path.

The returned tree walk is already positioned on the requested path, so the caller should not need to invoke next() unless they are looking for a possible directory/file name conflict.

Parameters:

db - repository to read tree object data from.

path - single path to advance the tree walk instance into.

tree - the single tree to walk through.

Returns:

a new tree walk configured for exactly this one path; null if no path was found in any of the trees.

Throws:

IOException - reading a pack file or loose object failed.

CorruptObjectException - an tree object could not be read as its data stream did not appear to be a tree, or could not be inflated.

IncorrectObjectTypeException - an object we expected to be a tree was not a tree.

MissingObjectException - a tree object was not found.

getObjectReader

public ObjectReader getObjectReader()

Returns:

the reader this walker is using to load objects.

release

public void release()

Release any resources used by this walker's reader.

A walker that has been released can be used again, but may need to be released after the subsequent usage.

getFilter

public TreeFilter getFilter()

Get the currently configured filter.

Returns:

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

setFilter

public void setFilter(TreeFilter newFilter)

Set the tree entry filter for this walker.

Multiple filters may be combined by constructing an arbitrary tree of AndTreeFilter or OrTreeFilter instances to describe the boolean expression required by the application. Custom filter implementations may also be constructed by applications.

Note that filters are not thread-safe and may not be shared by concurrent TreeWalk instances. Every TreeWalk must be supplied its own unique filter, unless the filter implementation specifically states it is (and always will be) thread-safe. Callers may use TreeFilter.clone() to create a unique filter tree for this TreeWalk instance.

Parameters:

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

See Also:

AndTreeFilter, OrTreeFilter

isRecursive

public boolean isRecursive()

Is this walker automatically entering into subtrees?

If the walker is recursive then the caller will not see a subtree node and instead will only receive file nodes in all relevant subtrees.

Returns:

true if automatically entering subtrees is enabled.

setRecursive

public void setRecursive(boolean b)

Set the walker to enter (or not enter) subtrees automatically.

If recursive mode is enabled the walker will hide subtree nodes from the calling application and will produce only file level nodes. If a tree (directory) is deleted then all of the file level nodes will appear to be deleted, recursively, through as many levels as necessary to account for all entries.

Parameters:

b - true to skip subtree nodes and only obtain files nodes.

isPostOrderTraversal

public boolean isPostOrderTraversal()

Does this walker return a tree entry after it exits the subtree?

If post order traversal is enabled then the walker will return a subtree after it has returned the last entry within that subtree. This may cause a subtree to be seen by the application twice if isRecursive() is false, as the application will see it once, call enterSubtree(), and then see it again as it leaves the subtree.

If an application does not enable isRecursive() and it does not call enterSubtree() then the tree is returned only once as none of the children were processed.

Returns:

true if subtrees are returned after entries within the subtree.

setPostOrderTraversal

public void setPostOrderTraversal(boolean b)

Set the walker to return trees after their children.

Parameters:

b - true to get trees after their children.

See Also:

isPostOrderTraversal()

reset

public void reset()

Reset this walker so new tree iterators can be added to it.

reset

public void reset(AnyObjectId id)
           throws MissingObjectException,
                  IncorrectObjectTypeException,
                  CorruptObjectException,
                  IOException

Reset this walker to run over a single existing tree.

Parameters:

id - the tree we need to parse. The walker will execute over this single tree if the reset is successful.

Throws:

MissingObjectException - the given tree object does not exist in this repository.

IncorrectObjectTypeException - the given object id does not denote a tree, but instead names some other non-tree type of object. Note that commits are not trees, even if they are sometimes called a "tree-ish".

CorruptObjectException - the object claimed to be a tree, but its contents did not appear to be a tree. The repository may have data corruption.

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

reset

public void reset(AnyObjectId... ids)
           throws MissingObjectException,
                  IncorrectObjectTypeException,
                  CorruptObjectException,
                  IOException

Reset this walker to run over a set of existing trees.

Parameters:

ids - the trees we need to parse. The walker will execute over this many parallel trees if the reset is successful.

Throws:

MissingObjectException - the given tree object does not exist in this repository.

IncorrectObjectTypeException - the given object id does not denote a tree, but instead names some other non-tree type of object. Note that commits are not trees, even if they are sometimes called a "tree-ish".

CorruptObjectException - the object claimed to be a tree, but its contents did not appear to be a tree. The repository may have data corruption.

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

addTree

public int addTree(AnyObjectId id)
            throws MissingObjectException,
                   IncorrectObjectTypeException,
                   CorruptObjectException,
                   IOException

Add an already existing tree object for walking.

The position of this tree is returned to the caller, in case the caller has lost track of the order they added the trees into the walker.

The tree must have the same root as existing trees in the walk.

Parameters:

id - identity of the tree object the caller wants walked.

Returns:

position of this tree within the walker.

Throws:

MissingObjectException - the given tree object does not exist in this repository.

IncorrectObjectTypeException - the given object id does not denote a tree, but instead names some other non-tree type of object. Note that commits are not trees, even if they are sometimes called a "tree-ish".

CorruptObjectException - the object claimed to be a tree, but its contents did not appear to be a tree. The repository may have data corruption.

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

addTree

public int addTree(AbstractTreeIterator p)
            throws CorruptObjectException

Add an already created tree iterator for walking.

The position of this tree is returned to the caller, in case the caller has lost track of the order they added the trees into the walker.

The tree which the iterator operates on must have the same root as existing trees in the walk.

Parameters:

p - an iterator to walk over. The iterator should be new, with no parent, and should still be positioned before the first entry. The tree which the iterator operates on must have the same root as other trees in the walk.

Returns:

position of this tree within the walker.

Throws:

CorruptObjectException - the iterator was unable to obtain its first entry, due to possible data corruption within the backing data store.

getTreeCount

public int getTreeCount()

Get the number of trees known to this walker.

Returns:

the total number of trees this walker is iterating over.

next

public boolean next()
             throws MissingObjectException,
                    IncorrectObjectTypeException,
                    CorruptObjectException,
                    IOException

Advance this walker to the next relevant entry.

Returns:

true if there is an entry available; false if all entries have been walked and the walk of this set of tree iterators is over.

Throws:

MissingObjectException - isRecursive() was enabled, a subtree was found, but the subtree object does not exist in this repository. The repository may be missing objects.

IncorrectObjectTypeException - isRecursive() was enabled, a subtree was found, and the subtree id does not denote a tree, but instead names some other non-tree type of object. The repository may have data corruption.

CorruptObjectException - the contents of a tree did not appear to be a tree. The repository may have data corruption.

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

getTree

public <T extends AbstractTreeIterator> T getTree(int nth,
                                         Class<T> clazz)

Obtain the tree iterator for the current entry.

Entering into (or exiting out of) a subtree causes the current tree iterator instance to be changed for the nth tree. This allows the tree iterators to manage only one list of items, with the diving handled by recursive trees.

Type Parameters:

T - type of the tree iterator expected by the caller.

Parameters:

nth - tree to obtain the current iterator of.

clazz - type of the tree iterator expected by the caller.

Returns:

r the current iterator of the requested type; null if the tree has no entry to match the current path.

getRawMode

public int getRawMode(int nth)

Obtain the raw FileMode bits for the current entry.

Every added tree supplies mode bits, even if the tree does not contain the current entry. In the latter case FileMode.MISSING's mode bits (0) are returned.

Parameters:

nth - tree to obtain the mode bits from.

Returns:

mode bits for the current entry of the nth tree.

See Also:

FileMode.fromBits(int)

getFileMode

public FileMode getFileMode(int nth)

Obtain the FileMode for the current entry.

Every added tree supplies a mode, even if the tree does not contain the current entry. In the latter case FileMode.MISSING is returned.

Parameters:

nth - tree to obtain the mode from.

Returns:

mode for the current entry of the nth tree.

getObjectId

public ObjectId getObjectId(int nth)

Obtain the ObjectId for the current entry.

Using this method to compare ObjectId values between trees of this walker is very inefficient. Applications should try to use idEqual(int, int) or getObjectId(MutableObjectId, int) whenever possible.

Every tree supplies an object id, even if the tree does not contain the current entry. In the latter case ObjectId.zeroId() is returned.

Parameters:

nth - tree to obtain the object identifier from.

Returns:

object identifier for the current tree entry.

See Also:

getObjectId(MutableObjectId, int), idEqual(int, int)

getObjectId

public void getObjectId(MutableObjectId out,
               int nth)

Obtain the ObjectId for the current entry.

Every tree supplies an object id, even if the tree does not contain the current entry. In the latter case ObjectId.zeroId() is supplied.

Applications should try to use idEqual(int, int) when possible as it avoids conversion overheads.

Parameters:

out - buffer to copy the object id into.

nth - tree to obtain the object identifier from.

See Also:

idEqual(int, int)

idEqual

public boolean idEqual(int nthA,
              int nthB)

Compare two tree's current ObjectId values for equality.

Parameters:

nthA - first tree to compare the object id from.

nthB - second tree to compare the object id from.

Returns:

result of getObjectId(nthA).equals(getObjectId(nthB)).

See Also:

getObjectId(int)

getNameString

public String getNameString()

Get the current entry's name within its parent tree.

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:

name of the current entry within the parent tree (or directory). The name never includes a '/'.

getPathString

public String getPathString()

Get the current entry'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.

getRawPath

public byte[] getRawPath()

Get the current entry's complete path as a UTF-8 byte array.

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.

getPathLength

public int getPathLength()

Returns:

The path length of the current entry.

isPathPrefix

public int isPathPrefix(byte[] p,
               int pLen)

Test if the supplied path matches the current entry's path.

This method tests that the supplied path is exactly equal to the current entry, or is one of its parent directories. It is faster to use this method then to use getPathString() to first create a String object, then test startsWith or some other type of string match function.

Parameters:

p - path buffer to test. Callers should ensure the path does not end with '/' prior to invocation.

pLen - number of bytes from buf to test.

Returns:

< 0 if p is before the current path; 0 if p matches the current path; 1 if the current path is past p and p will never match again on this tree walk.

isPathSuffix

public boolean isPathSuffix(byte[] p,
                   int pLen)

Test if the supplied path matches (being suffix of) the current entry's path.

This method tests that the supplied path is exactly equal to the current entry, or is relative to one of entry's parent directories. It is faster to use this method then to use getPathString() to first create a String object, then test endsWith or some other type of string match function.

Parameters:

p - path buffer to test.

pLen - number of bytes from buf to test.

Returns:

true if p is suffix of the current path; false if otherwise

getDepth

public int getDepth()

Get the current subtree depth of this walker.

Returns:

the current subtree depth of this walker.

isSubtree

public boolean isSubtree()

Is the current entry a subtree?

This method is faster then testing the raw mode bits of all trees to see if any of them are a subtree. If at least one is a subtree then this method will return true.

Returns:

true if enterSubtree() will work on the current node.

isPostChildren

public boolean isPostChildren()

Is the current entry a subtree returned after its children?

Returns:

true if the current node is a tree that has been returned after its children were already processed.

See Also:

isPostOrderTraversal()

enterSubtree

public void enterSubtree()
                  throws MissingObjectException,
                         IncorrectObjectTypeException,
                         CorruptObjectException,
                         IOException

Enter into the current subtree.

If the current entry is a subtree this method arranges for its children to be returned before the next sibling following the subtree is returned.

Throws:

MissingObjectException - a subtree was found, but the subtree object does not exist in this repository. The repository may be missing objects.

IncorrectObjectTypeException - a subtree was found, and the subtree id does not denote a tree, but instead names some other non-tree type of object. The repository may have data corruption.

CorruptObjectException - the contents of a tree did not appear to be a tree. The repository may have data corruption.

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