DirCache (JGit - Parent 5.3.6.201910020505-r API)

java.lang.Object
- org.eclipse.jgit.dircache.DirCache

```
public class DirCache
extends Object
```
Support for the Git dircache (aka index file).
The index file keeps track of which objects are currently checked out in the working directory, and the last modified time of those working files. Changes in the working directory can be detected by comparing the modification times to the cached modification time within the index file.
Index files are also used during merges, where the merge happens within the index file first, and the working directory is updated as a post-merge step. Conflicts are stored in the index file to allow tool (and human) based resolutions to be easily performed.

Constructor Summary

Constructors
Constructor and Description

DirCache(File indexLocation, FS fs)
Create a new in-core index representation.

Constructors
Constructor and Description
`DirCache(File indexLocation, FS fs)` Create a new in-core index representation.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`DirCacheBuilder`	`builder()` Create a new builder to update this cache.
`void`	`clear()` Empty this index, removing all entries.
`boolean`	`commit()` Commit this change and release the lock.
`DirCacheEditor`	`editor()` Create a new editor to recreate this cache.
`int`	`findEntry(byte[] p, int pLen)` Locate the position a path's entry is at in the index.
`int`	`findEntry(String path)` Locate the position a path's entry is at in the index.
`DirCacheTree`	`getCacheTree(boolean build)` Obtain (or build) the current cache tree structure.
`DirCacheEntry[]`	`getEntriesWithin(String path)` Recursively get all entries within a subtree.
`DirCacheEntry`	`getEntry(int i)` Get a specific entry.
`DirCacheEntry`	`getEntry(String path)` Get a specific entry.
`int`	`getEntryCount()` Total number of file entries stored in the index.
`boolean`	`hasUnmergedPaths()` Tells whether this index contains unmerged paths.
`boolean`	`isOutdated()` Whether the memory state differs from the index file
`boolean`	`lock()` Try to establish an update lock on the cache file.
`static DirCache`	`lock(File indexLocation, FS fs)` Create a new in-core index representation, lock it, and read from disk.
`static DirCache`	`lock(File indexLocation, FS fs, IndexChangedListener indexChangedListener)` Create a new in-core index representation, lock it, and read from disk.
`static DirCache`	`lock(Repository repository, IndexChangedListener indexChangedListener)` Create a new in-core index representation, lock it, and read from disk.
`static DirCache`	`newInCore()` Create a new empty index which is never stored on disk.
`int`	`nextEntry(int position)` Determine the next index position past all entries with the same name.
`void`	`read()` Read the index from disk, if it has changed on disk.
`static DirCache`	`read(File indexLocation, FS fs)` Create a new in-core index representation and read an index from disk.
`static DirCache`	`read(ObjectReader reader, AnyObjectId treeId)` Create a new in memory index read from the contents of a tree.
`static DirCache`	`read(Repository repository)` Create a new in-core index representation and read an index from disk.
`void`	`unlock()` Unlock this file and abort this change.
`void`	`write()` Write the entry records from memory to disk.
`ObjectId`	`writeTree(ObjectInserter ow)` Write all index trees to the object store, returning the root tree.

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

- Constructor Detail
  - DirCache
```
public DirCache(File indexLocation,
                FS fs)
```
    Create a new in-core index representation.
    The new index will be empty. Callers may wish to read from the on disk file first with read().
    
    Parameters:
    
    indexLocation - location of the index file on disk.
    
    fs - the file system abstraction which will be necessary to perform certain file system operations.
- Method Detail
  - newInCore
```
public static DirCache newInCore()
```
    Create a new empty index which is never stored on disk.
    
    Returns:
    
    an empty cache which has no backing store file. The cache may not be read or written, but it may be queried and updated (in memory).
  - read
```
public static DirCache read(ObjectReader reader,
                            AnyObjectId treeId)
                     throws IOException
```
    Create a new in memory index read from the contents of a tree.
    
    Parameters:
    
    reader - reader to access the tree objects from a repository.
    
    treeId - tree to read. Must identify a tree, not a tree-ish.
    
    Returns:
    
    a new cache which has no backing store file, but contains the contents of treeId.
    
    Throws:
    
    IOException - one or more trees not available from the ObjectReader.
    
    Since:
    
    4.2
  - read
```
public static DirCache read(Repository repository)
                     throws CorruptObjectException,
                            IOException
```
    Create a new in-core index representation and read an index from disk.
    The new index will be read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index.
    
    Parameters:
    
    repository - repository containing the index to read
    
    Returns:
    
    a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.
    
    Throws:
    
    IOException - the index file is present but could not be read.
    
    CorruptObjectException - the index file is using a format or extension that this library does not support.
  - read
```
public static DirCache read(File indexLocation,
                            FS fs)
                     throws CorruptObjectException,
                            IOException
```
    Create a new in-core index representation and read an index from disk.
    The new index will be read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index.
    
    Parameters:
    
    indexLocation - location of the index file on disk.
    
    fs - the file system abstraction which will be necessary to perform certain file system operations.
    
    Returns:
    
    a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.
    
    Throws:
    
    IOException - the index file is present but could not be read.
    
    CorruptObjectException - the index file is using a format or extension that this library does not support.
  - lock
```
public static DirCache lock(File indexLocation,
                            FS fs)
                     throws CorruptObjectException,
                            IOException
```
    Create a new in-core index representation, lock it, and read from disk.
    The new index will be locked and then read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index. On read failure, the lock is released.
    
    Parameters:
    
    indexLocation - location of the index file on disk.
    
    fs - the file system abstraction which will be necessary to perform certain file system operations.
    
    Returns:
    
    a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.
    
    Throws:
    
    IOException - the index file is present but could not be read, or the lock could not be obtained.
    
    CorruptObjectException - the index file is using a format or extension that this library does not support.
  - lock
```
public static DirCache lock(Repository repository,
                            IndexChangedListener indexChangedListener)
                     throws CorruptObjectException,
                            IOException
```
    Create a new in-core index representation, lock it, and read from disk.
    The new index will be locked and then read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index. On read failure, the lock is released.
    
    Parameters:
    
    repository - repository containing the index to lock and read
    
    indexChangedListener - listener to be informed when DirCache is committed
    
    Returns:
    
    a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.
    
    Throws:
    
    IOException - the index file is present but could not be read, or the lock could not be obtained.
    
    CorruptObjectException - the index file is using a format or extension that this library does not support.
    
    Since:
    
    2.0
  - lock
```
public static DirCache lock(File indexLocation,
                            FS fs,
                            IndexChangedListener indexChangedListener)
                     throws CorruptObjectException,
                            IOException
```
    Create a new in-core index representation, lock it, and read from disk.
    The new index will be locked and then read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index. On read failure, the lock is released.
    
    Parameters:
    
    indexLocation - location of the index file on disk.
    
    fs - the file system abstraction which will be necessary to perform certain file system operations.
    
    indexChangedListener - listener to be informed when DirCache is committed
    
    Returns:
    
    a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.
    
    Throws:
    
    IOException - the index file is present but could not be read, or the lock could not be obtained.
    
    CorruptObjectException - the index file is using a format or extension that this library does not support.
  - builder
```
public DirCacheBuilder builder()
```
    Create a new builder to update this cache.
    Callers should add all entries to the builder, then use DirCacheBuilder.finish() to update this instance.
    
    Returns:
    
    a new builder instance for this cache.
  - editor
```
public DirCacheEditor editor()
```
    Create a new editor to recreate this cache.
    Callers should add commands to the editor, then use DirCacheEditor.finish() to update this instance.
    
    Returns:
    
    a new builder instance for this cache.
  - read
```
public void read()
          throws IOException,
                 CorruptObjectException
```
    Read the index from disk, if it has changed on disk.
    This method tries to avoid loading the index if it has not changed since the last time we consulted it. A missing index file will be treated as though it were present but had no file entries in it.
    
    Throws:
    
    IOException - the index file is present but could not be read. This DirCache instance may not be populated correctly.
    
    CorruptObjectException - the index file is using a format or extension that this library does not support.
  - isOutdated
```
public boolean isOutdated()
                   throws IOException
```
    Whether the memory state differs from the index file
    
    Returns:
    
    true if the memory state differs from the index file
    
    Throws:
    
    IOException
  - clear
```
public void clear()
```
    Empty this index, removing all entries.
  - lock
```
public boolean lock()
             throws IOException
```
    Try to establish an update lock on the cache file.
    
    Returns:
    
    true if the lock is now held by the caller; false if it is held by someone else.
    
    Throws:
    
    IOException - the output file could not be created. The caller does not hold the lock.
  - write
```
public void write()
           throws IOException
```
    Write the entry records from memory to disk.
    The cache must be locked first by calling lock() and receiving true as the return value. Applications are encouraged to lock the index, then invoke read() to ensure the in-memory data is current, prior to updating the in-memory entries.
    Once written the lock is closed and must be either committed with commit() or rolled back with unlock().
    
    Throws:
    
    IOException - the output file could not be created. The caller no longer holds the lock.
  - commit
```
public boolean commit()
```
    Commit this change and release the lock.
    If this method fails (returns false) the lock is still released.
    
    Returns:
    
    true if the commit was successful and the file contains the new data; false if the commit failed and the file remains with the old data.
    
    Throws:
    
    IllegalStateException - the lock is not held.
  - unlock
```
public void unlock()
```
    Unlock this file and abort this change.
    The temporary file (if created) is deleted before returning.
  - findEntry
```
public int findEntry(String path)
```
    Locate the position a path's entry is at in the index. For details refer to #findEntry(byte[], int).
    
    Parameters:
    
    path - the path to search for.
    
    Returns:
    
    if >= 0 then the return value is the position of the entry in the index; pass to getEntry(int) to obtain the entry information. If < 0 the entry does not exist in the index.
  - findEntry
```
public int findEntry(byte[] p,
                     int pLen)
```
    Locate the position a path's entry is at in the index.
    If there is at least one entry in the index for this path the position of the lowest stage is returned. Subsequent stages can be identified by testing consecutive entries until the path differs.
    If no path matches the entry -(position+1) is returned, where position is the location it would have gone within the index.
    
    Parameters:
    
    p - the byte array starting with the path to search for.
    
    pLen - the length of the path in bytes
    
    Returns:
    
    if >= 0 then the return value is the position of the entry in the index; pass to getEntry(int) to obtain the entry information. If < 0 the entry does not exist in the index.
    
    Since:
    
    3.4
  - nextEntry
```
public int nextEntry(int position)
```
    Determine the next index position past all entries with the same name.
    As index entries are sorted by path name, then stage number, this method advances the supplied position to the first position in the index whose path name does not match the path name of the supplied position's entry.
    
    Parameters:
    
    position - entry position of the path that should be skipped.
    
    Returns:
    
    position of the next entry whose path is after the input.
  - getEntryCount
```
public int getEntryCount()
```
    Total number of file entries stored in the index.
    This count includes unmerged stages for a file entry if the file is currently conflicted in a merge. This means the total number of entries in the index may be up to 3 times larger than the number of files in the working directory.
    Note that this value counts only files.
    
    Returns:
    
    number of entries available.
    
    See Also:
    
    getEntry(int)
  - getEntry
```
public DirCacheEntry getEntry(int i)
```
    Get a specific entry.
    
    Parameters:
    
    i - position of the entry to get.
    
    Returns:
    
    the entry at position i.
  - getEntry
```
public DirCacheEntry getEntry(String path)
```
    Get a specific entry.
    
    Parameters:
    
    path - the path to search for.
    
    Returns:
    
    the entry for the given path.
  - getEntriesWithin
```
public DirCacheEntry[] getEntriesWithin(String path)
```
    Recursively get all entries within a subtree.
    
    Parameters:
    
    path - the subtree path to get all entries within.
    
    Returns:
    
    all entries recursively contained within the subtree.
  - getCacheTree
```
public DirCacheTree getCacheTree(boolean build)
```
    Obtain (or build) the current cache tree structure.
    This method can optionally recreate the cache tree, without flushing the tree objects themselves to disk.
    
    Parameters:
    
    build - if true and the cache tree is not present in the index it will be generated and returned to the caller.
    
    Returns:
    
    the cache tree; null if there is no current cache tree available and build was false.
  - writeTree
```
public ObjectId writeTree(ObjectInserter ow)
                   throws UnmergedPathException,
                          IOException
```
    Write all index trees to the object store, returning the root tree.
    
    Parameters:
    
    ow - the writer to use when serializing to the store. The caller is responsible for flushing the inserter before trying to use the returned tree identity.
    
    Returns:
    
    identity for the root tree.
    
    Throws:
    
    UnmergedPathException - one or more paths contain higher-order stages (stage > 0), which cannot be stored in a tree object.
    
    IllegalStateException - one or more paths contain an invalid mode which should never appear in a tree object.
    
    IOException - an unexpected error occurred writing to the object store.
  - hasUnmergedPaths
```
public boolean hasUnmergedPaths()
```
    Tells whether this index contains unmerged paths.
    
    Returns:
    
    true if this index contains unmerged paths. Means: at least one entry is of a stage different from 0. false will be returned if all entries are of stage 0.

Class DirCache

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DirCache

Method Detail

newInCore

read

read

read

lock

lock

lock

builder

editor

read

isOutdated

clear

lock

write

commit

unlock

findEntry

findEntry

nextEntry

getEntryCount

getEntry

getEntry

getEntriesWithin

getCacheTree

writeTree

hasUnmergedPaths