org.eclipse.jgit.transport

## Class BasePackFetchConnection

- java.lang.Object
- - org.eclipse.jgit.transport.BaseConnection
  - - org.eclipse.jgit.transport.BasePackFetchConnection

All Implemented Interfaces:
  Connection, FetchConnection

    public abstract class BasePackFetchConnection
    extends BaseConnection
    implements FetchConnection

Fetch implementation using the native Git pack transfer service.

This is the canonical implementation for transferring objects from the remote repository to the local repository by talking to the 'git-upload-pack' service. Objects are packed on the remote side into a pack file and then sent down the pipe to us.

This connection requires only a bi-directional pipe or socket, and thus is easily wrapped up into a local process pipe, anonymous TCP socket, or a command executed through an SSH tunnel.

If `BasePackConnection.statelessRPC` is `true`, this connection can be tunneled over a request-response style RPC system like HTTP. The RPC call boundary is determined by this class switching from writing to the OutputStream to reading from the InputStream.

Concrete implementations should just call `init(java.io.InputStream, java.io.OutputStream)` and `readAdvertisedRefs()` methods in constructor or before any use. They should also handle resources releasing in `close()` method if needed.

### Field Summary

Fields
`protected Set<ObjectId>` `additionalHaves` Extra objects the remote has, but which aren't offered as refs.
`protected InputStream` `in` Input stream reading from the remote.
`protected Repository` `local` The repository this transport fetches into, or pushes out of.
`protected static int` `MIN_CLIENT_BUFFER` Amount of data the client sends before starting to read.
`static String` `OPTION_ALLOW_TIP_SHA1_IN_WANT` The client supports fetching objects at the tip of any ref, even if not advertised.
`static String` `OPTION_INCLUDE_TAG` Include tags if we are also including the referenced objects.
`static String` `OPTION_MULTI_ACK` Mutli-ACK support for improved negotiation.
`static String` `OPTION_MULTI_ACK_DETAILED` Mutli-ACK detailed support for improved negotiation.
`static String` `OPTION_NO_DONE` The client supports receiving a pack before it has sent "done".
`static String` `OPTION_NO_PROGRESS` The client does not want progress messages and will ignore them.
`static String` `OPTION_OFS_DELTA` The client supports packs with OFS deltas.
`static String` `OPTION_SHALLOW` The client supports shallow fetches.
`static String` `OPTION_SIDE_BAND` The client supports using the side-band for progress messages.
`static String` `OPTION_SIDE_BAND_64K` The client supports using the 64K side-band for progress messages.
`static String` `OPTION_THIN_PACK` The client supports packs with deltas but not their bases.
`protected OutputStream` `out` Output stream sending to the remote.
`protected boolean` `outNeedsEnd` Send `PacketLineOut.end()` before closing `out`?
`protected PacketLineIn` `pckIn` Packet line decoder around `in`.
`protected PacketLineOut` `pckOut` Packet line encoder around `out`.
`protected boolean` `statelessRPC` True if this is a stateless RPC connection.
`protected TimeoutInputStream` `timeoutIn` Low-level input stream, if a timeout was configured.
`protected TimeoutOutputStream` `timeoutOut` Low-level output stream, if a timeout was configured.
`protected Transport` `transport` A transport connected to `uri`.
`protected URIish` `uri` Remote repository location.

### Constructor Summary

Constructors
Constructor and Description
`BasePackFetchConnection(PackTransport packTransport)` Create a new connection to fetch using the native git transport.

### Method Summary

Methods
`void` `close()` Close any resources used by this connection.
`boolean` `didFetchIncludeTags()` Did the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` get tags?
`boolean` `didFetchTestConnectivity()` Did the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` validate graph?
`protected void` `doFetch(ProgressMonitor monitor, Collection<Ref> want, Set<ObjectId> have, OutputStream outputStream)` Execute common ancestor negotiation and fetch the objects.
`protected void` `endOut()` Tell the peer we are disconnecting, if it cares to know.
`void` `fetch(ProgressMonitor monitor, Collection<Ref> want, Set<ObjectId> have)` Fetch objects we don't have but that are reachable from advertised refs.
`void` `fetch(ProgressMonitor monitor, Collection<Ref> want, Set<ObjectId> have, OutputStream outputStream)` Fetch objects we don't have but that are reachable from advertised refs.
`Collection<PackLock>` `getPackLocks()` All locks created by the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` call.
`protected void` `init(InputStream myIn, OutputStream myOut)` Configure this connection with the directional pipes.
`protected boolean` `isCapableOf(String option)`
`protected TransportException` `noRepository()` Create an exception to indicate problems finding a remote repository.
`protected void` `onReceivePack()` Notification event delivered just before the pack is received from the network.
`protected void` `readAdvertisedRefs()` Reads the advertised references through the initialized stream.
`void` `setPackLockMessage(String message)` Set the lock message used when holding a pack out of garbage collection.
`protected boolean` `wantCapability(StringBuilder b, String option)`

### Methods inherited from class org.eclipse.jgit.transport.BaseConnection

`available, getMessages, getMessageWriter, getRef, getRefs, getRefsMap, markStartedOperation, setMessageWriter`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.eclipse.jgit.transport.Connection

`getMessages, getRef, getRefs, getRefsMap`

### Field Detail

#### MIN_CLIENT_BUFFER

    protected static final int MIN_CLIENT_BUFFER

Amount of data the client sends before starting to read.

Any output stream given to the client must be able to buffer this many bytes before the client will stop writing and start reading from the input stream. If the output stream blocks before this many bytes are in the send queue, the system will deadlock.

See Also:
  Constant Field Values

#### OPTION_INCLUDE_TAG

    public static final String OPTION_INCLUDE_TAG

Include tags if we are also including the referenced objects.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_MULTI_ACK

    public static final String OPTION_MULTI_ACK

Mutli-ACK support for improved negotiation.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_MULTI_ACK_DETAILED

    public static final String OPTION_MULTI_ACK_DETAILED

Mutli-ACK detailed support for improved negotiation.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_THIN_PACK

    public static final String OPTION_THIN_PACK

The client supports packs with deltas but not their bases.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_SIDE_BAND

    public static final String OPTION_SIDE_BAND

The client supports using the side-band for progress messages.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_SIDE_BAND_64K

    public static final String OPTION_SIDE_BAND_64K

The client supports using the 64K side-band for progress messages.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_OFS_DELTA

    public static final String OPTION_OFS_DELTA

The client supports packs with OFS deltas.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_SHALLOW

    public static final String OPTION_SHALLOW

The client supports shallow fetches.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_NO_PROGRESS

    public static final String OPTION_NO_PROGRESS

The client does not want progress messages and will ignore them.

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_NO_DONE

    public static final String OPTION_NO_DONE

The client supports receiving a pack before it has sent "done".

Since:
  2.0
See Also:
  Constant Field Values

#### OPTION_ALLOW_TIP_SHA1_IN_WANT

    public static final String OPTION_ALLOW_TIP_SHA1_IN_WANT

The client supports fetching objects at the tip of any ref, even if not advertised.

Since:
  3.1
See Also:
  Constant Field Values

#### local

    protected final Repository local

The repository this transport fetches into, or pushes out of.

#### uri

    protected final URIish uri

Remote repository location.

#### transport

    protected final Transport transport

A transport connected to `uri`.

#### timeoutIn

    protected TimeoutInputStream timeoutIn

Low-level input stream, if a timeout was configured.

#### timeoutOut

    protected TimeoutOutputStream timeoutOut

Low-level output stream, if a timeout was configured.

#### in

    protected InputStream in

Input stream reading from the remote.

#### out

    protected OutputStream out

Output stream sending to the remote.

#### pckIn

    protected PacketLineIn pckIn

Packet line decoder around `in`.

#### pckOut

    protected PacketLineOut pckOut

Packet line encoder around `out`.

#### outNeedsEnd

    protected boolean outNeedsEnd

Send `PacketLineOut.end()` before closing `out`?

#### statelessRPC

    protected boolean statelessRPC

True if this is a stateless RPC connection.

#### additionalHaves

    protected final Set<ObjectId> additionalHaves

Extra objects the remote has, but which aren't offered as refs.

### Constructor Detail

#### BasePackFetchConnection

    public BasePackFetchConnection(PackTransport packTransport)

Create a new connection to fetch using the native git transport.

Parameters:
  `packTransport` - the transport.

### Method Detail

#### fetch

    public final void fetch(ProgressMonitor monitor,
             Collection<Ref> want,
             Set<ObjectId> have)
                     throws TransportException

Description copied from interface: `FetchConnection`
Fetch objects we don't have but that are reachable from advertised refs.

Only one call per connection is allowed. Subsequent calls will result in `TransportException`.

Implementations are free to use network connections as necessary to efficiently (for both client and server) transfer objects from the remote repository into this repository. When possible implementations should avoid replacing/overwriting/duplicating an object already available in the local destination repository. Locally available objects and packs should always be preferred over remotely available objects and packs. `Transport.isFetchThin()` should be honored if applicable.

Specified by:
  `fetch` in interface `FetchConnection`
Parameters:
  `monitor` - progress monitor to inform the end-user about the amount of work completed, or to indicate cancellation. Implementations should poll the monitor at regular intervals to look for cancellation requests from the user.
  `want` - one or more refs advertised by this connection that the caller wants to store locally.
  `have` - additional objects known to exist in the destination repository, especially if they aren't yet reachable by the ref database. Connections should take this set as an addition to what is reachable through all Refs, not in replace of it.
Throws:
  `TransportException` - objects could not be copied due to a network failure, protocol error, or error on remote side, or connection was already used for fetch.

#### fetch

    public final void fetch(ProgressMonitor monitor,
             Collection<Ref> want,
             Set<ObjectId> have,
             OutputStream outputStream)
                     throws TransportException

Description copied from interface: `FetchConnection`
Fetch objects we don't have but that are reachable from advertised refs.

Only one call per connection is allowed. Subsequent calls will result in `TransportException`.

Implementations are free to use network connections as necessary to efficiently (for both client and server) transfer objects from the remote repository into this repository. When possible implementations should avoid replacing/overwriting/duplicating an object already available in the local destination repository. Locally available objects and packs should always be preferred over remotely available objects and packs. `Transport.isFetchThin()` should be honored if applicable.

Specified by:
  `fetch` in interface `FetchConnection`
Parameters:
  `monitor` - progress monitor to inform the end-user about the amount of work completed, or to indicate cancellation. Implementations should poll the monitor at regular intervals to look for cancellation requests from the user.
  `want` - one or more refs advertised by this connection that the caller wants to store locally.
  `have` - additional objects known to exist in the destination repository, especially if they aren't yet reachable by the ref database. Connections should take this set as an addition to what is reachable through all Refs, not in replace of it.
  `outputStream` - OutputStream to write sideband messages to
Throws:
  `TransportException` - objects could not be copied due to a network failure, protocol error, or error on remote side, or connection was already used for fetch.
Since:
  3.0

#### didFetchIncludeTags

    public boolean didFetchIncludeTags()

Description copied from interface: `FetchConnection`
Did the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` get tags?

Some Git aware transports are able to implicitly grab an annotated tag if `TagOpt.AUTO_FOLLOW` or `TagOpt.FETCH_TAGS` was selected and the object the tag peels to (references) was transferred as part of the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` call. If it is possible for such tags to have been included in the transfer this method returns true, allowing the caller to attempt tag discovery.

By returning only true/false (and not the actual list of tags obtained) the transport itself does not need to be aware of whether or not tags were included in the transfer.

Specified by:
  `didFetchIncludeTags` in interface `FetchConnection`
Returns:
  true if the last fetch call implicitly included tag objects; false if tags were not implicitly obtained.

#### didFetchTestConnectivity

    public boolean didFetchTestConnectivity()

Description copied from interface: `FetchConnection`
Did the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` validate graph?

Some transports walk the object graph on the client side, with the client looking for what objects it is missing and requesting them individually from the remote peer. By virtue of completing the fetch call the client implicitly tested the object connectivity, as every object in the graph was either already local or was requested successfully from the peer. In such transports this method returns true.

Some transports assume the remote peer knows the Git object graph and is able to supply a fully connected graph to the client (although it may only be transferring the parts the client does not yet have). Its faster to assume such remote peers are well behaved and send the correct response to the client. In such transports this method returns false.

Specified by:
  `didFetchTestConnectivity` in interface `FetchConnection`
Returns:
  true if the last fetch had to perform a connectivity check on the client side in order to succeed; false if the last fetch assumed the remote peer supplied a complete graph.

#### setPackLockMessage

    public void setPackLockMessage(String message)

Description copied from interface: `FetchConnection`
Set the lock message used when holding a pack out of garbage collection.

Callers that set a lock message must ensure they call `FetchConnection.getPackLocks()` after `FetchConnection.fetch(ProgressMonitor, Collection, Set)`, even if an exception was thrown, and release the locks that are held.

Specified by:
  `setPackLockMessage` in interface `FetchConnection`
Parameters:
  `message` - message to use when holding a pack in place.

#### getPackLocks

    public Collection<PackLock> getPackLocks()

Description copied from interface: `FetchConnection`
All locks created by the last `FetchConnection.fetch(ProgressMonitor, Collection, Set)` call.

Specified by:
  `getPackLocks` in interface `FetchConnection`
Returns:
  collection (possibly empty) of locks created by the last call to fetch. The caller must release these after refs are updated in order to safely permit garbage collection.

#### doFetch

    protected void doFetch(ProgressMonitor monitor,
               Collection<Ref> want,
               Set<ObjectId> have,
               OutputStream outputStream)
                    throws TransportException

Execute common ancestor negotiation and fetch the objects.

Parameters:
  `monitor` - progress monitor to receive status updates. If the monitor is the `NullProgressMonitor.INSTANCE`, then the no-progress option enabled.
  `want` - the advertised remote references the caller wants to fetch.
  `have` - additional objects to assume that already exist locally. This will be added to the set of objects reachable from the destination repository's references.
  `outputStream` - ouputStream to write sideband messages to
Throws:
  `TransportException` - if any exception occurs.
Since:
  3.0

#### close

    public void close()

Description copied from interface: `Connection`
Close any resources used by this connection.

If the remote repository is contacted by a network socket this method must close that network socket, disconnecting the two peers. If the remote repository is actually local (same system) this method must close any open file handles used to read the "remote" repository.

If additional messages were produced by the remote peer, these should still be retained in the connection instance for `Connection.getMessages()`.

Specified by:
  `close` in interface `Connection`

#### onReceivePack

    protected void onReceivePack()

Notification event delivered just before the pack is received from the network. This event can be used by RPC such as `TransportHttp` to disable its request magic and ensure the pack stream is read correctly.

Since:
  2.0

#### init

    protected final void init(InputStream myIn,
            OutputStream myOut)

Configure this connection with the directional pipes.

Parameters:
  `myIn` - input stream to receive data from the peer. Caller must ensure the input is buffered, otherwise read performance may suffer.
  `myOut` - output stream to transmit data to the peer. Caller must ensure the output is buffered, otherwise write performance may suffer.

#### readAdvertisedRefs

    protected void readAdvertisedRefs()
                               throws TransportException

Reads the advertised references through the initialized stream.

Subclass implementations may call this method only after setting up the input and output streams with `init(InputStream, OutputStream)`.

If any errors occur, this connection is automatically closed by invoking `close()` and the exception is wrapped (if necessary) and thrown as a `TransportException`.

Throws:
  `TransportException` - the reference list could not be scanned.

#### noRepository

    protected TransportException noRepository()

Create an exception to indicate problems finding a remote repository. The caller is expected to throw the returned exception. Subclasses may override this method to provide better diagnostics.

Returns:
  a TransportException saying a repository cannot be found and possibly why.

#### isCapableOf

    protected boolean isCapableOf(String option)

#### wantCapability

    protected boolean wantCapability(StringBuilder b,
                         String option)

#### endOut

    protected void endOut()

Tell the peer we are disconnecting, if it cares to know.