| /* |
| * Copyright (C) 2006-2008, Shawn O. Pearce <spearce@spearce.org> |
| * 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 org.eclipse.jgit.annotations.NonNull; |
| import org.eclipse.jgit.annotations.Nullable; |
| |
| /** |
| * Pairing of a name and the {@link org.eclipse.jgit.lib.ObjectId} it currently |
| * has. |
| * <p> |
| * A ref in Git is (more or less) a variable that holds a single object |
| * identifier. The object identifier can be any valid Git object (blob, tree, |
| * commit, annotated tag, ...). |
| * <p> |
| * The ref name has the attributes of the ref that was asked for as well as the |
| * ref it was resolved to for symbolic refs plus the object id it points to and |
| * (for tags) the peeled target object id, i.e. the tag resolved recursively |
| * until a non-tag object is referenced. |
| */ |
| public interface Ref { |
| /** Location where a {@link Ref} is stored. */ |
| enum Storage { |
| /** |
| * The ref does not exist yet, updating it may create it. |
| * <p> |
| * Creation is likely to choose {@link #LOOSE} storage. |
| */ |
| NEW(true, false), |
| |
| /** |
| * The ref is stored in a file by itself. |
| * <p> |
| * Updating this ref affects only this ref. |
| */ |
| LOOSE(true, false), |
| |
| /** |
| * The ref is stored in the <code>packed-refs</code> file, with others. |
| * <p> |
| * Updating this ref requires rewriting the file, with perhaps many |
| * other refs being included at the same time. |
| */ |
| PACKED(false, true), |
| |
| /** |
| * The ref is both {@link #LOOSE} and {@link #PACKED}. |
| * <p> |
| * Updating this ref requires only updating the loose file, but deletion |
| * requires updating both the loose file and the packed refs file. |
| */ |
| LOOSE_PACKED(true, true), |
| |
| /** |
| * The ref came from a network advertisement and storage is unknown. |
| * <p> |
| * This ref cannot be updated without Git-aware support on the remote |
| * side, as Git-aware code consolidate the remote refs and reported them |
| * to this process. |
| */ |
| NETWORK(false, false); |
| |
| private final boolean loose; |
| |
| private final boolean packed; |
| |
| private Storage(boolean l, boolean p) { |
| loose = l; |
| packed = p; |
| } |
| |
| /** |
| * @return true if this storage has a loose file. |
| */ |
| public boolean isLoose() { |
| return loose; |
| } |
| |
| /** |
| * @return true if this storage is inside the packed file. |
| */ |
| public boolean isPacked() { |
| return packed; |
| } |
| } |
| |
| /** |
| * Update index value when a reference doesn't have one |
| * |
| * @since 5.4 |
| */ |
| long UNDEFINED_UPDATE_INDEX = -1L; |
| |
| /** |
| * What this ref is called within the repository. |
| * |
| * @return name of this ref. |
| */ |
| @NonNull |
| String getName(); |
| |
| /** |
| * Test if this reference is a symbolic reference. |
| * <p> |
| * A symbolic reference does not have its own |
| * {@link org.eclipse.jgit.lib.ObjectId} value, but instead points to |
| * another {@code Ref} in the same database and always uses that other |
| * reference's value as its own. |
| * |
| * @return true if this is a symbolic reference; false if this reference |
| * contains its own ObjectId. |
| */ |
| boolean isSymbolic(); |
| |
| /** |
| * Traverse target references until {@link #isSymbolic()} is false. |
| * <p> |
| * If {@link #isSymbolic()} is false, returns {@code this}. |
| * <p> |
| * If {@link #isSymbolic()} is true, this method recursively traverses |
| * {@link #getTarget()} until {@link #isSymbolic()} returns false. |
| * <p> |
| * This method is effectively |
| * |
| * <pre> |
| * return isSymbolic() ? getTarget().getLeaf() : this; |
| * </pre> |
| * |
| * @return the reference that actually stores the ObjectId value. |
| */ |
| @NonNull |
| Ref getLeaf(); |
| |
| /** |
| * Get the reference this reference points to, or {@code this}. |
| * <p> |
| * If {@link #isSymbolic()} is true this method returns the reference it |
| * directly names, which might not be the leaf reference, but could be |
| * another symbolic reference. |
| * <p> |
| * If this is a leaf level reference that contains its own ObjectId,this |
| * method returns {@code this}. |
| * |
| * @return the target reference, or {@code this}. |
| */ |
| @NonNull |
| Ref getTarget(); |
| |
| /** |
| * Cached value of this ref. |
| * |
| * @return the value of this ref at the last time we read it. May be |
| * {@code null} to indicate a ref that does not exist yet or a |
| * symbolic ref pointing to an unborn branch. |
| */ |
| @Nullable |
| ObjectId getObjectId(); |
| |
| /** |
| * Cached value of <code>ref^{}</code> (the ref peeled to commit). |
| * |
| * @return if this ref is an annotated tag the id of the commit (or tree or |
| * blob) that the annotated tag refers to; {@code null} if this ref |
| * does not refer to an annotated tag. |
| */ |
| @Nullable |
| ObjectId getPeeledObjectId(); |
| |
| /** |
| * Whether the Ref represents a peeled tag. |
| * |
| * @return whether the Ref represents a peeled tag. |
| */ |
| boolean isPeeled(); |
| |
| /** |
| * How was this ref obtained? |
| * <p> |
| * The current storage model of a Ref may influence how the ref must be |
| * updated or deleted from the repository. |
| * |
| * @return type of ref. |
| */ |
| @NonNull |
| Storage getStorage(); |
| |
| /** |
| * Indicator of the relative order between updates of a specific reference |
| * name. A number that increases when a reference is updated. |
| * <p> |
| * With symbolic references, the update index refers to updates of the |
| * symbolic reference itself. For example, if HEAD points to |
| * refs/heads/master, then the update index for exactRef("HEAD") will only |
| * increase when HEAD changes to point to another ref, regardless of how |
| * many times refs/heads/master is updated. |
| * <p> |
| * Should not be used unless the {@code RefDatabase} that instantiated the |
| * ref supports versioning (see {@link RefDatabase#hasVersioning()}) |
| * |
| * @return the update index (i.e. version) of this reference. |
| * @throws UnsupportedOperationException |
| * if the creator of the instance (e.g. {@link RefDatabase}) |
| * doesn't support versioning and doesn't override this method |
| * @since 5.3 |
| */ |
| default long getUpdateIndex() { |
| throw new UnsupportedOperationException(); |
| } |
| } |