org.spearce.jgit/src/org/spearce/jgit/lib/Ref.java

   1 /*
   2  * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
   3  *
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or
   7  * without modification, are permitted provided that the following
   8  * conditions are met:
   9  *
  10  * - Redistributions of source code must retain the above copyright
  11  *   notice, this list of conditions and the following disclaimer.
  12  *
  13  * - Redistributions in binary form must reproduce the above
  14  *   copyright notice, this list of conditions and the following
  15  *   disclaimer in the documentation and/or other materials provided
  16  *   with the distribution.
  17  *
  18  * - Neither the name of the Git Development Community nor the
  19  *   names of its contributors may be used to endorse or promote
  20  *   products derived from this software without specific prior
  21  *   written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  24  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  25  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  26  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  28  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  29  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  30  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  33  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  35  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  */
  37
  38 package org.spearce.jgit.lib;
  39
  40 /**
  41  * Pairing of a name and the {@link ObjectId} it currently has.
  42  * <p>
  43  * A ref in Git is (more or less) a variable that holds a single object
  44  * identifier. The object identifier can be any valid Git object (blob, tree,
  45  * commit, annotated tag, ...).
  46  */
  47 public class Ref {
  48         /** Location where a {@link Ref} is stored. */
  49         public static enum Storage {
  50                 /**
  51                  * The ref does not exist yet, updating it may create it.
  52                  * <p>
  53                  * Creation is likely to choose {@link #LOOSE} storage.
  54                  */
  55                 NEW(true, false),
  56
  57                 /**
  58                  * The ref is stored in a file by itself.
  59                  * <p>
  60                  * Updating this ref affects only this ref.
  61                  */
  62                 LOOSE(true, false),
  63
  64                 /**
  65                  * The ref is stored in the <code>packed-refs</code> file, with
  66                  * others.
  67                  * <p>
  68                  * Updating this ref requires rewriting the file, with perhaps many
  69                  * other refs being included at the same time.
  70                  */
  71                 PACKED(false, true),
  72
  73                 /**
  74                  * The ref is both {@link #LOOSE} and {@link #PACKED}.
  75                  * <p>
  76                  * Updating this ref requires only updating the loose file, but deletion
  77                  * requires updating both the loose file and the packed refs file.
  78                  */
  79                 LOOSE_PACKED(true, true),
  80
  81                 /**
  82                  * The ref came from a network advertisement and storage is unknown.
  83                  * <p>
  84                  * This ref cannot be updated without Git-aware support on the remote
  85                  * side, as Git-aware code consolidate the remote refs and reported them
  86                  * to this process.
  87                  */
  88                 NETWORK(false, false);
  89
  90                 private final boolean loose;
  91
  92                 private final boolean packed;
  93
  94                 private Storage(final boolean l, final boolean p) {
  95                         loose = l;
  96                         packed = p;
  97                 }
  98
  99                 /**
 100                  * @return true if this storage has a loose file.
 101                  */
 102                 public boolean isLoose() {
 103                         return loose;
 104                 }
 105
 106                 /**
 107                  * @return true if this storage is inside the packed file.
 108                  */
 109                 public boolean isPacked() {
 110                         return packed;
 111                 }
 112         }
 113
 114         private final Storage storage;
 115
 116         private final String name;
 117
 118         private ObjectId objectId;
 119
 120         private ObjectId peeledObjectId;
 121
 122         /**
 123          * Create a new ref pairing.
 124          *
 125          * @param st
 126          *            method used to store this ref.
 127          * @param refName
 128          *            name of this ref.
 129          * @param id
 130          *            current value of the ref. May be null to indicate a ref that
 131          *            does not exist yet.
 132          */
 133         public Ref(final Storage st, final String refName, final ObjectId id) {
 134                 storage = st;
 135                 name = refName;
 136                 objectId = id;
 137         }
 138
 139         /**
 140          * Create a new ref pairing.
 141          *
 142          * @param st
 143          *            method used to store this ref.
 144          * @param refName
 145          *            name of this ref.
 146          * @param id
 147          *            current value of the ref. May be null to indicate a ref that
 148          *            does not exist yet.
 149          * @param peel
 150          *            peeled value of the ref's tag. May be null if this is not a
 151          *            tag or the peeled value is not known.
 152          */
 153         public Ref(final Storage st, final String refName, final ObjectId id,
 154                         final ObjectId peel) {
 155                 storage = st;
 156                 name = refName;
 157                 objectId = id;
 158                 peeledObjectId = peel;
 159         }
 160
 161         /**
 162          * What this ref is called within the repository.
 163          *
 164          * @return name of this ref.
 165          */
 166         public String getName() {
 167                 return name;
 168         }
 169
 170         /**
 171          * Cached value of this ref.
 172          *
 173          * @return the value of this ref at the last time we read it.
 174          */
 175         public ObjectId getObjectId() {
 176                 return objectId;
 177         }
 178
 179         /**
 180          * Cached value of <code>ref^{}</code> (the ref peeled to commit).
 181          *
 182          * @return if this ref is an annotated tag the id of the commit (or tree or
 183          *         blob) that the annotated tag refers to; null if this ref does not
 184          *         refer to an annotated tag.
 185          */
 186         public ObjectId getPeeledObjectId() {
 187                 return peeledObjectId;
 188         }
 189
 190         /**
 191          * How was this ref obtained?
 192          * <p>
 193          * The current storage model of a Ref may influence how the ref must be
 194          * updated or deleted from the repository.
 195          *
 196          * @return type of ref.
 197          */
 198         public Storage getStorage() {
 199                 return storage;
 200         }
 201
 202         public String toString() {
 203                 return "Ref[" + name + "=" + ObjectId.toString(getObjectId()) + "]";
 204         }
 205 }