RefDatabase (JGit - Parent 5.1.15.202012011955-r API)

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

Direct Known Subclasses:

DfsRefDatabase, RefDirectory, RefTreeDatabase
```
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
Modifier and Type	Field and Description
`static String`	`ALL` Magic value for `getRefsByPrefix(String)` to return all references.
`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()

Constructors
Constructor and Description
`RefDatabase()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`abstract void`	`close()` Close any resources held by this database.
`abstract void`	`create()` Initialize a new reference database at this location.
`Map<String,Ref>`	`exactRef(String... refs)` Read the specified references.
`Ref`	`exactRef(String name)` Read a single reference.
`static Ref`	`findRef(Map<String,Ref> map, String name)` Try to find the specified name in the ref map using `SEARCH_PATH`.
`Ref`	`firstExactRef(String... refs)` Find the first named reference.
`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.
`List<Ref>`	`getRefs()` Returns all refs.
`abstract Map<String,Ref>`	`getRefs(String prefix)` Deprecated. use `getRefsByPrefix(java.lang.String)` instead
`List<Ref>`	`getRefsByPrefix(String prefix)` Returns refs whose names start with a given prefix.
`boolean`	`hasRefs()` Check if any refs exist in the ref database.
`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()` Whether the database is capable of performing batch updates as atomic transactions.
`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
```
public 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.
    
    Since:
    
    4.2
    
    See Also:
    
    Constant Field Values
  - ALL
```
public static final String ALL
```
    Magic value for getRefsByPrefix(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
```
@NonNull
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
```
@NonNull
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 SymbolicRefs 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
```
@NonNull
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
```
@NonNull
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()
```
    Whether the database is capable of performing batch updates as atomic transactions.
    If true, by default BatchRefUpdate instances will perform updates atomically, meaning either all updates will succeed, or all updates will fail. It is still possible to turn off this behavior on a per-batch basis by calling update.setAtomic(false).
    If false, BatchRefUpdate instances will never perform updates atomically, and calling update.setAtomic(true) will cause the entire batch to fail with REJECTED_OTHER_REASON.
    This definition of atomicity is stronger than what is provided by ReceivePack. ReceivePack will attempt to reject all commands if it knows in advance some commands may fail, even if the storage layer does not support atomic transactions. Here, atomicity applies even in the case of unforeseeable errors.
    
    Returns:
    
    whether transactions are atomic by default.
    
    Since:
    
    3.6
  - getRef
```
@Nullable
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).
    To read a specific reference without using @{link #SEARCH_PATH}, see exactRef(String).
    
    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.
  - exactRef
```
@Nullable
public Ref exactRef(String name)
                       throws IOException
```
    Read a single reference.
    Unlike getRef(java.lang.String), this method expects an unshortened reference name and does not search using the standard SEARCH_PATH.
    
    Parameters:
    
    name - the unabbreviated name of the reference.
    
    Returns:
    
    the reference (if it exists); else null.
    
    Throws:
    
    IOException - the reference space cannot be accessed.
    
    Since:
    
    4.1
  - exactRef
```
@NonNull
public Map<String,Ref> exactRef(String... refs)
                                  throws IOException
```
    Read the specified references.
    This method expects a list of unshortened reference names and returns a map from reference names to refs. Any named references that do not exist will not be included in the returned map.
    
    Parameters:
    
    refs - the unabbreviated names of references to look up.
    
    Returns:
    
    modifiable map describing any refs that exist among the ref ref names supplied. The map can be an unsorted map.
    
    Throws:
    
    IOException - the reference space cannot be accessed.
    
    Since:
    
    4.1
  - firstExactRef
```
@Nullable
public Ref firstExactRef(String... refs)
                            throws IOException
```
    Find the first named reference.
    This method expects a list of unshortened reference names and returns the first that exists.
    
    Parameters:
    
    refs - the unabbreviated names of references to look up.
    
    Returns:
    
    the first named reference that exists (if any); else null.
    
    Throws:
    
    IOException - the reference space cannot be accessed.
    
    Since:
    
    4.1
  - getRefs
```
@NonNull
public List<Ref> getRefs()
                           throws IOException
```
    Returns all refs.
    This includes HEAD, branches under ref/heads/, tags under refs/tags/, etc. It does not include pseudo-refs like FETCH_HEAD; for those, see getAdditionalRefs().
    Symbolic references to a non-existent ref (for example, HEAD pointing to a branch yet to be born) are not included.
    Callers interested in only a portion of the ref hierarchy can call getRefsByPrefix(java.lang.String) instead.
    
    Returns:
    
    immutable list of all refs.
    
    Throws:
    
    IOException - the reference space cannot be accessed.
    
    Since:
    
    5.0
  - getRefs
```
@NonNull
 @Deprecated
public abstract Map<String,Ref> getRefs(String prefix)
                                                       throws IOException
```
    Deprecated. use getRefsByPrefix(java.lang.String) instead
    
    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.
  - getRefsByPrefix
```
@NonNull
public List<Ref> getRefsByPrefix(String prefix)
                                   throws IOException
```
    Returns refs whose names start with a given prefix.
    The default implementation uses getRefs(String). Implementors of RefDatabase should override this method directly if a better implementation is possible.
    
    Parameters:
    
    prefix - string that names of refs should start with; may be empty (to return all refs).
    
    Returns:
    
    immutable list of refs whose names start with prefix.
    
    Throws:
    
    IOException - the reference space cannot be accessed.
    
    Since:
    
    5.0
  - hasRefs
```
public boolean hasRefs()
                throws IOException
```
    Check if any refs exist in the ref database.
    This uses the same definition of refs as getRefs(). In particular, returns false in a new repository with no refs under refs/ and HEAD pointing to a branch yet to be born, and returns true in a repository with no refs under refs/ and a detached HEAD pointing to history.
    
    Returns:
    
    true if the database has refs.
    
    Throws:
    
    IOException - the reference space cannot be accessed.
    
    Since:
    
    5.0
  - getAdditionalRefs
```
@NonNull
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() but are accepted by getRef(String) and exactRef(String).
    
    Returns:
    
    a list of additional refs
    
    Throws:
    
    IOException - the reference space cannot be accessed.
  - peel
```
@NonNull
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
```
@Nullable
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

Class RefDatabase

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SEARCH_PATH

MAX_SYMBOLIC_REF_DEPTH

ALL

Constructor Detail

RefDatabase

Method Detail

create

close

isNameConflicting

getConflictingNames

newUpdate

newRename

newBatchUpdate

performsAtomicTransactions

getRef

exactRef

exactRef

firstExactRef

getRefs

getRefs

getRefsByPrefix

hasRefs

getAdditionalRefs

peel

refresh

findRef