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