com.microsoft.tfs.core
Class TFSConnection

java.lang.Object
  extended by com.microsoft.tfs.core.TFSConnection
All Implemented Interfaces:
com.microsoft.tfs.util.Closable
Direct Known Subclasses:
TFSConfigurationServer, TFSTeamProjectCollection

public abstract class TFSConnection
extends java.lang.Object
implements com.microsoft.tfs.util.Closable

A generic connection to a Team Foundation Server: subclasses will provide access to either TFS Configuration Server or a Team Project Collection.

A TFSConnection instance is ultimately created by specifying two things: a URI that identifies the URI, and a ConnectionAdvisor that supplies environmental settings (and can influence how some profile data is interpreted).

A TFSConnection provides the following services:

TFSConnection implements the Closable interface. Clients that instantiate TFSConnection instances must call close() on those instances when they are no longer needed. This allows the TFSConnection instance and all allocated client classes to perform cleanup operations (delete temporary files, close cache files, etc.). TFSConnection instances register JVM shutdown event listeners which call close(), but it's better for clients to manually invoke close() as soon as possible.

TFSConnection is thread safe. Objects obtained from a TFSConnection document their threading policy individually.

For both TFSTeamProjectCollection and TFSConfigurationServer the server URL string provided in the constructor may be either:

  1. A "base" URL, which points to where the TFS configuration server is installed or to any team project collection
  2. The full URL to the location service inside either a TFS configuration server or any project collection
A user normally provides the first type when a URI is created via UI input or command-line arguments. The second type is occasionally convenient for programmatic construction (this method is used internally). TFSConnection's constructor determines which type was provided by matching against a known location service endpoint suffix, then computes getBaseURI() and getLocationServiceURI() from the URL.

See Also:
ConnectionAdvisor
Since:
TEE-SDK-10.1
Thread-safety:
thread-safe

Nested Class Summary
protected static class TFSConnection.HTTPClientReference
           
 
Constructor Summary
protected TFSConnection(java.net.URI serverURI, java.util.concurrent.atomic.AtomicReference<Credentials> credentialsHolder, ConnectionAdvisor advisor, java.lang.String locationServiceRelativePath)
          Creates a TFSConnection.
 
Method Summary
 void addConnectivityFailureStatusChangeListener(ConnectivityFailureStatusChangeListener listener)
           
 void authenticate()
          This method actually authenticates with the server, using the specified provider to get credentials if necessary.
 void close()
           This Closable interface method must be called when this TFSConnection instance is no longer needed.
 void connect(ConnectOptions connectOptions)
          Performs all of the steps that are necessary for setting up a connection with a TeamFoundationServer.
 void ensureAuthenticated()
          This method will authenticate the connection if not previously authenticated.
 TeamFoundationIdentity getAuthenticatedIdentity()
          Returns the identity that authenticated with the server.
 java.lang.String getAuthorizedAccountName()
          Gets the authorized identity's account name, which does not include a domain name.
 java.lang.String getAuthorizedDomainName()
          Gets the authorized identity's domain name, which does not include an account name.
 TeamFoundationIdentity getAuthorizedIdentity()
          The identity who the calls to the server are being made for.
 TFSUser getAuthorizedTFSUser()
          Gets the authorized user name in the form of a TFSUser object, which includes the account name and domain.
 java.net.URI getBaseURI()
          Obtains the base Team Foundation Server URI that this TFSConnection connects to (for example, http://server.mycompany.com:8080/ for TFS 2005-2008, posibly more like http://server.mycompany.com:8080/tfs/TeamProjectCollection for TFS 2010).
 java.text.Collator getCaseInsensitiveCollator()
           Obtains a Collator for the connection's current Locale that considers character and accent differences important, but not case.
 java.text.Collator getCaseSensitiveCollator()
          Obtains a Collator for the connection's current Locale that considers all character differences important.
 CatalogNode getCatalogNode()
           
 com.microsoft.tfs.util.GUID getCatalogResourceID()
          Gets the catalog identifier from this connection's ServerDataProvider.
protected abstract  ICatalogService getCatalogService()
          Gets the ICatalogService for this connection.
 java.lang.Object getClient(java.lang.Class<?> clientType)
          Gets a client from this TFSConnection.
protected  ConnectionAdvisor getConnectionAdvisor()
           
 boolean getConnectivityFailureOnLastWebServiceCall()
           
 Credentials getCredentials()
           
 java.util.concurrent.atomic.AtomicReference<Credentials> getCredentialsHolder()
           
 HttpClient getHTTPClient()
          Gets the HttpClient instance from this TFSConnection.
protected  TFSConnection.HTTPClientReference getHTTPClientReference()
          Gets the TFSConnection.HTTPClientReference instance from this TFSConnection.
 com.microsoft.tfs.util.GUID getInstanceID()
          Gets the instance identifier from this connection's ServerDataProvider.
 ms.tfs.services.linking._03._IntegrationServiceSoap getLinkingWebService(java.lang.String endpoint)
          Obtains a new linking web service from this TFSConnection.
 java.util.Locale getLocale()
          Obtains the Locale associated with this TFSConnection.
 java.net.URI getLocationServiceURI()
           
 java.lang.String getName()
          Returns a string suitable for user display which identifies this TFS connection.
 PersistenceStoreProvider getPersistenceStoreProvider()
          Obtains the PersistenceStoreProvider that determines where cache and configuration data is stored.
abstract  RegistrationClient getRegistrationClient()
          Convenience method to get the registration client for this connection.
 ServerCapabilities getServerCapabilities()
          The capabilities of the TFS server
protected abstract  ServerDataProvider getServerDataProvider()
          Gets the ServerDataProvider for this connection.
 com.microsoft.tfs.util.GUID getSessionID()
          The session ID is a unique GUID that is created when TFSConnection is constructed.
 TFProxyServerSettings getTFProxyServerSettings()
          Gets the TF proxy server settings from this TFSConnection.
 java.util.TimeZone getTimeZone()
          Obtains the TimeZone associated with this TFSConnection.
 java.net.URL getURL()
          Deprecated. use getBaseURI() instead
 java.lang.Object getWebService(java.lang.Class<?> webServiceType)
          Obtains a new web service from this TFSConnection.
protected  WebServiceFactory getWebServiceFactory()
           
 java.net.URI getWebServiceURI(java.lang.Object webService)
          Called to obtain the URI that a web service is connected to.
 WSSClient getWSSClient(ProjectInfo projectInfo)
          Gets a Windows Sharepoint Services client.
 ms.wss._ListsSoap getWSSWebService(ProjectInfo projectInfo)
          Obtains a new sharepoint web service from this TFSConnection.
abstract  boolean hasAuthenticated()
          Tests whether the connection has authenticated.
 boolean isHosted()
           
 HttpClient newHTTPClient(java.net.URI proxyScopeURI)
          Gets a new HttpClient whose configuration (SSL restrictions, proxy settings, credentials, etc.) are similar to those in use by this TFSConnection's HttpClient.
 void removeConnectivityFailureStatusChangeListener(ConnectivityFailureStatusChangeListener listener)
           
 void setConnectivityFailureOnLastWebServiceCall(boolean failure)
           
protected  void setHTTPClientReference(TFSConnection.HTTPClientReference httpClientReference)
          Sets the TFSConnection.HTTPClientReference for this TFSConnection, and increments the use count by one.
 java.lang.String toString()
          
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TFSConnection

protected TFSConnection(java.net.URI serverURI,
                        java.util.concurrent.atomic.AtomicReference<Credentials> credentialsHolder,
                        ConnectionAdvisor advisor,
                        java.lang.String locationServiceRelativePath)
Creates a TFSConnection. Both a URI and a ConnectionAdvisor are specified.

The URI in the profile must be the fully qualified URI to the server; it should not point to a project collection.

Parameters:
serverURI - the URI to connect to (must not be null). This URI must be properly URI encoded.
credentialsHolder - an AtomicReference to the Credentials to connect with (must not be null)
advisor - the ConnectionAdvisor to use (must not be null)
locationServiceRelativePath - the URI path (relative to the scheme, host, and port of the main URI computed from the profile data) where the location service can be reached for this connection (must not be null or empty)
Method Detail

getSessionID

public com.microsoft.tfs.util.GUID getSessionID()
The session ID is a unique GUID that is created when TFSConnection is constructed. It is useful only for identifying TFSConnection instances and it may be sent to the TFS in HTTP headers.

Returns:
session ID of this TFSConnection instance (never null)

getCatalogResourceID

public com.microsoft.tfs.util.GUID getCatalogResourceID()
Gets the catalog identifier from this connection's ServerDataProvider.

Returns:
the GUID used to identify the service this TFSConnection is connected to in the TFS catalog (never null)

getCatalogNode

public CatalogNode getCatalogNode()
Returns:
the CatalogNode for the service this TFSConnection is connected to. Will be null if no catalog service is present on the server.

getCatalogService

protected abstract ICatalogService getCatalogService()
Gets the ICatalogService for this connection. Derived classes must implement this to support getCatalogNode().


getInstanceID

public com.microsoft.tfs.util.GUID getInstanceID()
Gets the instance identifier from this connection's ServerDataProvider.

Returns:
the GUID used to identify the TFS instance

getServerDataProvider

protected abstract ServerDataProvider getServerDataProvider()
Gets the ServerDataProvider for this connection.

Service discovery is often a slow process. Derived classes should cache the result of the first call to ensure subsequent calls to this method finish quickly.

Returns:
the ServerDataProvider, which provides information about the server this TFSConnection is connected to (never null)

hasAuthenticated

public abstract boolean hasAuthenticated()
Tests whether the connection has authenticated. This is left for derived classes to implement so they can use their knowledge of whether the ServerDataProvider has been initialized to make the test more efficient.

Returns:
true if this connection has authenticated to the server, false if it has not

close

public void close()

This Closable interface method must be called when this TFSConnection instance is no longer needed. This method cleans up resources associated with this instance. After calling this method, this instance should be discarded.

After calling close(), no methods on a TFSConnection instance should be subsequently called. The close() method should only be called once.

Specified by:
close in interface com.microsoft.tfs.util.Closable

getAuthenticatedIdentity

public TeamFoundationIdentity getAuthenticatedIdentity()
Returns the identity that authenticated with the server. When using TFS Impersonation this will be the identity doing the impersonation, not the user the call is being made on behalf of. Because of this, getAuthorizedIdentity() is usually the correct identity to use from this API. TEE does not currently support impersonation, so the identies for authorized vs. authenticated should always be the same.


getAuthorizedIdentity

public TeamFoundationIdentity getAuthorizedIdentity()
The identity who the calls to the server are being made for. TEE does not currently support impersonation, so the identies for authorized vs. authenticated should always be the same.


getAuthorizedTFSUser

public TFSUser getAuthorizedTFSUser()
Gets the authorized user name in the form of a TFSUser object, which includes the account name and domain. If this TFSConnection has not already authorized, an authorization is done to retrieve the authorized user name.

Returns:
the authorized user name as a TFSUser

getAuthorizedAccountName

public java.lang.String getAuthorizedAccountName()
Gets the authorized identity's account name, which does not include a domain name. If the authorized user's full domain identity is "MYDOMAIN\\myuser" (single backslash), then the account name is just "myuser". If this TFSConnection has not already authenticated the user, an authenticated is done to retrieve the authorized user name.

Returns:
the authorized user's account name

getAuthorizedDomainName

public java.lang.String getAuthorizedDomainName()
Gets the authorized identity's domain name, which does not include an account name. If the authorized user's full domain identity is "MYDOMAIN\\myuser" (single backslash), then the domain name is just "MYDOMAIN". If this TFSConnection has not already authenticated the user, an authenticated is done to retrieve the authorized domain name.

Returns:
the authorized user's domain

ensureAuthenticated

public void ensureAuthenticated()
This method will authenticate the connection if not previously authenticated.


authenticate

public void authenticate()
This method actually authenticates with the server, using the specified provider to get credentials if necessary.


connect

public void connect(ConnectOptions connectOptions)
Performs all of the steps that are necessary for setting up a connection with a TeamFoundationServer. Specify what information should be returned in the connectOptions parameter. Specifies what information that should be returned from the server. The service types to get information for. If service information is not requested in the connectOptions value, this parameter must be null. To request all service definitions, pass "*" as the first and only entry in the array. To only request service information about the possible client zones, pass in null or an empty array.


getWebServiceURI

public java.net.URI getWebServiceURI(java.lang.Object webService)
Called to obtain the URI that a web service is connected to. The specified web service must have been previously returned from a call to getWebService(Class), getWSSWebService(ProjectInfo), or getLinkingWebService(String).

Parameters:
webService - the web service instance (not type) to get the URI for (must not be null)
Returns:
the URI the web service is connected to (must not be null)

getWebService

public java.lang.Object getWebService(java.lang.Class<?> webServiceType)
                               throws UnknownWebServiceException
Obtains a new web service from this TFSConnection. Web service instances are not cached - every call to this method will return a new instance. This method can only create a few kinds of services, the basic internal TFS services. Classes which extend TFSConnection should handle the more specialized types of services.

Parameters:
webServiceType - the web service type (must not be null)
Returns:
a web service of the requested type or null if the web service type is known but no endpoint is appropriate for the current connection (for example, old server which doesn't support the requested service)
Throws:
UnknownWebServiceException - if the kind of web service is not known or can't be created

getWSSWebService

public ms.wss._ListsSoap getWSSWebService(ProjectInfo projectInfo)
Obtains a new sharepoint web service from this TFSConnection. Sharepoint web services are not cached - every call to this method returns a new instance.

Parameters:
projectInfo - the team project to get a sharepoint web service for
Returns:
the sharepoint web service (never null)

getLinkingWebService

public ms.tfs.services.linking._03._IntegrationServiceSoap getLinkingWebService(java.lang.String endpoint)
Obtains a new linking web service from this TFSConnection. Linking web services are not cached - every call to this method returns a new instance.

Parameters:
endpoint - the endpoint for the linking web service to use (must not be null)
Returns:
the linking web service (never null)

setHTTPClientReference

protected void setHTTPClientReference(TFSConnection.HTTPClientReference httpClientReference)
Sets the TFSConnection.HTTPClientReference for this TFSConnection, and increments the use count by one. Subsequent calls to getHTTPClientReference() and getHTTPClient() will return this client.

Parameters:
httpClientReference - the TFSConnection.HTTPClientReference instance to return (or null) to generate a new one.

getHTTPClientReference

protected TFSConnection.HTTPClientReference getHTTPClientReference()
Gets the TFSConnection.HTTPClientReference instance from this TFSConnection. If the TFSConnection.HTTPClientReference instance has not yet been created, returns null.

Returns:
the TFSConnection.HTTPClientReference instance or null.

getHTTPClient

public HttpClient getHTTPClient()
Gets the HttpClient instance from this TFSConnection. If the HttpClient instance has not yet been created, creates it. The HttpClient instance is cached by this TFSConnection.

Returns:
the HttpClient instance (never null)

newHTTPClient

public HttpClient newHTTPClient(java.net.URI proxyScopeURI)
Gets a new HttpClient whose configuration (SSL restrictions, proxy settings, credentials, etc.) are similar to those in use by this TFSConnection's HttpClient. The target URI is required so the correct proxy settings for the scheme and host can be used.

Parameters:
proxyScopeURI - the URI to use to scope proxy settings for (maybe to any type of resource; really only the scheme, host, and port will matter) (must not be null )
Returns:
a new HttpClient which the caller can modify

getTFProxyServerSettings

public TFProxyServerSettings getTFProxyServerSettings()
Gets the TF proxy server settings from this TFSConnection. For a given TFSConnection, this method will always return the same TFProxyServerSettings object (but that object's state may change in between calls).

Returns:
the TFProxyServerSettings for this TFSConnection (never null)

getURL

@Deprecated
public java.net.URL getURL()
Deprecated. use getBaseURI() instead

Obtains the base TF server URL that this TFSConnection connects to (for example, http://server.mycompany.com:8080/). The returned URL is guaranteed to have a path component that ends in a slash (/) character.

Returns:
the TF server URL (never null)

getName

public java.lang.String getName()
Returns a string suitable for user display which identifies this TFS connection. Currently this is the base URI (getBaseURI()) with escaped characters (including spaces and non-ASCII chars) fully decoded into Unicode.


toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

getBaseURI

public java.net.URI getBaseURI()
Obtains the base Team Foundation Server URI that this TFSConnection connects to (for example, http://server.mycompany.com:8080/ for TFS 2005-2008, posibly more like http://server.mycompany.com:8080/tfs/TeamProjectCollection for TFS 2010). The returned URI is guaranteed to have a path component that ends in a slash ( /) character.

Returns:
the base Team Foundation Server URI for this connection (never null)

getLocationServiceURI

public java.net.URI getLocationServiceURI()

getTimeZone

public java.util.TimeZone getTimeZone()
Obtains the TimeZone associated with this TFSConnection.

Returns:
this TFSConnection's TimeZone (never null)

getLocale

public java.util.Locale getLocale()
Obtains the Locale associated with this TFSConnection.

Returns:
this TFSConnection's Locale (never null)

getCaseSensitiveCollator

public java.text.Collator getCaseSensitiveCollator()
Obtains a Collator for the connection's current Locale that considers all character differences important.

Returns:
a Collator for this connection's Locale that considers all character differences important.
See Also:
CollatorFactory.getCaseSensitiveCollator(Locale)

getCaseInsensitiveCollator

public java.text.Collator getCaseInsensitiveCollator()

Obtains a Collator for the connection's current Locale that considers character and accent differences important, but not case.

Returns:
a Collator for this connection's Locale that recognizes primary differences in characters and accents, but not case
See Also:
CollatorFactory.getCaseInsensitiveCollator(Locale)

getServerCapabilities

public ServerCapabilities getServerCapabilities()
The capabilities of the TFS server


isHosted

public boolean isHosted()

getPersistenceStoreProvider

public PersistenceStoreProvider getPersistenceStoreProvider()
Obtains the PersistenceStoreProvider that determines where cache and configuration data is stored.

Child stores may be created from this base store.

Returns:
this TFSConnection's PersistenceStoreProvider (never null)
See Also:
ConnectionAdvisor.getPersistenceStoreProvider(ConnectionInstanceData)

getCredentials

public Credentials getCredentials()

getCredentialsHolder

public java.util.concurrent.atomic.AtomicReference<Credentials> getCredentialsHolder()

getConnectionAdvisor

protected ConnectionAdvisor getConnectionAdvisor()

getWebServiceFactory

protected WebServiceFactory getWebServiceFactory()

getRegistrationClient

public abstract RegistrationClient getRegistrationClient()
Convenience method to get the registration client for this connection. May return null if this kind of TFSConnection doesn't support the registration service.

Returns:
the RegistrationClient (possibly null)

getClient

public java.lang.Object getClient(java.lang.Class<?> clientType)
Gets a client from this TFSConnection. Clients are cached (there will be at most one client created for each client type specified to this method. To get a Windows Sharepoint Services client (WSSClient) do not call this method, call getWSSClient(ProjectInfo) instead.

Parameters:
clientType - the type of client to get (must not be null)
Returns:
a client of the requested type (never null)

getWSSClient

public WSSClient getWSSClient(ProjectInfo projectInfo)
Gets a Windows Sharepoint Services client. Sharepoint clients are cached (there will be at most one client created for each project name specified to this method).

Parameters:
projectInfo - the team project info to get a Windows Sharepoint Services client for (must not be null)
Returns:
a Windows Sharepoint Services client for the requested team project name (never null)

setConnectivityFailureOnLastWebServiceCall

public void setConnectivityFailureOnLastWebServiceCall(boolean failure)

getConnectivityFailureOnLastWebServiceCall

public boolean getConnectivityFailureOnLastWebServiceCall()

addConnectivityFailureStatusChangeListener

public void addConnectivityFailureStatusChangeListener(ConnectivityFailureStatusChangeListener listener)

removeConnectivityFailureStatusChangeListener

public void removeConnectivityFailureStatusChangeListener(ConnectivityFailureStatusChangeListener listener)


© 2015 Microsoft. All rights reserved.