org.eclipse.jgit.transport
Class Transport

java.lang.Object
  org.eclipse.jgit.transport.Transport

Direct Known Subclasses:

HttpTransport, TcpTransport, TransportBundleStream

public abstract class Transport
extends Object

Connects two Git repositories together and copies objects between them.

A transport can be used for either fetching (copying objects into the caller's repository from the remote repository) or pushing (copying objects into the remote repository from the caller's repository). Each transport implementation is responsible for the details associated with establishing the network connection(s) necessary for the copy, as well as actually shuffling data back and forth.

Transport instances and the connections they create are not thread-safe. Callers must ensure a transport is accessed by only one thread at a time.

Nested Class Summary

static class

Transport.Operation Type of operation a Transport is being opened for.

Field Summary

static boolean	DEFAULT_FETCH_THIN Default setting for fetchThin option.
static boolean	DEFAULT_PUSH_THIN Default setting for pushThin option.
protected Repository	local The repository this transport fetches into, or pushes out of.
static RefSpec	REFSPEC_PUSH_ALL Specification for push operation, to push all refs under refs/heads.
static RefSpec	REFSPEC_TAGS Specification for fetch or push operations, to fetch or push all tags.
protected URIish	uri The URI used to create this transport.

Constructor Summary

protected

Transport(Repository local, URIish uri) Create a new transport instance.

Method Summary

void	applyConfig(RemoteConfig cfg) Apply provided remote configuration on this transport.
abstract void	close() Close any resources used by this transport.
FetchResult	fetch(ProgressMonitor monitor, Collection<RefSpec> toFetch) Fetch objects and refs from the remote repository to the local one.
Collection<RemoteRefUpdate>	findRemoteRefUpdatesFor(Collection<RefSpec> specs) Convert push remote refs update specification from RefSpec form to RemoteRefUpdate.
static Collection<RemoteRefUpdate>	findRemoteRefUpdatesFor(Repository db, Collection<RefSpec> specs, Collection<RefSpec> fetchSpecs) Convert push remote refs update specification from RefSpec form to RemoteRefUpdate.
CredentialsProvider	getCredentialsProvider() The configured credentials provider.
String	getOptionReceivePack() Default setting is: RemoteConfig.DEFAULT_RECEIVE_PACK
String	getOptionUploadPack() Get the name of the remote executable providing upload-pack service.
PackConfig	getPackConfig() Get the configuration used by the pack generator to make packs.
TagOpt	getTagOpt() Get the description of how annotated tags should be treated during fetch.
int	getTimeout()
static List<TransportProtocol>	getTransportProtocols() Obtain a copy of the registered protocols.
URIish	getURI() Get the URI this transport connects to.
boolean	isCheckFetchedObjects()
boolean	isDryRun()
boolean	isFetchThin() Default setting is: DEFAULT_FETCH_THIN
boolean	isPushThin() Default setting is: false
boolean	isRemoveDeletedRefs()
static Transport	open(Repository local, RemoteConfig cfg) Open a new transport instance to connect two repositories.
static Transport	open(Repository local, RemoteConfig cfg, Transport.Operation op) Open a new transport instance to connect two repositories.
static Transport	open(Repository local, String remote) Open a new transport instance to connect two repositories.
static Transport	open(Repository local, String remote, Transport.Operation op) Open a new transport instance to connect two repositories.
static Transport	open(Repository local, URIish uri) Open a new transport instance to connect two repositories.
static Transport	open(Repository local, URIish uri, String remoteName) Open a new transport instance to connect two repositories.
static List<Transport>	openAll(Repository local, RemoteConfig cfg) Open new transport instances to connect two repositories.
static List<Transport>	openAll(Repository local, RemoteConfig cfg, Transport.Operation op) Open new transport instances to connect two repositories.
static List<Transport>	openAll(Repository local, String remote) Open new transport instances to connect two repositories.
static List<Transport>	openAll(Repository local, String remote, Transport.Operation op) Open new transport instances to connect two repositories.
abstract FetchConnection	openFetch() Begins a new connection for fetching from the remote repository.
abstract PushConnection	openPush() Begins a new connection for pushing into the remote repository.
PushResult	push(ProgressMonitor monitor, Collection<RemoteRefUpdate> toPush) Push objects and refs from the local repository to the remote one.
static void	register(TransportProtocol proto) Register a TransportProtocol instance for use during open.
void	setCheckFetchedObjects(boolean check)
void	setCredentialsProvider(CredentialsProvider credentialsProvider) A credentials provider to assist with authentication connections..
void	setDryRun(boolean dryRun) Set dry run option for push operation.
void	setFetchThin(boolean fetchThin) Set the thin-pack preference for fetch operation.
void	setOptionReceivePack(String optionReceivePack) Set remote executable providing receive-pack service for pack transports.
void	setOptionUploadPack(String where) Set the name of the remote executable providing upload-pack services.
void	setPackConfig(PackConfig pc) Set the configuration used by the pack generator.
void	setPushThin(boolean pushThin) Set thin-pack preference for push operation.
void	setRemoveDeletedRefs(boolean remove) Set whether or not to remove refs which no longer exist in the source.
void	setTagOpt(TagOpt option) Set the description of how annotated tags should be treated on fetch.
void	setTimeout(int seconds) Set the timeout before willing to abort an IO call.
static void	unregister(TransportProtocol proto) Unregister a TransportProtocol instance.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FETCH_THIN

public static final boolean DEFAULT_FETCH_THIN

Default setting for fetchThin option.

See Also:

Constant Field Values

DEFAULT_PUSH_THIN

public static final boolean DEFAULT_PUSH_THIN

Default setting for pushThin option.

See Also:

Constant Field Values

REFSPEC_TAGS

public static final RefSpec REFSPEC_TAGS

Specification for fetch or push operations, to fetch or push all tags. Acts as --tags.

REFSPEC_PUSH_ALL

public static final RefSpec REFSPEC_PUSH_ALL

Specification for push operation, to push all refs under refs/heads. Acts as --all.

local

protected final Repository local

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

uri

protected final URIish uri

The URI used to create this transport.

Constructor Detail

Transport

protected Transport(Repository local,
                    URIish uri)

Create a new transport instance.

Parameters:

local - the repository this instance will fetch into, or push out of. This must be the repository passed to open(Repository, URIish).

uri - the URI used to access the remote repository. This must be the URI passed to open(Repository, URIish).

Method Detail

register

public static void register(TransportProtocol proto)

Register a TransportProtocol instance for use during open.

Protocol definitions are held by WeakReference, allowing them to be garbage collected when the calling application drops all strongly held references to the TransportProtocol. Therefore applications should use a singleton pattern as described in TransportProtocol's class documentation to ensure their protocol does not get disabled by garbage collection earlier than expected.

The new protocol is registered in front of all earlier protocols, giving it higher priority than the built-in protocol definitions.

Parameters:

proto - the protocol definition. Must not be null.

unregister

public static void unregister(TransportProtocol proto)

Unregister a TransportProtocol instance.

Unregistering a protocol usually isn't necessary, as protocols are held by weak references and will automatically clear when they are garbage collected by the JVM. Matching is handled by reference equality, so the exact reference given to register(TransportProtocol) must be used.

Parameters:

proto - the exact object previously given to register.

getTransportProtocols

public static List<TransportProtocol> getTransportProtocols()

Obtain a copy of the registered protocols.

Returns:

an immutable copy of the currently registered protocols.

open

public static Transport open(Repository local,
                             String remote)
                      throws NotSupportedException,
                             URISyntaxException,
                             TransportException

Open a new transport instance to connect two repositories.

This method assumes Transport.Operation.FETCH.

Parameters:

local - existing local repository.

remote - location of the remote repository - may be URI or remote configuration name.

Returns:

the new transport instance. Never null. In case of multiple URIs in remote configuration, only the first is chosen.

Throws:

URISyntaxException - the location is not a remote defined in the configuration file and is not a well-formed URL.

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

open

public static Transport open(Repository local,
                             String remote,
                             Transport.Operation op)
                      throws NotSupportedException,
                             URISyntaxException,
                             TransportException

Open a new transport instance to connect two repositories.

Parameters:

local - existing local repository.

remote - location of the remote repository - may be URI or remote configuration name.

op - planned use of the returned Transport; the URI may differ based on the type of connection desired.

Returns:

the new transport instance. Never null. In case of multiple URIs in remote configuration, only the first is chosen.

Throws:

URISyntaxException - the location is not a remote defined in the configuration file and is not a well-formed URL.

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

openAll

public static List<Transport> openAll(Repository local,
                                      String remote)
                               throws NotSupportedException,
                                      URISyntaxException,
                                      TransportException

Open new transport instances to connect two repositories.

This method assumes Transport.Operation.FETCH.

Parameters:

local - existing local repository.

remote - location of the remote repository - may be URI or remote configuration name.

Returns:

the list of new transport instances for every URI in remote configuration.

Throws:

URISyntaxException - the location is not a remote defined in the configuration file and is not a well-formed URL.

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

openAll

public static List<Transport> openAll(Repository local,
                                      String remote,
                                      Transport.Operation op)
                               throws NotSupportedException,
                                      URISyntaxException,
                                      TransportException

Open new transport instances to connect two repositories.

Parameters:

local - existing local repository.

remote - location of the remote repository - may be URI or remote configuration name.

op - planned use of the returned Transport; the URI may differ based on the type of connection desired.

Returns:

the list of new transport instances for every URI in remote configuration.

Throws:

URISyntaxException - the location is not a remote defined in the configuration file and is not a well-formed URL.

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

open

public static Transport open(Repository local,
                             RemoteConfig cfg)
                      throws NotSupportedException,
                             TransportException

Open a new transport instance to connect two repositories.

This method assumes Transport.Operation.FETCH.

Parameters:

local - existing local repository.

cfg - configuration describing how to connect to the remote repository.

Returns:

the new transport instance. Never null. In case of multiple URIs in remote configuration, only the first is chosen.

Throws:

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

IllegalArgumentException - if provided remote configuration doesn't have any URI associated.

open

public static Transport open(Repository local,
                             RemoteConfig cfg,
                             Transport.Operation op)
                      throws NotSupportedException,
                             TransportException

Open a new transport instance to connect two repositories.

Parameters:

local - existing local repository.

cfg - configuration describing how to connect to the remote repository.

op - planned use of the returned Transport; the URI may differ based on the type of connection desired.

Returns:

the new transport instance. Never null. In case of multiple URIs in remote configuration, only the first is chosen.

Throws:

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

IllegalArgumentException - if provided remote configuration doesn't have any URI associated.

openAll

public static List<Transport> openAll(Repository local,
                                      RemoteConfig cfg)
                               throws NotSupportedException,
                                      TransportException

Open new transport instances to connect two repositories.

This method assumes Transport.Operation.FETCH.

Parameters:

local - existing local repository.

cfg - configuration describing how to connect to the remote repository.

Returns:

the list of new transport instances for every URI in remote configuration.

Throws:

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

openAll

public static List<Transport> openAll(Repository local,
                                      RemoteConfig cfg,
                                      Transport.Operation op)
                               throws NotSupportedException,
                                      TransportException

Open new transport instances to connect two repositories.

Parameters:

local - existing local repository.

cfg - configuration describing how to connect to the remote repository.

op - planned use of the returned Transport; the URI may differ based on the type of connection desired.

Returns:

the list of new transport instances for every URI in remote configuration.

Throws:

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

open

public static Transport open(Repository local,
                             URIish uri)
                      throws NotSupportedException,
                             TransportException

Open a new transport instance to connect two repositories.

Parameters:

local - existing local repository.

uri - location of the remote repository.

Returns:

the new transport instance. Never null.

Throws:

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

open

public static Transport open(Repository local,
                             URIish uri,
                             String remoteName)
                      throws NotSupportedException,
                             TransportException

Open a new transport instance to connect two repositories.

Parameters:

local - existing local repository.

uri - location of the remote repository.

remoteName - name of the remote, if the remote as configured in local; otherwise null.

Returns:

the new transport instance. Never null.

Throws:

NotSupportedException - the protocol specified is not supported.

TransportException - the transport cannot open this URI.

findRemoteRefUpdatesFor

public static Collection<RemoteRefUpdate> findRemoteRefUpdatesFor(Repository db,
                                                                  Collection<RefSpec> specs,
                                                                  Collection<RefSpec> fetchSpecs)
                                                           throws IOException

Convert push remote refs update specification from RefSpec form to RemoteRefUpdate. Conversion expands wildcards by matching source part to local refs. expectedOldObjectId in RemoteRefUpdate is always set as null. Tracking branch is configured if RefSpec destination matches source of any fetch ref spec for this transport remote configuration.

Parameters:

db - local database.

specs - collection of RefSpec to convert.

fetchSpecs - fetch specifications used for finding localtracking refs. May be null or empty collection.

Returns:

collection of set up RemoteRefUpdate.

Throws:

IOException - when problem occurred during conversion or specification set up: most probably, missing objects or refs.

getURI

public URIish getURI()

Get the URI this transport connects to.

Each transport instance connects to at most one URI at any point in time.

Returns:

the URI describing the location of the remote repository.

getOptionUploadPack

public String getOptionUploadPack()

Get the name of the remote executable providing upload-pack service.

Returns:

typically "git-upload-pack".

setOptionUploadPack

public void setOptionUploadPack(String where)

Set the name of the remote executable providing upload-pack services.

Parameters:

where - name of the executable.

getTagOpt

public TagOpt getTagOpt()

Get the description of how annotated tags should be treated during fetch.

Returns:

option indicating the behavior of annotated tags in fetch.

setTagOpt

public void setTagOpt(TagOpt option)

Set the description of how annotated tags should be treated on fetch.

Parameters:

option - method to use when handling annotated tags.

isFetchThin

public boolean isFetchThin()

Default setting is: DEFAULT_FETCH_THIN

Returns:

true if fetch should request thin-pack when possible; false otherwise

See Also:

PackTransport

setFetchThin

public void setFetchThin(boolean fetchThin)

Set the thin-pack preference for fetch operation. Default setting is: DEFAULT_FETCH_THIN

Parameters:

fetchThin - true when fetch should request thin-pack when possible; false when it shouldn't

See Also:

PackTransport

isCheckFetchedObjects

public boolean isCheckFetchedObjects()

Returns:

true if fetch will verify received objects are formatted correctly. Validating objects requires more CPU time on the client side of the connection.

setCheckFetchedObjects

public void setCheckFetchedObjects(boolean check)

Parameters:

check - true to enable checking received objects; false to assume all received objects are valid.

getOptionReceivePack

public String getOptionReceivePack()

Default setting is: RemoteConfig.DEFAULT_RECEIVE_PACK

Returns:

remote executable providing receive-pack service for pack transports.

See Also:

PackTransport

setOptionReceivePack

public void setOptionReceivePack(String optionReceivePack)

Set remote executable providing receive-pack service for pack transports. Default setting is: RemoteConfig.DEFAULT_RECEIVE_PACK

Parameters:

optionReceivePack - remote executable, if null or empty default one is set;

isPushThin

public boolean isPushThin()

Default setting is: false

Returns:

true if push should produce thin-pack in pack transports

See Also:

PackTransport

setPushThin

public void setPushThin(boolean pushThin)

Set thin-pack preference for push operation. Default setting is: false

Parameters:

pushThin - true when push should produce thin-pack in pack transports; false when it shouldn't

See Also:

PackTransport

isRemoveDeletedRefs

public boolean isRemoveDeletedRefs()

Returns:

true if destination refs should be removed if they no longer exist at the source repository.

setRemoveDeletedRefs

public void setRemoveDeletedRefs(boolean remove)

Set whether or not to remove refs which no longer exist in the source.

If true, refs at the destination repository (local for fetch, remote for push) are deleted if they no longer exist on the source side (remote for fetch, local for push).

False by default, as this may cause data to become unreachable, and eventually be deleted on the next GC.

Parameters:

remove - true to remove refs that no longer exist.

applyConfig

public void applyConfig(RemoteConfig cfg)

Apply provided remote configuration on this transport.

Parameters:

cfg - configuration to apply on this transport.

isDryRun

public boolean isDryRun()

Returns:

true if push operation should just check for possible result and not really update remote refs, false otherwise - when push should act normally.

setDryRun

public void setDryRun(boolean dryRun)

Set dry run option for push operation.

Parameters:

dryRun - true if push operation should just check for possible result and not really update remote refs, false otherwise - when push should act normally.

getTimeout

public int getTimeout()

Returns:

timeout (in seconds) before aborting an IO operation.

setTimeout

public void setTimeout(int seconds)

Set the timeout before willing to abort an IO call.

Parameters:

seconds - number of seconds to wait (with no data transfer occurring) before aborting an IO read or write operation with this remote.

getPackConfig

public PackConfig getPackConfig()

Get the configuration used by the pack generator to make packs. If setPackConfig(PackConfig) was previously given null a new PackConfig is created on demand by this method using the source repository's settings.

Returns:

the pack configuration. Never null.

setPackConfig

public void setPackConfig(PackConfig pc)

Set the configuration used by the pack generator.

Parameters:

pc - configuration controlling packing parameters. If null the source repository's settings will be used.

setCredentialsProvider

public void setCredentialsProvider(CredentialsProvider credentialsProvider)

A credentials provider to assist with authentication connections..

Parameters:

credentialsProvider - the credentials provider, or null if there is none

getCredentialsProvider

public CredentialsProvider getCredentialsProvider()

The configured credentials provider.

Returns:

the credentials provider, or null if no credentials provider is associated with this transport.

fetch

public FetchResult fetch(ProgressMonitor monitor,
                         Collection<RefSpec> toFetch)
                  throws NotSupportedException,
                         TransportException

Fetch objects and refs from the remote repository to the local one.

This is a utility function providing standard fetch behavior. Local tracking refs associated with the remote repository are automatically updated if this transport was created from a RemoteConfig with fetch RefSpecs defined.

Parameters:

monitor - progress monitor to inform the user about our processing activity. Must not be null. Use NullProgressMonitor if progress updates are not interesting or necessary.

toFetch - specification of refs to fetch locally. May be null or the empty collection to use the specifications from the RemoteConfig. Source for each RefSpec can't be null.

Returns:

information describing the tracking refs updated.

Throws:

NotSupportedException - this transport implementation does not support fetching objects.

TransportException - the remote connection could not be established or object copying (if necessary) failed or update specification was incorrect.

push

public PushResult push(ProgressMonitor monitor,
                       Collection<RemoteRefUpdate> toPush)
                throws NotSupportedException,
                       TransportException

Push objects and refs from the local repository to the remote one.

This is a utility function providing standard push behavior. It updates remote refs and send there necessary objects according to remote ref update specification. After successful remote ref update, associated locally stored tracking branch is updated if set up accordingly. Detailed operation result is provided after execution.

For setting up remote ref update specification from ref spec, see helper method findRemoteRefUpdatesFor(Collection), predefined refspecs (REFSPEC_TAGS, REFSPEC_PUSH_ALL) or consider using directly RemoteRefUpdate for more possibilities.

When isDryRun() is true, result of this operation is just estimation of real operation result, no real action is performed.

Parameters:

monitor - progress monitor to inform the user about our processing activity. Must not be null. Use NullProgressMonitor if progress updates are not interesting or necessary.

toPush - specification of refs to push. May be null or the empty collection to use the specifications from the RemoteConfig converted by findRemoteRefUpdatesFor(Collection). No more than 1 RemoteRefUpdate with the same remoteName is allowed. These objects are modified during this call.

Returns:

information about results of remote refs updates, tracking refs updates and refs advertised by remote repository.

Throws:

NotSupportedException - this transport implementation does not support pushing objects.

TransportException - the remote connection could not be established or object copying (if necessary) failed at I/O or protocol level or update specification was incorrect.

See Also:

RemoteRefUpdate

findRemoteRefUpdatesFor

public Collection<RemoteRefUpdate> findRemoteRefUpdatesFor(Collection<RefSpec> specs)
                                                    throws IOException

Convert push remote refs update specification from RefSpec form to RemoteRefUpdate. Conversion expands wildcards by matching source part to local refs. expectedOldObjectId in RemoteRefUpdate is always set as null. Tracking branch is configured if RefSpec destination matches source of any fetch ref spec for this transport remote configuration.

Conversion is performed for context of this transport (database, fetch specifications).

Parameters:

specs - collection of RefSpec to convert.

Returns:

collection of set up RemoteRefUpdate.

Throws:

IOException - when problem occurred during conversion or specification set up: most probably, missing objects or refs.

openFetch

public abstract FetchConnection openFetch()
                                   throws NotSupportedException,
                                          TransportException

Begins a new connection for fetching from the remote repository.

Returns:

a fresh connection to fetch from the remote repository.

Throws:

NotSupportedException - the implementation does not support fetching.

TransportException - the remote connection could not be established.

openPush

public abstract PushConnection openPush()
                                 throws NotSupportedException,
                                        TransportException

Begins a new connection for pushing into the remote repository.

Returns:

a fresh connection to push into the remote repository.

Throws:

NotSupportedException - the implementation does not support pushing.

TransportException - the remote connection could not be established

close

public abstract void close()

Close any resources used by this transport.

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.