org.eclipse.jgit.lib

## Class RefDatabase

- java.lang.Object
- - org.eclipse.jgit.lib.RefDatabase

Direct Known Subclasses:
  DfsRefDatabase, RefDirectory

    public abstract class RefDatabase
    extends Object

Abstraction of name to `ObjectId` mapping.

A reference database stores a mapping of reference names to `ObjectId`. Every `Repository` has a single reference database, mapping names to the tips of the object graph contained by the `ObjectDatabase`.

### Field Summary

Fields
`static String` `ALL` Magic value for `getRefs(String)` to return all references.
`protected static int` `MAX_SYMBOLIC_REF_DEPTH` Maximum number of times a `SymbolicRef` can be traversed.
`protected static String[]` `SEARCH_PATH` Order of prefixes to search when using non-absolute references.

### Constructor Summary

Constructors
Constructor and Description
`RefDatabase()`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`abstract void` `close()` Close any resources held by this database.
`abstract void` `create()` Initialize a new reference database at this location.
`static Ref` `findRef(Map<String,Ref> map, String name)` Try to find the specified name in the ref map using `SEARCH_PATH`.
`abstract List<Ref>` `getAdditionalRefs()` Get the additional reference-like entities from the repository.
`Collection<String>` `getConflictingNames(String name)` Determine if a proposed reference cannot coexist with existing ones.
`abstract Ref` `getRef(String name)` Read a single reference.
`abstract Map<String,Ref>` `getRefs(String prefix)` Get a section of the reference namespace.
`abstract boolean` `isNameConflicting(String name)` Determine if a proposed reference name overlaps with an existing one.
`BatchRefUpdate` `newBatchUpdate()` Create a new batch update to attempt on this database.
`abstract RefRename` `newRename(String fromName, String toName)` Create a new update command to rename a reference.
`abstract RefUpdate` `newUpdate(String name, boolean detach)` Create a new update command to create, modify or delete a reference.
`abstract Ref` `peel(Ref ref)` Peel a possibly unpeeled reference by traversing the annotated tags.
`boolean` `performsAtomicTransactions()`
`void` `refresh()` Triggers a refresh of all internal data structures.

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

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

### Field Detail

#### SEARCH_PATH

    protected static final String[] SEARCH_PATH

Order of prefixes to search when using non-absolute references.

The implementation's `getRef(String)` method must take this search space into consideration when locating a reference by name. The first entry in the path is always `""`, ensuring that absolute references are resolved without further mangling.

#### MAX_SYMBOLIC_REF_DEPTH

    protected static final int MAX_SYMBOLIC_REF_DEPTH

Maximum number of times a `SymbolicRef` can be traversed.

If the reference is nested deeper than this depth, the implementation should either fail, or at least claim the reference does not exist.

See Also:
  Constant Field Values

#### ALL

    public static final String ALL

Magic value for `getRefs(String)` to return all references.

See Also:
  Constant Field Values

### Constructor Detail

#### RefDatabase

    public RefDatabase()

### Method Detail

#### create

    public abstract void create()
                         throws IOException

Initialize a new reference database at this location.

Throws:
  `IOException` - the database could not be created.

#### close

    public abstract void close()

Close any resources held by this database.

#### isNameConflicting

    public abstract boolean isNameConflicting(String name)
                                       throws IOException

Determine if a proposed reference name overlaps with an existing one.

Reference names use '/' as a component separator, and may be stored in a hierarchical storage such as a directory on the local filesystem.

If the reference "refs/heads/foo" exists then "refs/heads/foo/bar" must not exist, as a reference cannot have a value and also be a container for other references at the same time.

If the reference "refs/heads/foo/bar" exists than the reference "refs/heads/foo" cannot exist, for the same reason.

Parameters:
  `name` - proposed name.
Returns:
  true if the name overlaps with an existing reference; false if using this name right now would be safe.
Throws:
  `IOException` - the database could not be read to check for conflicts.
See Also:
  `getConflictingNames(String)`

#### getConflictingNames

    public Collection<String> getConflictingNames(String name)
                                           throws IOException

Determine if a proposed reference cannot coexist with existing ones. If the passed name already exists, it's not considered a conflict.

Parameters:
  `name` - proposed name to check for conflicts against
Returns:
  a collection of full names of existing refs which would conflict with the passed ref name; empty collection when there are no conflicts
Throws:
  `IOException`
Since:
  2.3
See Also:
  `isNameConflicting(String)`

#### newUpdate

    public abstract RefUpdate newUpdate(String name,
                                        boolean detach)
                                 throws IOException

Create a new update command to create, modify or delete a reference.

Parameters:
  `name` - the name of the reference.
  `detach` - if `true` and `name` is currently a `SymbolicRef`, the update will replace it with an `ObjectIdRef`. Otherwise, the update will recursively traverse `SymbolicRef`s and operate on the leaf `ObjectIdRef`.
Returns:
  a new update for the requested name; never null.
Throws:
  `IOException` - the reference space cannot be accessed.

#### newRename

    public abstract RefRename newRename(String fromName,
                                        String toName)
                                 throws IOException

Create a new update command to rename a reference.

Parameters:
  `fromName` - name of reference to rename from
  `toName` - name of reference to rename to
Returns:
  an update command that knows how to rename a branch to another.
Throws:
  `IOException` - the reference space cannot be accessed.

#### newBatchUpdate

    public BatchRefUpdate newBatchUpdate()

Create a new batch update to attempt on this database.

The default implementation performs a sequential update of each command.

Returns:
  a new batch update object.

#### performsAtomicTransactions

    public boolean performsAtomicTransactions()

Returns:
  if the database performs `newBatchUpdate()` as an atomic transaction.
Since:
  3.6

#### getRef

    public abstract Ref getRef(String name)
                        throws IOException

Read a single reference.

Aside from taking advantage of `SEARCH_PATH`, this method may be able to more quickly resolve a single reference name than obtaining the complete namespace by `getRefs(ALL).get(name)`.

Parameters:
  `name` - the name of the reference. May be a short name which must be searched for using the standard `SEARCH_PATH`.
Returns:
  the reference (if it exists); else `null`.
Throws:
  `IOException` - the reference space cannot be accessed.

#### getRefs

    public abstract Map<String,Ref> getRefs(String prefix)
                                     throws IOException

Get a section of the reference namespace.

Parameters:
  `prefix` - prefix to search the namespace with; must end with `/`. If the empty string (`ALL`), obtain a complete snapshot of all references.
Returns:
  modifiable map that is a complete snapshot of the current reference namespace, with `prefix` removed from the start of each key. The map can be an unsorted map.
Throws:
  `IOException` - the reference space cannot be accessed.

#### getAdditionalRefs

    public abstract List<Ref> getAdditionalRefs()
                                         throws IOException

Get the additional reference-like entities from the repository.

The result list includes non-ref items such as MERGE_HEAD and FETCH_RESULT cast to be refs. The names of these refs are not returned by `getRefs(ALL)` but are accepted by `getRef(String)`

Returns:
  a list of additional refs
Throws:
  `IOException` - the reference space cannot be accessed.

#### peel

    public abstract Ref peel(Ref ref)
                      throws IOException

Peel a possibly unpeeled reference by traversing the annotated tags.

If the reference cannot be peeled (as it does not refer to an annotated tag) the peeled id stays null, but `Ref.isPeeled()` will be true.

Implementors should check `Ref.isPeeled()` before performing any additional work effort.

Parameters:
  `ref` - The reference to peel
Returns:
  `ref` if `ref.isPeeled()` is true; otherwise a new Ref object representing the same data as Ref, but isPeeled() will be true and getPeeledObjectId() will contain the peeled object (or null).
Throws:
  `IOException` - the reference space or object space cannot be accessed.

#### refresh

    public void refresh()

Triggers a refresh of all internal data structures.

In case the RefDatabase implementation has internal caches this method will trigger that all these caches are cleared.

Implementors should overwrite this method if they use any kind of caches.

#### findRef

    public static Ref findRef(Map<String,Ref> map,
                              String name)

Try to find the specified name in the ref map using `SEARCH_PATH`.

Parameters:
  `map` - map of refs to search within. Names should be fully qualified, e.g. "refs/heads/master".
  `name` - short name of ref to find, e.g. "master" to find "refs/heads/master" in map.
Returns:
  The first ref matching the name, or null if not found.
Since:
  3.4