1 /*
2 * Copyright (C) 2008-2009, Google Inc.
3 * Copyright (C) 2008, Marek Zawirski <marek.zawirski@gmail.com>
4 * Copyright (C) 2008, Mike Ralphson <mike@abacus.co.uk>
5 * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
6 * and other copyright owners as documented in the project's IP log.
7 *
8 * This program and the accompanying materials are made available
9 * under the terms of the Eclipse Distribution License v1.0 which
10 * accompanies this distribution, is reproduced below, and is
11 * available at http://www.eclipse.org/org/documents/edl-v10.php
12 *
13 * All rights reserved.
14 *
15 * Redistribution and use in source and binary forms, with or
16 * without modification, are permitted provided that the following
17 * conditions are met:
18 *
19 * - Redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer.
21 *
22 * - Redistributions in binary form must reproduce the above
23 * copyright notice, this list of conditions and the following
24 * disclaimer in the documentation and/or other materials provided
25 * with the distribution.
26 *
27 * - Neither the name of the Eclipse Foundation, Inc. nor the
28 * names of its contributors may be used to endorse or promote
29 * products derived from this software without specific prior
30 * written permission.
31 *
32 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
33 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
34 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
35 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
36 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
37 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
38 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
39 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
40 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
41 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
42 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
43 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
44 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
45 */
46
47 package org.eclipse.jgit.transport;
48
49 import java.io.OutputStream;
50 import java.util.Collection;
51 import java.util.Set;
52
53 import org.eclipse.jgit.errors.TransportException;
54 import org.eclipse.jgit.internal.storage.file.PackLock;
55 import org.eclipse.jgit.lib.ObjectId;
56 import org.eclipse.jgit.lib.ProgressMonitor;
57 import org.eclipse.jgit.lib.Ref;
58
59 /**
60 * Lists known refs from the remote and copies objects of selected refs.
61 * <p>
62 * A fetch connection typically connects to the <code>git-upload-pack</code>
63 * service running where the remote repository is stored. This provides a
64 * one-way object transfer service to copy objects from the remote repository
65 * into this local repository.
66 * <p>
67 * Instances of a FetchConnection must be created by a
68 * {@link org.eclipse.jgit.transport.Transport} that implements a specific
69 * object transfer protocol that both sides of the connection understand.
70 * <p>
71 * FetchConnection instances are not thread safe and may be accessed by only one
72 * thread at a time.
73 *
74 * @see Transport
75 */
76 public interface FetchConnection extends Connection {
77 /**
78 * Fetch objects we don't have but that are reachable from advertised refs.
79 * <p>
80 * Only one call per connection is allowed. Subsequent calls will result in
81 * {@link org.eclipse.jgit.errors.TransportException}.
82 * </p>
83 * <p>
84 * Implementations are free to use network connections as necessary to
85 * efficiently (for both client and server) transfer objects from the remote
86 * repository into this repository. When possible implementations should
87 * avoid replacing/overwriting/duplicating an object already available in
88 * the local destination repository. Locally available objects and packs
89 * should always be preferred over remotely available objects and packs.
90 * {@link org.eclipse.jgit.transport.Transport#isFetchThin()} should be
91 * honored if applicable.
92 * </p>
93 *
94 * @param monitor
95 * progress monitor to inform the end-user about the amount of
96 * work completed, or to indicate cancellation. Implementations
97 * should poll the monitor at regular intervals to look for
98 * cancellation requests from the user.
99 * @param want
100 * one or more refs advertised by this connection that the caller
101 * wants to store locally.
102 * @param have
103 * additional objects known to exist in the destination
104 * repository, especially if they aren't yet reachable by the ref
105 * database. Connections should take this set as an addition to
106 * what is reachable through all Refs, not in replace of it.
107 * @throws org.eclipse.jgit.errors.TransportException
108 * objects could not be copied due to a network failure,
109 * protocol error, or error on remote side, or connection was
110 * already used for fetch.
111 */
112 public void fetch(final ProgressMonitor monitor,
113 final Collection<Ref> want, final Set<ObjectId> have)
114 throws TransportException;
115
116 /**
117 * Fetch objects we don't have but that are reachable from advertised refs.
118 * <p>
119 * Only one call per connection is allowed. Subsequent calls will result in
120 * {@link org.eclipse.jgit.errors.TransportException}.
121 * </p>
122 * <p>
123 * Implementations are free to use network connections as necessary to
124 * efficiently (for both client and server) transfer objects from the remote
125 * repository into this repository. When possible implementations should
126 * avoid replacing/overwriting/duplicating an object already available in
127 * the local destination repository. Locally available objects and packs
128 * should always be preferred over remotely available objects and packs.
129 * {@link org.eclipse.jgit.transport.Transport#isFetchThin()} should be
130 * honored if applicable.
131 * </p>
132 *
133 * @param monitor
134 * progress monitor to inform the end-user about the amount of
135 * work completed, or to indicate cancellation. Implementations
136 * should poll the monitor at regular intervals to look for
137 * cancellation requests from the user.
138 * @param want
139 * one or more refs advertised by this connection that the caller
140 * wants to store locally.
141 * @param have
142 * additional objects known to exist in the destination
143 * repository, especially if they aren't yet reachable by the ref
144 * database. Connections should take this set as an addition to
145 * what is reachable through all Refs, not in replace of it.
146 * @param out
147 * OutputStream to write sideband messages to
148 * @throws org.eclipse.jgit.errors.TransportException
149 * objects could not be copied due to a network failure,
150 * protocol error, or error on remote side, or connection was
151 * already used for fetch.
152 * @since 3.0
153 */
154 public void fetch(final ProgressMonitor monitor,
155 final Collection<Ref> want, final Set<ObjectId> have,
156 OutputStream out) throws TransportException;
157
158 /**
159 * Did the last {@link #fetch(ProgressMonitor, Collection, Set)} get tags?
160 * <p>
161 * Some Git aware transports are able to implicitly grab an annotated tag if
162 * {@link org.eclipse.jgit.transport.TagOpt#AUTO_FOLLOW} or
163 * {@link org.eclipse.jgit.transport.TagOpt#FETCH_TAGS} was selected and the
164 * object the tag peels to (references) was transferred as part of the last
165 * {@link #fetch(ProgressMonitor, Collection, Set)} call. If it is possible
166 * for such tags to have been included in the transfer this method returns
167 * true, allowing the caller to attempt tag discovery.
168 * <p>
169 * By returning only true/false (and not the actual list of tags obtained)
170 * the transport itself does not need to be aware of whether or not tags
171 * were included in the transfer.
172 *
173 * @return true if the last fetch call implicitly included tag objects;
174 * false if tags were not implicitly obtained.
175 */
176 public boolean didFetchIncludeTags();
177
178 /**
179 * Did the last {@link #fetch(ProgressMonitor, Collection, Set)} validate
180 * graph?
181 * <p>
182 * Some transports walk the object graph on the client side, with the client
183 * looking for what objects it is missing and requesting them individually
184 * from the remote peer. By virtue of completing the fetch call the client
185 * implicitly tested the object connectivity, as every object in the graph
186 * was either already local or was requested successfully from the peer. In
187 * such transports this method returns true.
188 * <p>
189 * Some transports assume the remote peer knows the Git object graph and is
190 * able to supply a fully connected graph to the client (although it may
191 * only be transferring the parts the client does not yet have). Its faster
192 * to assume such remote peers are well behaved and send the correct
193 * response to the client. In such transports this method returns false.
194 *
195 * @return true if the last fetch had to perform a connectivity check on the
196 * client side in order to succeed; false if the last fetch assumed
197 * the remote peer supplied a complete graph.
198 */
199 public boolean didFetchTestConnectivity();
200
201 /**
202 * Set the lock message used when holding a pack out of garbage collection.
203 * <p>
204 * Callers that set a lock message <b>must</b> ensure they call
205 * {@link #getPackLocks()} after
206 * {@link #fetch(ProgressMonitor, Collection, Set)}, even if an exception
207 * was thrown, and release the locks that are held.
208 *
209 * @param message message to use when holding a pack in place.
210 */
211 public void setPackLockMessage(String message);
212
213 /**
214 * All locks created by the last
215 * {@link #fetch(ProgressMonitor, Collection, Set)} call.
216 *
217 * @return collection (possibly empty) of locks created by the last call to
218 * fetch. The caller must release these after refs are updated in
219 * order to safely permit garbage collection.
220 */
221 public Collection<PackLock> getPackLocks();
222 }