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> and others
6 *
7 * This program and the accompanying materials are made available under the
8 * terms of the Eclipse Distribution License v. 1.0 which is available at
9 * https://www.eclipse.org/org/documents/edl-v10.php.
10 *
11 * SPDX-License-Identifier: BSD-3-Clause
12 */
13
14 package org.eclipse.jgit.transport;
15
16 import java.io.OutputStream;
17 import java.util.Collection;
18 import java.util.Set;
19
20 import org.eclipse.jgit.errors.TransportException;
21 import org.eclipse.jgit.internal.storage.file.PackLock;
22 import org.eclipse.jgit.lib.ObjectId;
23 import org.eclipse.jgit.lib.ProgressMonitor;
24 import org.eclipse.jgit.lib.Ref;
25
26 /**
27 * Lists known refs from the remote and copies objects of selected refs.
28 * <p>
29 * A fetch connection typically connects to the <code>git-upload-pack</code>
30 * service running where the remote repository is stored. This provides a
31 * one-way object transfer service to copy objects from the remote repository
32 * into this local repository.
33 * <p>
34 * Instances of a FetchConnection must be created by a
35 * {@link org.eclipse.jgit.transport.Transport} that implements a specific
36 * object transfer protocol that both sides of the connection understand.
37 * <p>
38 * FetchConnection instances are not thread safe and may be accessed by only one
39 * thread at a time.
40 *
41 * @see Transport
42 */
43 public interface FetchConnection extends Connection {
44 /**
45 * Fetch objects we don't have but that are reachable from advertised refs.
46 * <p>
47 * Only one call per connection is allowed. Subsequent calls will result in
48 * {@link org.eclipse.jgit.errors.TransportException}.
49 * </p>
50 * <p>
51 * Implementations are free to use network connections as necessary to
52 * efficiently (for both client and server) transfer objects from the remote
53 * repository into this repository. When possible implementations should
54 * avoid replacing/overwriting/duplicating an object already available in
55 * the local destination repository. Locally available objects and packs
56 * should always be preferred over remotely available objects and packs.
57 * {@link org.eclipse.jgit.transport.Transport#isFetchThin()} should be
58 * honored if applicable.
59 * </p>
60 *
61 * @param monitor
62 * progress monitor to inform the end-user about the amount of
63 * work completed, or to indicate cancellation. Implementations
64 * should poll the monitor at regular intervals to look for
65 * cancellation requests from the user.
66 * @param want
67 * one or more refs advertised by this connection that the caller
68 * wants to store locally.
69 * @param have
70 * additional objects known to exist in the destination
71 * repository, especially if they aren't yet reachable by the ref
72 * database. Connections should take this set as an addition to
73 * what is reachable through all Refs, not in replace of it.
74 * @throws org.eclipse.jgit.errors.TransportException
75 * objects could not be copied due to a network failure,
76 * protocol error, or error on remote side, or connection was
77 * already used for fetch.
78 */
79 void fetch(final ProgressMonitor monitor,
80 final Collection<Ref> want, final Set<ObjectId> have)
81 throws TransportException;
82
83 /**
84 * Fetch objects we don't have but that are reachable from advertised refs.
85 * <p>
86 * Only one call per connection is allowed. Subsequent calls will result in
87 * {@link org.eclipse.jgit.errors.TransportException}.
88 * </p>
89 * <p>
90 * Implementations are free to use network connections as necessary to
91 * efficiently (for both client and server) transfer objects from the remote
92 * repository into this repository. When possible implementations should
93 * avoid replacing/overwriting/duplicating an object already available in
94 * the local destination repository. Locally available objects and packs
95 * should always be preferred over remotely available objects and packs.
96 * {@link org.eclipse.jgit.transport.Transport#isFetchThin()} should be
97 * honored if applicable.
98 * </p>
99 *
100 * @param monitor
101 * progress monitor to inform the end-user about the amount of
102 * work completed, or to indicate cancellation. Implementations
103 * should poll the monitor at regular intervals to look for
104 * cancellation requests from the user.
105 * @param want
106 * one or more refs advertised by this connection that the caller
107 * wants to store locally.
108 * @param have
109 * additional objects known to exist in the destination
110 * repository, especially if they aren't yet reachable by the ref
111 * database. Connections should take this set as an addition to
112 * what is reachable through all Refs, not in replace of it.
113 * @param out
114 * OutputStream to write sideband messages to
115 * @throws org.eclipse.jgit.errors.TransportException
116 * objects could not be copied due to a network failure,
117 * protocol error, or error on remote side, or connection was
118 * already used for fetch.
119 * @since 3.0
120 */
121 void fetch(final ProgressMonitor monitor,
122 final Collection<Ref> want, final Set<ObjectId> have,
123 OutputStream out) throws TransportException;
124
125 /**
126 * Did the last {@link #fetch(ProgressMonitor, Collection, Set)} get tags?
127 * <p>
128 * Some Git aware transports are able to implicitly grab an annotated tag if
129 * {@link org.eclipse.jgit.transport.TagOpt#AUTO_FOLLOW} or
130 * {@link org.eclipse.jgit.transport.TagOpt#FETCH_TAGS} was selected and the
131 * object the tag peels to (references) was transferred as part of the last
132 * {@link #fetch(ProgressMonitor, Collection, Set)} call. If it is possible
133 * for such tags to have been included in the transfer this method returns
134 * true, allowing the caller to attempt tag discovery.
135 * <p>
136 * By returning only true/false (and not the actual list of tags obtained)
137 * the transport itself does not need to be aware of whether or not tags
138 * were included in the transfer.
139 *
140 * @return true if the last fetch call implicitly included tag objects;
141 * false if tags were not implicitly obtained.
142 */
143 boolean didFetchIncludeTags();
144
145 /**
146 * Did the last {@link #fetch(ProgressMonitor, Collection, Set)} validate
147 * graph?
148 * <p>
149 * Some transports walk the object graph on the client side, with the client
150 * looking for what objects it is missing and requesting them individually
151 * from the remote peer. By virtue of completing the fetch call the client
152 * implicitly tested the object connectivity, as every object in the graph
153 * was either already local or was requested successfully from the peer. In
154 * such transports this method returns true.
155 * <p>
156 * Some transports assume the remote peer knows the Git object graph and is
157 * able to supply a fully connected graph to the client (although it may
158 * only be transferring the parts the client does not yet have). Its faster
159 * to assume such remote peers are well behaved and send the correct
160 * response to the client. In such transports this method returns false.
161 *
162 * @return true if the last fetch had to perform a connectivity check on the
163 * client side in order to succeed; false if the last fetch assumed
164 * the remote peer supplied a complete graph.
165 */
166 boolean didFetchTestConnectivity();
167
168 /**
169 * Set the lock message used when holding a pack out of garbage collection.
170 * <p>
171 * Callers that set a lock message <b>must</b> ensure they call
172 * {@link #getPackLocks()} after
173 * {@link #fetch(ProgressMonitor, Collection, Set)}, even if an exception
174 * was thrown, and release the locks that are held.
175 *
176 * @param message message to use when holding a pack in place.
177 */
178 void setPackLockMessage(String message);
179
180 /**
181 * All locks created by the last
182 * {@link #fetch(ProgressMonitor, Collection, Set)} call.
183 *
184 * @return collection (possibly empty) of locks created by the last call to
185 * fetch. The caller must release these after refs are updated in
186 * order to safely permit garbage collection.
187 */
188 Collection<PackLock> getPackLocks();
189 }