org.eclipse.jgit.dircache

## Class DirCacheIterator

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

Direct Known Subclasses:
  DirCacheBuildIterator

    public class DirCacheIterator
    extends AbstractTreeIterator

Iterate a `DirCache` as part of a `TreeWalk`.

This is an iterator to adapt a loaded `DirCache` instance (such as read from an existing `.git/index` file) to the tree structure used by a `TreeWalk`, making it possible for applications to walk over any combination of tree objects already in the object database, index files, or working directories.

See Also:
  `TreeWalk`

### Field Summary

Fields
`protected DirCache` `cache` The cache this iterator was created to walk.
`protected DirCacheEntry` `currentEntry` The current file entry from `cache`.
`protected DirCacheTree` `currentSubtree` The subtree containing `currentEntry` if this is first entry.
`protected int` `ptr` Index of entry within `cache`.

### Fields inherited from class org.eclipse.jgit.treewalk.AbstractTreeIterator

`DEFAULT_PATH_SIZE, mode, path, pathLen, pathOffset, zeroid`

### Constructor Summary

Constructors
Constructor and Description
`DirCacheIterator(DirCache dc)` Create a new iterator for an already loaded DirCache instance.

### Method Summary

All Methods Instance Methods Concrete Methods
`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.
`AbstractTreeIterator` `createSubtreeIterator(ObjectReader reader)` Create a new iterator for the current entry's subtree.
`boolean` `eof()` Is this tree iterator at its EOF point (no more entries)?
`boolean` `first()` Is this tree iterator positioned on its first entry?
`DirCacheEntry` `getDirCacheEntry()` Get the DirCacheEntry for the current file.
`AttributesNode` `getEntryAttributesNode(ObjectReader reader)` Retrieves the `AttributesNode` for the current entry.
`boolean` `hasId()`
`byte[]` `idBuffer()` Get the byte array buffer object IDs must be copied out of.
`int` `idOffset()` Get the position within `AbstractTreeIterator.idBuffer()` of this entry's ObjectId.
`void` `next(int delta)` Move to next entry, populating this iterator with the entry data.
`void` `reset()` Position this iterator on the first entry.

### Methods inherited from class org.eclipse.jgit.treewalk.AbstractTreeIterator

`createSubtreeIterator, ensurePathCapacity, getEntryFileMode, getEntryObjectId, getEntryObjectId, getEntryPathBuffer, getEntryPathHashCode, getEntryPathLength, getEntryPathString, getEntryRawMode, getName, getNameLength, getNameOffset, growPath, idEqual, pathCompare, pathCompare, skip, stopWalk, toString`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### cache

    protected final DirCache cache

The cache this iterator was created to walk.

#### ptr

    protected int ptr

Index of entry within `cache`.

#### currentEntry

    protected DirCacheEntry currentEntry

The current file entry from `cache`.

#### currentSubtree

    protected DirCacheTree currentSubtree

The subtree containing `currentEntry` if this is first entry.

### Constructor Detail

#### DirCacheIterator

    public DirCacheIterator(DirCache dc)

Create a new iterator for an already loaded DirCache instance.

The iterator implementation may copy part of the cache's data during construction, so the cache must be read in prior to creating the iterator.

Parameters:
  `dc` - the cache to walk. It must be already loaded into memory.

### Method Detail

#### createSubtreeIterator

    public AbstractTreeIterator createSubtreeIterator(ObjectReader reader)
                                               throws IncorrectObjectTypeException,
                                                      IOException

Description copied from class: `AbstractTreeIterator`
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`.

Specified by:
  `createSubtreeIterator` in class `AbstractTreeIterator`
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()

Description copied from class: `AbstractTreeIterator`
Create a new iterator as though the current entry were a subtree.

Overrides:
  `createEmptyTreeIterator` in class `AbstractTreeIterator`
Returns:
  a new empty tree iterator.

#### hasId

    public boolean hasId()

Specified by:
  `hasId` in class `AbstractTreeIterator`
Returns:
  true if the entry has a valid ObjectId.

#### idBuffer

    public byte[] idBuffer()

Description copied from class: `AbstractTreeIterator`
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.

Specified by:
  `idBuffer` in class `AbstractTreeIterator`
Returns:
  byte array the implementation stores object IDs within.
See Also:
  `AbstractTreeIterator.getEntryObjectId()`

#### idOffset

    public int idOffset()

Description copied from class: `AbstractTreeIterator`
Get the position within `AbstractTreeIterator.idBuffer()` of this entry's ObjectId.

Specified by:
  `idOffset` in class `AbstractTreeIterator`
Returns:
  offset into the array returned by `AbstractTreeIterator.idBuffer()` where the ObjectId must be copied out of.

#### reset

    public void reset()

Description copied from class: `AbstractTreeIterator`
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.

Overrides:
  `reset` in class `AbstractTreeIterator`

#### first

    public boolean first()

Description copied from class: `AbstractTreeIterator`
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()`.

Specified by:
  `first` in class `AbstractTreeIterator`
Returns:
  true if the iterator is positioned on the first entry.

#### eof

    public boolean eof()

Description copied from class: `AbstractTreeIterator`
Is this tree iterator at its EOF point (no more entries)?

An iterator is at EOF if there is no current entry.

Specified by:
  `eof` in class `AbstractTreeIterator`
Returns:
  true if we have walked all entries and have none left.

#### next

    public void next(int delta)

Description copied from class: `AbstractTreeIterator`
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:

- `AbstractTreeIterator.mode`
- `AbstractTreeIterator.path` (from `AbstractTreeIterator.pathOffset` to `AbstractTreeIterator.pathLen`)
- `AbstractTreeIterator.pathLen`

as well as any implementation dependent information necessary to accurately return data from `AbstractTreeIterator.idBuffer()` and `AbstractTreeIterator.idOffset()` when demanded.

Specified by:
  `next` in class `AbstractTreeIterator`
Parameters:
  `delta` - number of entries to move the iterator by. Must be a positive, non-zero integer.

#### back

    public void back(int delta)

Description copied from class: `AbstractTreeIterator`
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:

- `AbstractTreeIterator.mode`
- `AbstractTreeIterator.path` (from `AbstractTreeIterator.pathOffset` to `AbstractTreeIterator.pathLen`)
- `AbstractTreeIterator.pathLen`

as well as any implementation dependent information necessary to accurately return data from `AbstractTreeIterator.idBuffer()` and `AbstractTreeIterator.idOffset()` when demanded.

Specified by:
  `back` in class `AbstractTreeIterator`
Parameters:
  `delta` - number of entries to move the iterator by. Must be a positive, non-zero integer.

#### getDirCacheEntry

    public DirCacheEntry getDirCacheEntry()

Get the DirCacheEntry for the current file.

Returns:
  the current cache entry, if this iterator is positioned on a non-tree.

#### getEntryAttributesNode

    public AttributesNode getEntryAttributesNode(ObjectReader reader)
                                          throws IOException

Retrieves the `AttributesNode` for the current entry.

Parameters:
  `reader` - `ObjectReader` used to parse the .gitattributes entry.
Returns:
  `AttributesNode` for the current entry.
Throws:
  `IOException`
Since:
  3.7