|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.microsoft.tfs.core.TFSConnection
public abstract class TFSConnection
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:
getSessionID()
), which is a unique GUID associated
with every TFSConnection
instance. This ID may be sent to the TFS in
HTTP headers.HttpClient
(getHTTPClient()
), which is configured for
use with a Team Foundation Server (credentials, proxy settings, etc. are
automatically configured from profile information).getBaseURI()
), which is the fully
qualified URI to the team project collection or configuration server
instance this TFSConnection
is connected to.getClient(Class)
) for high-level access to TFS
services (version control, work items, build, etc.).getWebService(Class)
)
for low-level access to TFS services. This is for internal use by client
classes. In almost all cases you should use the client classes instead of
using the web proxy classes directly.getTFProxyServerSettings()
).getLocale()
) and time zone (getTimeZone()
)
settings associated with this TFSConnection
.getInstanceID()
).
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:
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.
ConnectionAdvisor
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 |
---|
protected TFSConnection(java.net.URI serverURI, java.util.concurrent.atomic.AtomicReference<Credentials> credentialsHolder, ConnectionAdvisor advisor, java.lang.String locationServiceRelativePath)
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.
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 |
---|
public com.microsoft.tfs.util.GUID getSessionID()
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.
TFSConnection
instance (never
null
)public com.microsoft.tfs.util.GUID getCatalogResourceID()
ServerDataProvider
.
GUID
used to identify the service this
TFSConnection
is connected to in the TFS catalog (never
null
)public CatalogNode getCatalogNode()
CatalogNode
for the service this
TFSConnection
is connected to. Will be null
if no catalog service is present on the server.protected abstract ICatalogService getCatalogService()
ICatalogService
for this connection. Derived classes
must implement this to support getCatalogNode()
.
public com.microsoft.tfs.util.GUID getInstanceID()
ServerDataProvider
.
GUID
used to identify the TFS instanceprotected abstract ServerDataProvider getServerDataProvider()
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.
ServerDataProvider
, which provides information about
the server this TFSConnection
is connected to (never
null
)public abstract boolean hasAuthenticated()
ServerDataProvider
has been initialized to make the test more
efficient.
true
if this connection has authenticated to the
server, false
if it has notpublic 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.
close
in interface com.microsoft.tfs.util.Closable
public TeamFoundationIdentity getAuthenticatedIdentity()
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.
public TeamFoundationIdentity getAuthorizedIdentity()
public TFSUser getAuthorizedTFSUser()
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.
TFSUser
public java.lang.String getAuthorizedAccountName()
TFSConnection
has not already authenticated the
user, an authenticated is done to retrieve the authorized user name.
public java.lang.String getAuthorizedDomainName()
TFSConnection
has not already authenticated
the user, an authenticated is done to retrieve the authorized domain
name.
public void ensureAuthenticated()
public void authenticate()
public void connect(ConnectOptions connectOptions)
public java.net.URI getWebServiceURI(java.lang.Object webService)
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)
.
webService
- the web service instance (not type) to get the URI
for
(must not be null
)
URI
the web service is connected to (must not be
null
)public java.lang.Object getWebService(java.lang.Class<?> webServiceType) throws UnknownWebServiceException
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.
webServiceType
- the web service type (must not be null
)
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)
UnknownWebServiceException
- if the kind of web service is not known or can't be createdpublic ms.wss._ListsSoap getWSSWebService(ProjectInfo projectInfo)
TFSConnection
.
Sharepoint web services are not cached - every call to this method
returns a new instance.
projectInfo
- the team project to get a sharepoint web service for
null
)public ms.tfs.services.linking._03._IntegrationServiceSoap getLinkingWebService(java.lang.String endpoint)
TFSConnection
.
Linking web services are not cached - every call to this method returns a
new instance.
endpoint
- the endpoint for the linking web service to use (must not be
null
)
null
)protected void setHTTPClientReference(TFSConnection.HTTPClientReference httpClientReference)
TFSConnection.HTTPClientReference
for this TFSConnection
, and
increments the use count by one. Subsequent calls to
getHTTPClientReference()
and getHTTPClient()
will
return this client.
httpClientReference
- the TFSConnection.HTTPClientReference
instance to return (or
null
) to generate a new one.protected TFSConnection.HTTPClientReference getHTTPClientReference()
TFSConnection.HTTPClientReference
instance from this
TFSConnection
. If the TFSConnection.HTTPClientReference
instance has
not yet been created, returns null
.
TFSConnection.HTTPClientReference
instance or null
.public HttpClient getHTTPClient()
HttpClient
instance from this TFSConnection
. If
the HttpClient
instance has not yet been created, creates it. The
HttpClient
instance is cached by this TFSConnection
.
HttpClient
instance (never null
)public HttpClient newHTTPClient(java.net.URI proxyScopeURI)
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.
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
)
HttpClient
which the caller can modifypublic TFProxyServerSettings getTFProxyServerSettings()
TFSConnection
. For a
given TFSConnection
, this method will always return the same
TFProxyServerSettings
object (but that object's state may change
in between calls).
TFProxyServerSettings
for this TFSConnection
(never null
)@Deprecated public java.net.URL getURL()
getBaseURI()
instead
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.
URL
(never null
)public java.lang.String getName()
getBaseURI()
) with
escaped characters (including spaces and non-ASCII chars) fully decoded
into Unicode.
public java.lang.String toString()
toString
in class java.lang.Object
public java.net.URI getBaseURI()
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.
URI
for this connection
(never null
)public java.net.URI getLocationServiceURI()
public java.util.TimeZone getTimeZone()
TimeZone
associated with this TFSConnection
.
TFSConnection
's TimeZone
(never
null
)public java.util.Locale getLocale()
Locale
associated with this TFSConnection
.
TFSConnection
's Locale
(never
null
)public java.text.Collator getCaseSensitiveCollator()
Collator
for the connection's current Locale
that considers all character differences important.
Collator
for this connection's Locale
that
considers all character differences important.CollatorFactory.getCaseSensitiveCollator(Locale)
public java.text.Collator getCaseInsensitiveCollator()
Obtains a Collator
for the connection's current Locale
that considers character and accent differences important, but not case.
Collator
for this connection's Locale
that
recognizes primary differences in characters and accents, but not
caseCollatorFactory.getCaseInsensitiveCollator(Locale)
public ServerCapabilities getServerCapabilities()
public boolean isHosted()
public PersistenceStoreProvider getPersistenceStoreProvider()
PersistenceStoreProvider
that determines where cache
and configuration data is stored.
Child stores may be created from this base store.
TFSConnection
's PersistenceStoreProvider
(never null
)ConnectionAdvisor.getPersistenceStoreProvider(ConnectionInstanceData)
public Credentials getCredentials()
public java.util.concurrent.atomic.AtomicReference<Credentials> getCredentialsHolder()
protected ConnectionAdvisor getConnectionAdvisor()
protected WebServiceFactory getWebServiceFactory()
public abstract RegistrationClient getRegistrationClient()
null
if this kind of TFSConnection
doesn't support the registration service.
RegistrationClient
(possibly null
)public java.lang.Object getClient(java.lang.Class<?> clientType)
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.
clientType
- the type of client to get (must not be null
)
null
)public WSSClient getWSSClient(ProjectInfo projectInfo)
projectInfo
- the team project info to get a Windows Sharepoint Services client
for (must not be null
)
null
)public void setConnectivityFailureOnLastWebServiceCall(boolean failure)
public boolean getConnectivityFailureOnLastWebServiceCall()
public void addConnectivityFailureStatusChangeListener(ConnectivityFailureStatusChangeListener listener)
public void removeConnectivityFailureStatusChangeListener(ConnectivityFailureStatusChangeListener listener)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |