Class RefDatabase
- Direct Known Subclasses:
DfsRefDatabase
,FileReftableDatabase
,RefDirectory
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
FieldsModifier and TypeFieldDescriptionstatic final String
Magic value forgetRefsByPrefix(String)
to return all references.static final int
Maximum number of times aSymbolicRef
can be traversed.protected static final String[]
Order of prefixes to search when using non-absolute references. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract void
close()
Close any resources held by this database.abstract void
create()
Initialize a new reference database at this location.abstract Ref
Read a single reference.Read the specified references.final Ref
Read a single reference.static Ref
Try to find the specified name in the ref map usingSEARCH_PATH
.firstExactRef
(String... refs) Find the first named reference.Get the additional reference-like entities from the repository.getConflictingNames
(String name) Determine if a proposed reference cannot coexist with existing ones.final Ref
Deprecated.getRefs()
Returns all refs.Deprecated.usegetRefsByPrefix(java.lang.String)
insteadgetRefsByPrefix
(String prefix) Returns refs whose names start with a given prefix.getRefsByPrefix
(String... prefixes) Returns refs whose names start with one of the given prefixes.getRefsByPrefixWithExclusions
(String include, Set<String> excludes) Returns refs whose names start with a given prefix excluding all refs that start with one of the given prefixes.Returns all refs that resolve directly to the givenObjectId
.boolean
If the ref database does not support fast inverse queries, it may be advantageous to build a complete SHA1 to ref map in advance for multiple uses.boolean
hasRefs()
Check if any refs exist in the ref database.boolean
With versioning, each reference has a version number that increases on update.abstract boolean
isNameConflicting
(String name) Determine if a proposed reference name overlaps with an existing one.Create a new batch update to attempt on this database.abstract RefRename
Create a new update command to rename a reference.abstract RefUpdate
Create a new update command to create, modify or delete a reference.abstract Ref
Peel a possibly unpeeled reference by traversing the annotated tags.boolean
Whether the database is capable of performing batch updates as atomic transactions.void
refresh()
Triggers a refresh of all internal data structures.
-
Field Details
-
SEARCH_PATH
Order of prefixes to search when using non-absolute references.findRef(String)
takes 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_DEPTHMaximum number of times aSymbolicRef
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:
-
ALL
Magic value forgetRefsByPrefix(String)
to return all references.- See Also:
-
-
Constructor Details
-
RefDatabase
public RefDatabase()
-
-
Method Details
-
create
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. -
hasVersioning
public boolean hasVersioning()With versioning, each reference has a version number that increases on update. SeeRef.getUpdateIndex()
.- Returns:
- true if the implementation assigns update indices to references.
- Since:
- 5.3
-
isNameConflicting
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
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:
-
newUpdate
Create a new update command to create, modify or delete a reference.- Parameters:
name
- the name of the reference.detach
- iftrue
andname
is currently aSymbolicRef
, the update will replace it with anObjectIdRef
. Otherwise, the update will recursively traverseSymbolicRef
s and operate on the leafObjectIdRef
.- Returns:
- a new update for the requested name; never null.
- Throws:
IOException
- the reference space cannot be accessed.
-
newRename
Create a new update command to rename a reference.- Parameters:
fromName
- name of reference to rename fromtoName
- 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
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 callingupdate.setAtomic(false)
.If false,
BatchRefUpdate
instances will never perform updates atomically, and callingupdate.setAtomic(true)
will cause the entire batch to fail withREJECTED_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
Deprecated.UsefindRef(String)
instead.Compatibility synonym forfindRef(String)
.- Parameters:
name
- the name of the reference. May be a short name which must be searched for using the standardSEARCH_PATH
.- Returns:
- the reference (if it exists); else
null
. - Throws:
IOException
- the reference space cannot be accessed.
-
findRef
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 bygetRefs(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 standardSEARCH_PATH
.- Returns:
- the reference (if it exists); else
null
. - Throws:
IOException
- the reference space cannot be accessed.- Since:
- 5.3
-
exactRef
Read a single reference.Unlike
findRef(java.lang.String)
, this method expects an unshortened reference name and does not search using the standardSEARCH_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
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
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
Returns all refs.This includes
HEAD
, branches underref/heads/
, tags underrefs/tags/
, etc. It does not include pseudo-refs likeFETCH_HEAD
; for those, seegetAdditionalRefs()
.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
Deprecated.usegetRefsByPrefix(java.lang.String)
insteadGet 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
Returns refs whose names start with a given prefix.The default implementation uses
getRefs(String)
. Implementors ofRefDatabase
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
-
getRefsByPrefixWithExclusions
@NonNull public List<Ref> getRefsByPrefixWithExclusions(String include, Set<String> excludes) throws IOException Returns refs whose names start with a given prefix excluding all refs that start with one of the given prefixes.The default implementation is not efficient. Implementors of
RefDatabase
should override this method directly if a better implementation is possible.- Parameters:
include
- string that names of refs should start with; may be empty.excludes
- strings that names of refs can't start with; may be empty.- Returns:
- immutable list of refs whose names start with
prefix
and none of the strings inexclude
. - Throws:
IOException
- the reference space cannot be accessed.- Since:
- 5.11
-
getRefsByPrefix
Returns refs whose names start with one of the given prefixes.The default implementation uses
getRefsByPrefix(String)
. Implementors ofRefDatabase
should override this method directly if a better implementation is possible.- Parameters:
prefixes
- strings that names of refs should start with.- Returns:
- immutable list of refs whose names start with one of
prefixes
. Refs can be unsorted and may contain duplicates if the prefixes overlap. - Throws:
IOException
- the reference space cannot be accessed.- Since:
- 5.2
-
getTipsWithSha1
Returns all refs that resolve directly to the givenObjectId
. Includes peeledObjectId
s. This is the inverse lookup ofexactRef(String...)
.The default implementation uses a linear scan. Implementors of
RefDatabase
should override this method directly if a better implementation is possible.- Parameters:
id
-ObjectId
to resolve- Returns:
- a
Set
ofRef
s whose tips point to the provided id. - Throws:
IOException
- the reference space cannot be accessed.- Since:
- 5.4
-
hasFastTipsWithSha1
If the ref database does not support fast inverse queries, it may be advantageous to build a complete SHA1 to ref map in advance for multiple uses. To let applications decide on this decision, this function indicates whether the inverse map is available.- Returns:
- whether this RefDatabase supports fast inverse ref queries.
- Throws:
IOException
- on I/O problems.- Since:
- 5.6
-
hasRefs
Check if any refs exist in the ref database.This uses the same definition of refs as
getRefs()
. In particular, returnsfalse
in a new repository with no refs underrefs/
andHEAD
pointing to a branch yet to be born, and returnstrue
in a repository with no refs underrefs/
and a detachedHEAD
pointing to history.- Returns:
- true if the database has refs.
- Throws:
IOException
- the reference space cannot be accessed.- Since:
- 5.0
-
getAdditionalRefs
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 byfindRef(String)
andexactRef(String)
.- Returns:
- a list of additional refs
- Throws:
IOException
- the reference space cannot be accessed.
-
peel
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
ifref.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 (ornull
).- 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
Try to find the specified name in the ref map usingSEARCH_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
-
findRef(String)
instead.