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