AbstractTreeIterator (JGit - Parent 5.11.0.202103091610-r API)

java.lang.Object
- org.eclipse.jgit.treewalk.AbstractTreeIterator

Direct Known Subclasses:

CanonicalTreeParser, DirCacheIterator, EmptyTreeIterator, WorkingTreeIterator
```
public abstract class AbstractTreeIterator
extends Object
```
Walks a Git tree (directory) in Git sort order.
A new iterator instance should be positioned on the first entry, or at eof. Data for the first entry (if not at eof) should be available immediately.
Implementors must walk a tree in the Git sort order, which has the following odd sorting:
1. A.c
2. A/c
3. A0c
In the second item, A is the name of a subtree and c is a file within that subtree. The other two items are files in the root level tree.
See Also:

CanonicalTreeParser

Field Summary

Fields
Modifier and Type	Field and Description
`protected AttributesNode`	`attributesNode` Parsed rules of .gitattributes file if it exists.
`protected static int`	`DEFAULT_PATH_SIZE` Default size for the `path` buffer.
`protected int`	`mode` Mode bits for the current entry.
`AbstractTreeIterator`	`parent` Iterator for the parent tree; null if we are the root iterator.
`protected byte[]`	`path` Path buffer for the current entry.
`protected int`	`pathLen` Total length of the current entry's complete path from the root.
`protected int`	`pathOffset` Position within `path` this iterator starts writing at.
`protected static byte[]`	`zeroid` A dummy object id buffer that matches the zero ObjectId.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractTreeIterator()` Create a new iterator with no parent.
`protected`	`AbstractTreeIterator(AbstractTreeIterator p)` Create an iterator for a subtree of an existing iterator.
`protected`	`AbstractTreeIterator(AbstractTreeIterator p, byte[] childPath, int childPathOffset)` Create an iterator for a subtree of an existing iterator.
`protected`	`AbstractTreeIterator(byte[] prefix)` Create a new iterator with no parent and a prefix.
`protected`	`AbstractTreeIterator(String prefix)` Create a new iterator with no parent and a prefix.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`back(int delta)` Move to prior entry, populating this iterator with the entry data.
`EmptyTreeIterator`	`createEmptyTreeIterator()` Create a new iterator as though the current entry were a subtree.
`abstract AbstractTreeIterator`	`createSubtreeIterator(ObjectReader reader)` Create a new iterator for the current entry's subtree.
`AbstractTreeIterator`	`createSubtreeIterator(ObjectReader reader, MutableObjectId idBuffer)` Create a new iterator for the current entry's subtree.
`protected void`	`ensurePathCapacity(int capacity, int len)` Ensure that path is capable to hold at least `capacity` bytes
`abstract boolean`	`eof()` Is this tree iterator at its EOF point (no more entries)?
`boolean`	`findFile(byte[] name)` Seek the iterator on a file, if present.
`boolean`	`findFile(String name)` Seek the iterator on a file, if present.
`abstract boolean`	`first()` Is this tree iterator positioned on its first entry?
`FileMode`	`getEntryFileMode()` Get the file mode of the current entry.
`ObjectId`	`getEntryObjectId()` Get the object id of the current entry.
`void`	`getEntryObjectId(MutableObjectId out)` Obtain the ObjectId for the current entry.
`byte[]`	`getEntryPathBuffer()` Get the current entry path buffer.
`int`	`getEntryPathHashCode()` Get the current entry's path hash code.
`int`	`getEntryPathLength()` Get length of the path in `getEntryPathBuffer()`.
`String`	`getEntryPathString()` Get path of the current entry, as a string.
`int`	`getEntryRawMode()` Get the file mode of the current entry as bits.
`void`	`getName(byte[] buffer, int offset)` Get the name component of the current entry path into the provided buffer.
`int`	`getNameLength()` Get the length of the name component of the path for the current entry.
`int`	`getNameOffset()` JGit internal API for use by `DirCacheCheckout`
`protected void`	`growPath(int len)` Grow the path buffer larger.
`abstract boolean`	`hasId()` Whether the entry has a valid ObjectId.
`abstract byte[]`	`idBuffer()` Get the byte array buffer object IDs must be copied out of.
`boolean`	`idEqual(AbstractTreeIterator otherIterator)` Check if the current entry of both iterators has the same id.
`abstract int`	`idOffset()` Get the position within `idBuffer()` of this entry's ObjectId.
`boolean`	`isWorkTree()` Whether or not this Iterator is iterating through the working tree.
`protected boolean`	`needsStopWalk()` Whether the iterator implements `stopWalk()`.
`abstract void`	`next(int delta)` Move to next entry, populating this iterator with the entry data.
`int`	`pathCompare(AbstractTreeIterator p)` Compare the path of this current entry to another iterator's entry.
`int`	`pathCompare(byte[] buf, int pos, int end, int pathMode)` Compare the path of this current entry to a raw buffer.
`void`	`reset()` Position this iterator on the first entry.
`void`	`skip()` Advance to the next tree entry, populating this iterator with its data.
`void`	`stopWalk()` Indicates to the iterator that no more entries will be read.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_PATH_SIZE
```
protected static final int DEFAULT_PATH_SIZE
```
    Default size for the path buffer.
    
    See Also:
    
    Constant Field Values
  - zeroid
```
protected static final byte[] zeroid
```
    A dummy object id buffer that matches the zero ObjectId.
  - parent
```
public final AbstractTreeIterator parent
```
    Iterator for the parent tree; null if we are the root iterator.
    Used by TreeWalk and AttributesHandler
    
    Since:
    
    4.3
  - attributesNode
```
protected AttributesNode attributesNode
```
    Parsed rules of .gitattributes file if it exists.
    
    Since:
    
    4.2
  - mode
```
protected int mode
```
    Mode bits for the current entry.
    A numerical value from FileMode is usually faster for an iterator to obtain from its data source so this is the preferred representation.
    
    See Also:
    
    FileMode
  - path
```
protected byte[] path
```
    Path buffer for the current entry.
    This buffer is pre-allocated at the start of walking and is shared from parent iterators down into their subtree iterators. The sharing allows the current entry to always be a full path from the root, while each subtree only needs to populate the part that is under their control.
  - pathOffset
```
protected final int pathOffset
```
    Position within path this iterator starts writing at.
    This is the first offset in path that this iterator must populate during next(int). At the root level (when parent is null) this is 0. For a subtree iterator the index before this position should have the value '/'.
  - pathLen
```
protected int pathLen
```
    Total length of the current entry's complete path from the root.
    This is the number of bytes within path that pertain to the current entry. Values at this index through the end of the array are garbage and may be randomly populated from prior entries.
- Constructor Detail
  - AbstractTreeIterator
```
protected AbstractTreeIterator()
```
    Create a new iterator with no parent.
  - AbstractTreeIterator
```
protected AbstractTreeIterator(String prefix)
```
    Create a new iterator with no parent and a prefix.
    The prefix path supplied is inserted in front of all paths generated by this iterator. It is intended to be used when an iterator is being created for a subsection of an overall repository and needs to be combined with other iterators that are created to run over the entire repository namespace.
    
    Parameters:
    
    prefix - position of this iterator in the repository tree. The value may be null or the empty string to indicate the prefix is the root of the repository. A trailing slash ('/') is automatically appended if the prefix does not end in '/'.
  - AbstractTreeIterator
```
protected AbstractTreeIterator(byte[] prefix)
```
    Create a new iterator with no parent and a prefix.
    The prefix path supplied is inserted in front of all paths generated by this iterator. It is intended to be used when an iterator is being created for a subsection of an overall repository and needs to be combined with other iterators that are created to run over the entire repository namespace.
    
    Parameters:
    
    prefix - position of this iterator in the repository tree. The value may be null or the empty array to indicate the prefix is the root of the repository. A trailing slash ('/') is automatically appended if the prefix does not end in '/'.
  - AbstractTreeIterator
```
protected AbstractTreeIterator(AbstractTreeIterator p)
```
    Create an iterator for a subtree of an existing iterator.
    
    Parameters:
    
    p - parent tree iterator.
  - AbstractTreeIterator
```
protected AbstractTreeIterator(AbstractTreeIterator p,
                               byte[] childPath,
                               int childPathOffset)
```
    Create an iterator for a subtree of an existing iterator.
    The caller is responsible for setting up the path of the child iterator.
    
    Parameters:
    
    p - parent tree iterator.
    
    childPath - path array to be used by the child iterator. This path must contain the path from the top of the walk to the first child and must end with a '/'.
    
    childPathOffset - position within childPath where the child can insert its data. The value at childPath[childPathOffset-1] must be '/'.
- Method Detail
  - growPath
```
protected void growPath(int len)
```
    Grow the path buffer larger.
    
    Parameters:
    
    len - number of live bytes in the path buffer. This many bytes will be moved into the larger buffer.
  - ensurePathCapacity
```
protected void ensurePathCapacity(int capacity,
                                  int len)
```
    Ensure that path is capable to hold at least capacity bytes
    
    Parameters:
    
    capacity - the amount of bytes to hold
    
    len - the amount of live bytes in path buffer
  - pathCompare
```
public int pathCompare(AbstractTreeIterator p)
```
    Compare the path of this current entry to another iterator's entry.
    
    Parameters:
    
    p - the other iterator to compare the path against.
    
    Returns:
    
    -1 if this entry sorts first; 0 if the entries are equal; 1 if p's entry sorts first.
  - findFile
```
public boolean findFile(String name)
                 throws CorruptObjectException
```
    Seek the iterator on a file, if present.
    
    Parameters:
    
    name - file name to find (will not find a directory).
    
    Returns:
    
    true if the file exists in this tree; false otherwise.
    
    Throws:
    
    CorruptObjectException - tree is invalid.
    
    Since:
    
    4.2
  - findFile
```
public boolean findFile(byte[] name)
                 throws CorruptObjectException
```
    Seek the iterator on a file, if present.
    
    Parameters:
    
    name - file name to find (will not find a directory).
    
    Returns:
    
    true if the file exists in this tree; false otherwise.
    
    Throws:
    
    CorruptObjectException - tree is invalid.
    
    Since:
    
    4.2
  - pathCompare
```
public int pathCompare(byte[] buf,
                       int pos,
                       int end,
                       int pathMode)
```
    Compare the path of this current entry to a raw buffer.
    
    Parameters:
    
    buf - the raw path buffer.
    
    pos - position to start reading the raw buffer.
    
    end - one past the end of the raw buffer (length is end - pos).
    
    pathMode - the mode of the path.
    
    Returns:
    
    -1 if this entry sorts first; 0 if the entries are equal; 1 if p's entry sorts first.
  - idEqual
```
public boolean idEqual(AbstractTreeIterator otherIterator)
```
    Check if the current entry of both iterators has the same id.
    This method is faster than getEntryObjectId() as it does not require copying the bytes out of the buffers. A direct idBuffer() compare operation is performed.
    
    Parameters:
    
    otherIterator - the other iterator to test against.
    
    Returns:
    
    true if both iterators have the same object id; false otherwise.
  - hasId
```
public abstract boolean hasId()
```
    Whether the entry has a valid ObjectId.
    
    Returns:
    
    true if the entry has a valid ObjectId.
  - getEntryObjectId
```
public ObjectId getEntryObjectId()
```
    Get the object id of the current entry.
    
    Returns:
    
    an object id for the current entry.
  - getEntryObjectId
```
public void getEntryObjectId(MutableObjectId out)
```
    Obtain the ObjectId for the current entry.
    
    Parameters:
    
    out - buffer to copy the object id into.
  - getEntryFileMode
```
public FileMode getEntryFileMode()
```
    Get the file mode of the current entry.
    
    Returns:
    
    the file mode of the current entry.
  - getEntryRawMode
```
public int getEntryRawMode()
```
    Get the file mode of the current entry as bits.
    
    Returns:
    
    the file mode of the current entry as bits.
  - getEntryPathString
```
public String getEntryPathString()
```
    Get path of the current entry, as a string.
    
    Returns:
    
    path of the current entry, as a string.
  - getEntryPathBuffer
```
public byte[] getEntryPathBuffer()
```
    Get the current entry path buffer.
    Note that the returned byte[] has to be used together with getEntryPathLength() (only use bytes up to this length).
    
    Returns:
    
    the internal buffer holding the current path.
  - getEntryPathLength
```
public int getEntryPathLength()
```
    Get length of the path in getEntryPathBuffer().
    
    Returns:
    
    length of the path in getEntryPathBuffer().
  - getEntryPathHashCode
```
public int getEntryPathHashCode()
```
    Get the current entry'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.
  - idBuffer
```
public abstract byte[] idBuffer()
```
    Get the byte array buffer object IDs must be copied out of.
    The id buffer contains the bytes necessary to construct an ObjectId for the current entry of this iterator. The buffer can be the same buffer for all entries, or it can be a unique buffer per-entry. Implementations are encouraged to expose their private buffer whenever possible to reduce garbage generation and copying costs.
    
    Returns:
    
    byte array the implementation stores object IDs within.
    
    See Also:
    
    getEntryObjectId()
  - idOffset
```
public abstract int idOffset()
```
    Get the position within idBuffer() of this entry's ObjectId.
    
    Returns:
    
    offset into the array returned by idBuffer() where the ObjectId must be copied out of.
  - createSubtreeIterator
```
public abstract AbstractTreeIterator createSubtreeIterator(ObjectReader reader)
                                                    throws IncorrectObjectTypeException,
                                                           IOException
```
    Create a new iterator for the current entry's subtree.
    The parent reference of the iterator must be this, otherwise the caller would not be able to exit out of the subtree iterator correctly and return to continue walking this.
    
    Parameters:
    
    reader - reader to load the tree data from.
    
    Returns:
    
    a new parser that walks over the current subtree.
    
    Throws:
    
    IncorrectObjectTypeException - the current entry is not actually a tree and cannot be parsed as though it were a tree.
    
    IOException - a loose object or pack file could not be read.
  - createEmptyTreeIterator
```
public EmptyTreeIterator createEmptyTreeIterator()
```
    Create a new iterator as though the current entry were a subtree.
    
    Returns:
    
    a new empty tree iterator.
  - createSubtreeIterator
```
public AbstractTreeIterator createSubtreeIterator(ObjectReader reader,
                                                  MutableObjectId idBuffer)
                                           throws IncorrectObjectTypeException,
                                                  IOException
```
    Create a new iterator for the current entry's subtree.
    The parent reference of the iterator must be this, otherwise the caller would not be able to exit out of the subtree iterator correctly and return to continue walking this.
    
    Parameters:
    
    reader - reader to load the tree data from.
    
    idBuffer - temporary ObjectId buffer for use by this method.
    
    Returns:
    
    a new parser that walks over the current subtree.
    
    Throws:
    
    IncorrectObjectTypeException - the current entry is not actually a tree and cannot be parsed as though it were a tree.
    
    IOException - a loose object or pack file could not be read.
  - reset
```
public void reset()
           throws CorruptObjectException
```
    Position this iterator on the first entry. The default implementation of this method uses back(1) until first() is true. This is most likely not the most efficient method of repositioning the iterator to its first entry, so subclasses are strongly encouraged to override the method.
    
    Throws:
    
    CorruptObjectException - the tree is invalid.
  - first
```
public abstract boolean first()
```
    Is this tree iterator positioned on its first entry?
    An iterator is positioned on the first entry if back(1) would be an invalid request as there is no entry before the current one.
    An empty iterator (one with no entries) will be first() && eof().
    
    Returns:
    
    true if the iterator is positioned on the first entry.
  - eof
```
public abstract boolean eof()
```
    Is this tree iterator at its EOF point (no more entries)?
    An iterator is at EOF if there is no current entry.
    
    Returns:
    
    true if we have walked all entries and have none left.
  - next
```
public abstract void next(int delta)
                   throws CorruptObjectException
```
    Move to next entry, populating this iterator with the entry data.
    The delta indicates how many moves forward should occur. The most common delta is 1 to move to the next entry.
    Implementations must populate the following members:
    - mode
    - path (from pathOffset to pathLen)
    - pathLen
    as well as any implementation dependent information necessary to accurately return data from idBuffer() and idOffset() when demanded.
    Parameters:
    
    delta - number of entries to move the iterator by. Must be a positive, non-zero integer.
    
    Throws:
    
    CorruptObjectException - the tree is invalid.
  - back
```
public abstract void back(int delta)
                   throws CorruptObjectException
```
    Move to prior entry, populating this iterator with the entry data.
    The delta indicates how many moves backward should occur.The most common delta is 1 to move to the prior entry.
    Implementations must populate the following members:
    - mode
    - path (from pathOffset to pathLen)
    - pathLen
    as well as any implementation dependent information necessary to accurately return data from idBuffer() and idOffset() when demanded.
    Parameters:
    
    delta - number of entries to move the iterator by. Must be a positive, non-zero integer.
    
    Throws:
    
    CorruptObjectException - the tree is invalid.
  - skip
```
public void skip()
          throws CorruptObjectException
```
    Advance to the next tree entry, populating this iterator with its data.
    This method behaves like seek(1) but is called by TreeWalk only if a TreeFilter was used and ruled out the current entry from the results. In such cases this tree iterator may perform special behavior.
    
    Throws:
    
    CorruptObjectException - the tree is invalid.
  - stopWalk
```
public void stopWalk()
```
    Indicates to the iterator that no more entries will be read.
    This is only invoked by TreeWalk when the iteration is aborted early due to a StopWalkException being thrown from within a TreeFilter.
  - needsStopWalk
```
protected boolean needsStopWalk()
```
    Whether the iterator implements stopWalk().
    
    Returns:
    
    true if the iterator implements stopWalk().
    
    Since:
    
    4.2
  - getNameLength
```
public int getNameLength()
```
    Get the length of the name component of the path for the current entry.
    
    Returns:
    
    the length of the name component of the path for the current entry.
  - getNameOffset
```
public int getNameOffset()
```
    JGit internal API for use by DirCacheCheckout
    
    Returns:
    
    start of name component part within getEntryPathBuffer()
    
    Since:
    
    2.0
  - getName
```
public void getName(byte[] buffer,
                    int offset)
```
    Get the name component of the current entry path into the provided buffer.
    
    Parameters:
    
    buffer - the buffer to get the name into, it is assumed that buffer can hold the name
    
    offset - the offset of the name in the buffer
    
    See Also:
    
    getNameLength()
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - isWorkTree
```
public boolean isWorkTree()
```
    Whether or not this Iterator is iterating through the working tree.
    
    Returns:
    
    whether or not this Iterator is iterating through the working tree
    
    Since:
    
    4.3

Class AbstractTreeIterator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PATH_SIZE

zeroid

parent

attributesNode

mode

path

pathOffset

pathLen

Constructor Detail

AbstractTreeIterator

AbstractTreeIterator

AbstractTreeIterator

AbstractTreeIterator

AbstractTreeIterator

Method Detail

growPath

ensurePathCapacity

pathCompare

findFile

findFile

pathCompare

idEqual

hasId

getEntryObjectId

getEntryObjectId

getEntryFileMode

getEntryRawMode

getEntryPathString

getEntryPathBuffer

getEntryPathLength

getEntryPathHashCode

idBuffer

idOffset

createSubtreeIterator

createEmptyTreeIterator

createSubtreeIterator

reset

first

eof

next

back

skip

stopWalk

needsStopWalk

getNameLength

getNameOffset

getName

toString

isWorkTree