diff options
Diffstat (limited to 'org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java')
| -rw-r--r-- | org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java | 128 |
1 files changed, 72 insertions, 56 deletions
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java index f119c44fe2..9c374760b0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java @@ -1,50 +1,21 @@ /* - * Copyright (C) 2006-2008, Shawn O. Pearce <spearce@spearce.org> - * and other copyright owners as documented in the project's IP log. + * Copyright (C) 2006-2008, Shawn O. Pearce <spearce@spearce.org> and others * - * 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 + * This program and the accompanying materials are made available under the + * terms of the Eclipse Distribution License v. 1.0 which is available at + * https://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. + * SPDX-License-Identifier: BSD-3-Clause */ package org.eclipse.jgit.lib; +import org.eclipse.jgit.annotations.NonNull; +import org.eclipse.jgit.annotations.Nullable; + /** - * Pairing of a name and the {@link ObjectId} it currently has. + * 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, @@ -57,7 +28,7 @@ package org.eclipse.jgit.lib; */ public interface Ref { /** Location where a {@link Ref} is stored. */ - public static enum Storage { + enum Storage { /** * The ref does not exist yet, updating it may create it. * <p> @@ -101,12 +72,14 @@ public interface Ref { private final boolean packed; - private Storage(final boolean l, final boolean p) { + private Storage(boolean l, boolean p) { loose = l; packed = p; } /** + * Whether this storage has a loose file + * * @return true if this storage has a loose file. */ public boolean isLoose() { @@ -114,6 +87,8 @@ public interface Ref { } /** + * Whether this storage is inside the packed file + * * @return true if this storage is inside the packed file. */ public boolean isPacked() { @@ -122,23 +97,32 @@ public interface Ref { } /** + * 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. */ - public String getName(); + @NonNull + String getName(); /** * Test if this reference is a symbolic reference. * <p> - * A symbolic reference does not have its own {@link ObjectId} value, but - * instead points to another {@code Ref} in the same database and always - * uses that other reference's value as its own. + * 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. */ - public abstract boolean isSymbolic(); + boolean isSymbolic(); /** * Traverse target references until {@link #isSymbolic()} is false. @@ -156,7 +140,8 @@ public interface Ref { * * @return the reference that actually stores the ObjectId value. */ - public abstract Ref getLeaf(); + @NonNull + Ref getLeaf(); /** * Get the reference this reference points to, or {@code this}. @@ -170,28 +155,35 @@ public interface Ref { * * @return the target reference, or {@code this}. */ - public abstract Ref getTarget(); + @NonNull + Ref getTarget(); /** * Cached value of this ref. * - * @return the value of this ref at the last time we read it. + * @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. */ - public abstract ObjectId getObjectId(); + @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; null if this ref does not - * refer to an annotated tag. + * blob) that the annotated tag refers to; {@code null} if this ref + * does not refer to an annotated tag. */ - public abstract ObjectId getPeeledObjectId(); + @Nullable + ObjectId getPeeledObjectId(); /** - * @return whether the Ref represents a peeled tag + * Whether the Ref represents a peeled tag. + * + * @return whether the Ref represents a peeled tag. */ - public abstract boolean isPeeled(); + boolean isPeeled(); /** * How was this ref obtained? @@ -201,5 +193,29 @@ public interface Ref { * * @return type of ref. */ - public abstract Storage getStorage(); + @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(); + } } |