* A reference database stores a mapping of reference names to {@link ObjectId}. * Every {@link Repository} has a single reference database, mapping names to * the tips of the object graph contained by the {@link ObjectDatabase}. */ public abstract class RefDatabase { /** * Order of prefixes to search when using non-absolute references. *
* The implementation's {@link #getRef(String)} method must take this search * space into consideration when locating a reference by name. The first * entry in the path is always {@code ""}, ensuring that absolute references * are resolved without further mangling. */ protected static final String[] SEARCH_PATH = { "", //$NON-NLS-1$ Constants.R_REFS, // Constants.R_TAGS, // Constants.R_HEADS, // Constants.R_REMOTES // }; /** * Maximum number of times a {@link 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. */ protected static final int MAX_SYMBOLIC_REF_DEPTH = 5; /** Magic value for {@link #getRefs(String)} to return all references. */ public static final String ALL = "";//$NON-NLS-1$ /** * Initialize a new reference database at this location. * * @throws IOException * the database could not be created. */ public abstract void create() throws IOException; /** Close any resources held by this database. */ public abstract void close(); /** * 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. * * @param name * proposed name. * @return 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. */ public abstract boolean isNameConflicting(String name) throws IOException; /** * Create a new update command to create, modify or delete a reference. * * @param name * the name of the reference. * @param detach * if {@code true} and {@code name} is currently a * {@link SymbolicRef}, the update will replace it with an * {@link ObjectIdRef}. Otherwise, the update will recursively * traverse {@link SymbolicRef}s and operate on the leaf * {@link ObjectIdRef}. * @return a new update for the requested name; never null. * @throws IOException * the reference space cannot be accessed. */ public abstract RefUpdate newUpdate(String name, boolean detach) throws IOException; /** * Create a new update command to rename a reference. * * @param fromName * name of reference to rename from * @param toName * name of reference to rename to * @return an update command that knows how to rename a branch to another. * @throws IOException * the reference space cannot be accessed. */ public abstract RefRename newRename(String fromName, String toName) throws IOException; /** * Read a single reference. *
* Aside from taking advantage of {@link #SEARCH_PATH}, this method may be
* able to more quickly resolve a single reference name than obtaining the
* complete namespace by {@code getRefs(ALL).get(name)}.
*
* @param name
* the name of the reference. May be a short name which must be
* searched for using the standard {@link #SEARCH_PATH}.
* @return the reference (if it exists); else {@code null}.
* @throws IOException
* the reference space cannot be accessed.
*/
public abstract Ref getRef(String name) throws IOException;
/**
* Get a section of the reference namespace.
*
* @param prefix
* prefix to search the namespace with; must end with {@code /}.
* If the empty string ({@link #ALL}), obtain a complete snapshot
* of all references.
* @return modifiable map that is a complete snapshot of the current
* reference namespace, with {@code prefix} removed from the start
* of each key. The map can be an unsorted map.
* @throws IOException
* the reference space cannot be accessed.
*/
public abstract Map
* 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
*
* If the reference cannot be peeled (as it does not refer to an annotated
* tag) the peeled id stays null, but {@link Ref#isPeeled()} will be true.
*
* Implementors should check {@link Ref#isPeeled()} before performing any
* additional work effort.
*
* @param ref
* The reference to peel
* @return {@code ref} if {@code 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.
*/
public abstract Ref peel(Ref ref) throws IOException;
/**
* 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.
*/
public void refresh() {
// nothing
}
}
getRefs(ALL) but are accepted by {@link #getRef(String)}
*
* @return a list of additional refs
* @throws IOException
* the reference space cannot be accessed.
*/
public abstract List getAdditionalRefs() throws IOException;
/**
* Peel a possibly unpeeled reference by traversing the annotated tags.
*