/*
* 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);
}
/**
* Whether the database is capable of performing batch updates as atomic
* transactions.
* <p>
* If true, by default {@link 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 {@code update.setAtomic(false)}.
* <p>
* If false, {@link BatchRefUpdate} instances will never perform updates
* atomically, and calling {@code update.setAtomic(true)} will cause the
* entire batch to fail with {@code REJECTED_OTHER_REASON}.
* <p>
* This definition of atomicity is stronger than what is provided by
* {@link org.eclipse.jgit.transport.ReceivePack}. {@code 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.
*
* @return whether transactions are atomic by default.
* @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;
}
}