123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397 |
- /*
- * Copyright (C) 2010, 2013 Google Inc.
- * and other copyright owners as documented in the project's IP log.
- *
- * This program and the accompanying materials are made available
- * under the terms of the Eclipse Distribution License v1.0 which
- * accompanies this distribution, is reproduced below, and is
- * available at http://www.eclipse.org/org/documents/edl-v10.php
- *
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or
- * without modification, are permitted provided that the following
- * conditions are met:
- *
- * - Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * - Redistributions in binary form must reproduce the above
- * copyright notice, this list of conditions and the following
- * disclaimer in the documentation and/or other materials provided
- * with the distribution.
- *
- * - Neither the name of the Eclipse Foundation, Inc. nor the
- * names of its contributors may be used to endorse or promote
- * products derived from this software without specific prior
- * written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
- * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
- * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
- * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
- * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
- * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
- package org.eclipse.jgit.lib;
-
- import java.io.IOException;
- import java.util.ArrayList;
- import java.util.Collection;
- import java.util.Collections;
- import java.util.HashMap;
- import java.util.List;
- import java.util.Map;
-
- import org.eclipse.jgit.annotations.NonNull;
- import org.eclipse.jgit.annotations.Nullable;
-
- /**
- * Abstraction of name to {@link ObjectId} mapping.
- * <p>
- * 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.
- * <p>
- * 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.
- * <p>
- * 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
- */
- public 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.
- * <p>
- * Reference names use '/' as a component separator, and may be stored in a
- * hierarchical storage such as a directory on the local filesystem.
- * <p>
- * 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.
- * <p>
- * 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.
- * @see #getConflictingNames(String)
- */
- public abstract boolean isNameConflicting(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.
- *
- * @param name
- * proposed name to check for conflicts against
- * @return 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 #isNameConflicting(String)
- */
- @NonNull
- public Collection<String> getConflictingNames(String name)
- throws IOException {
- Map<String, Ref> allRefs = getRefs(ALL);
- // Cannot be nested within an existing reference.
- int lastSlash = name.lastIndexOf('/');
- while (0 < lastSlash) {
- String needle = name.substring(0, lastSlash);
- if (allRefs.containsKey(needle))
- return Collections.singletonList(needle);
- lastSlash = name.lastIndexOf('/', lastSlash - 1);
- }
-
- List<String> conflicting = new ArrayList<String>();
- // Cannot be the container of an existing reference.
- String prefix = name + '/';
- for (String existing : allRefs.keySet())
- if (existing.startsWith(prefix))
- conflicting.add(existing);
-
- return conflicting;
- }
-
- /**
- * 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.
- */
- @NonNull
- 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.
- */
- @NonNull
- public abstract RefRename newRename(String fromName, String toName)
- throws IOException;
-
- /**
- * Create a new batch update to attempt on this database.
- * <p>
- * The default implementation performs a sequential update of each command.
- *
- * @return a new batch update object.
- */
- @NonNull
- public BatchRefUpdate newBatchUpdate() {
- return new BatchRefUpdate(this);
- }
-
- /**
- * @return if the database performs {@code newBatchUpdate()} as an atomic
- * transaction.
- * @since 3.6
- */
- public boolean performsAtomicTransactions() {
- return false;
- }
-
- /**
- * Read a single reference.
- * <p>
- * 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)}.
- * <p>
- * To read a specific reference without using @{link #SEARCH_PATH}, see
- * {@link #exactRef(String)}.
- *
- * @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.
- */
- @Nullable
- public abstract Ref getRef(String name) throws IOException;
-
- /**
- * Read a single reference.
- * <p>
- * Unlike {@link #getRef}, this method expects an unshortened reference
- * name and does not search using the standard {@link #SEARCH_PATH}.
- *
- * @param name
- * the unabbreviated name of the reference.
- * @return the reference (if it exists); else {@code null}.
- * @throws IOException
- * the reference space cannot be accessed.
- * @since 4.1
- */
- @Nullable
- public Ref exactRef(String name) throws IOException {
- Ref ref = getRef(name);
- if (ref == null || !name.equals(ref.getName())) {
- return null;
- }
- return ref;
- }
-
- /**
- * Read the specified references.
- * <p>
- * 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.
- *
- * @param refs
- * the unabbreviated names of references to look up.
- * @return 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
- */
- @NonNull
- public Map<String, Ref> exactRef(String... refs) throws IOException {
- Map<String, Ref> result = new HashMap<>(refs.length);
- for (String name : refs) {
- Ref ref = exactRef(name);
- if (ref != null) {
- result.put(name, ref);
- }
- }
- return result;
- }
-
- /**
- * Find the first named reference.
- * <p>
- * This method expects a list of unshortened reference names and returns
- * the first that exists.
- *
- * @param refs
- * the unabbreviated names of references to look up.
- * @return the first named reference that exists (if any); else {@code null}.
- * @throws IOException
- * the reference space cannot be accessed.
- * @since 4.1
- */
- @Nullable
- public Ref firstExactRef(String... refs) throws IOException {
- for (String name : refs) {
- Ref ref = exactRef(name);
- if (ref != null) {
- return ref;
- }
- }
- return null;
- }
-
- /**
- * 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.
- */
- @NonNull
- public abstract Map<String, Ref> getRefs(String prefix) throws IOException;
-
- /**
- * Get the additional reference-like entities from the repository.
- * <p>
- * 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
- * <code>getRefs(ALL)</code> but are accepted by {@link #getRef(String)}
- * and {@link #exactRef(String)}.
- *
- * @return a list of additional refs
- * @throws IOException
- * the reference space cannot be accessed.
- */
- @NonNull
- public abstract List<Ref> getAdditionalRefs() throws IOException;
-
- /**
- * Peel a possibly unpeeled reference by traversing the annotated tags.
- * <p>
- * 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.
- * <p>
- * 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 {@code null}).
- * @throws IOException
- * the reference space or object space cannot be accessed.
- */
- @NonNull
- public abstract Ref peel(Ref ref) throws IOException;
-
- /**
- * Triggers a refresh of all internal data structures.
- * <p>
- * In case the RefDatabase implementation has internal caches this method
- * will trigger that all these caches are cleared.
- * <p>
- * Implementors should overwrite this method if they use any kind of caches.
- */
- public void refresh() {
- // nothing
- }
-
- /**
- * Try to find the specified name in the ref map using {@link #SEARCH_PATH}.
- *
- * @param map
- * map of refs to search within. Names should be fully qualified,
- * e.g. "refs/heads/master".
- * @param name
- * short name of ref to find, e.g. "master" to find
- * "refs/heads/master" in map.
- * @return The first ref matching the name, or {@code null} if not found.
- * @since 3.4
- */
- @Nullable
- public static Ref findRef(Map<String, Ref> map, String name) {
- for (String prefix : SEARCH_PATH) {
- String fullname = prefix + name;
- Ref ref = map.get(fullname);
- if (ref != null)
- return ref;
- }
- return null;
- }
- }
|