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.Collections;
  42 import java.util.Map;
  43
  44 import org.spearce.jgit.errors.TransportException;
  45 import org.spearce.jgit.lib.ProgressMonitor;
  46 import org.spearce.jgit.lib.Ref;
  47
  48 /**
  49  * Lists known refs from the remote and copies objects of selected refs.
  50  * <p>
  51  * A fetch connection typically connects to the <code>git-upload-pack</code>
  52  * service running where the remote repository is stored. This provides a
  53  * one-way object transfer service to copy objects from the remote repository
  54  * into this local repository.
  55  * <p>
  56  * Instances of a FetchConnection must be created by a {@link Transport} that
  57  * implements a specific object transfer protocol that both sides of the
  58  * connection understand.
  59  * <p>
  60  * FetchConnection instances are not thread safe and may be accessed by only one
  61  * thread at a time.
  62  *
  63  * @see Transport
  64  */
  65 public abstract class FetchConnection {
  66         private Map<String, Ref> cachedRefs = Collections.<String, Ref> emptyMap();
  67
  68         /** Have we started {@link #fetch(ProgressMonitor, Collection)} yet? */
  69         private boolean startedFetch;
  70
  71         Map<String, Ref> getCachedRefs() {
  72                 return cachedRefs;
  73         }
  74
  75         /**
  76          * Denote the list of refs available on the remote repository.
  77          * <p>
  78          * Implementors should invoke this method once they have obtained the refs
  79          * that are available from the remote repository.s
  80          *
  81          * @param all
  82          *            the complete list of refs the remote has to offer. This map
  83          *            will be wrapped in an unmodifiable way to protect it, but it
  84          *            does not get copied.
  85          */
  86         protected void available(final Map<String, Ref> all) {
  87                 cachedRefs = Collections.unmodifiableMap(all);
  88         }
  89
  90         /**
  91          * Get the complete list of refs advertised as available for fetching.
  92          * <p>
  93          * The returned refs may appear in any order. If the caller needs these to
  94          * be sorted, they should be copied into a new array or List and then sorted
  95          * by the caller as necessary.
  96          *
  97          * @return available/advertised refs. Never null. Not modifiable. The
  98          *         collection can be empty if the remote side has no refs (it is an
  99          *         empty/newly created repository).
 100          */
 101         public final Collection<Ref> getRefs() {
 102                 return cachedRefs.values();
 103         }
 104
 105         /**
 106          * Get a single advertised ref by name.
 107          * <p>
 108          * The name supplied should be valid ref name. To get a peeled value for a
 109          * ref (aka <code>refs/tags/v1.0^{}</code>) use the base name (without
 110          * the <code>^{}</code> suffix) and look at the peeled object id.
 111          *
 112          * @param name
 113          *            name of the ref to obtain.
 114          * @return the requested ref; null if the remote did not advertise this ref.
 115          */
 116         public final Ref getRef(final String name) {
 117                 return cachedRefs.get(name);
 118         }
 119
 120         /**
 121          * Fetch objects we don't have but that are reachable from advertised refs.
 122          *
 123          * @param monitor
 124          *            progress monitor to update the end-user about the amount of
 125          *            work completed, or to indicate cancellation.
 126          * @param want
 127          *            one or more refs advertised by this connection that the caller
 128          *            wants to store locally.
 129          * @throws TransportException
 130          *             objects could not be copied due to a network failure,
 131          *             protocol error, or error on remote side.
 132          */
 133         public final void fetch(final ProgressMonitor monitor,
 134                         final Collection<Ref> want) throws TransportException {
 135                 if (startedFetch)
 136                         throw new TransportException("Only one fetch call supported.");
 137                 startedFetch = true;
 138                 doFetch(monitor, want);
 139         }
 140
 141         /**
 142          * Fetch objects this repository does not yet contain.
 143          * <p>
 144          * Implementations are free to use network connections as necessary to
 145          * efficiently (for both client and server) transfer objects from the remote
 146          * repository into this repository. When possible implementations should
 147          * avoid replacing/overwriting/duplicating an object already available in
 148          * the local destination repository. Locally available objects and packs
 149          * should always be preferred over remotely available objects and packs.
 150          *
 151          * @param monitor
 152          *            progress feedback to inform the end-user about the status of
 153          *            the object transfer. Implementors should poll the monitor at
 154          *            regular intervals to look for cancellation requests from the
 155          *            user.
 156          * @param want
 157          *            one or more refs that were previously passed to
 158          *            {@link #available(Map)} by the implementation. These refs
 159          *            indicate the objects the caller wants copied.
 160          * @throws TransportException
 161          *             objects could not be copied due to a network failure,
 162          *             protocol error, or error on remote side.
 163          */
 164         protected abstract void doFetch(ProgressMonitor monitor,
 165                         Collection<Ref> want) throws TransportException;
 166
 167         /**
 168          * Did the last {@link #fetch(ProgressMonitor, Collection)} get tags?
 169          * <p>
 170          * Some Git aware transports are able to implicitly grab an annotated tag if
 171          * {@link TagOpt#AUTO_FOLLOW} or {@link TagOpt#FETCH_TAGS} was selected and
 172          * the object the tag peels to (references) was transferred as part of the
 173          * last {@link #doFetch(ProgressMonitor, Collection)} call. If it is
 174          * possible for such tags to have been included in the transfer this method
 175          * returns true, allowing the caller to attempt tag discovery.
 176          * <p>
 177          * By returning only true/false (and not the actual list of tags obtained)
 178          * the transport itself does not need to be aware of whether or not tags
 179          * were included in the transfer.
 180          *
 181          * @return true if the last fetch call implicitly included tag objects;
 182          *         false if tags were not implicitly obtained.
 183          */
 184         public boolean didFetchIncludeTags() {
 185                 return false;
 186         }
 187
 188         /**
 189          * Close any resources used by this connection.
 190          * <p>
 191          * If the remote repository is contacted by a network socket this method
 192          * must close that network socket, disconnecting the two peers. If the
 193          * remote repository is actually local (same system) this method must close
 194          * any open file handles used to read the "remote" repository.
 195          */
 196         public abstract void close();
 197 }