com.microsoft.tfs.core.clients.framework.location
Class LocationService

java.lang.Object
  extended by com.microsoft.tfs.core.clients.framework.location.LocationService
All Implemented Interfaces:
ILocationService, ServerDataProvider
Direct Known Subclasses:
FrameworkServerDataProvider

public class LocationService
extends java.lang.Object
implements ServerDataProvider

The TFS location service. Implements the ILocationService interface via the ServerDataProvider (which extends ILocationService to provide some more convenient methods).

Since:
TEE-SDK-10.1
Thread-safety:
thread-compatible

Constructor Summary
LocationService(TFSConnection connection)
          Construct the TFS Location Service.
 
Method Summary
 void authenticate()
           
 AccessMapping configureAccessMapping(java.lang.String moniker, java.lang.String displayName, java.lang.String accessPoint, boolean makeDefault)
          Configures the AccessMapping with the provided moniker to have the provided display name and access point.
 void connect(ConnectOptions connectOptions)
          Performs all of the steps that are necessary for setting up a connection with a TeamFoundationServer.
 void ensureAuthenticated()
           
 java.lang.String findServerLocation(com.microsoft.tfs.util.GUID serverGuid)
          The function finds the location of the server that has the guid passed.
 ServiceDefinition findServiceDefinition(java.lang.String serviceType, com.microsoft.tfs.util.GUID serviceIdentifier)
          Finds the ServiceDefinition with the specified service type and service identifier.
 ServiceDefinition[] findServiceDefinitions(java.lang.String serviceType)
          Finds the ServiceDefinitions for all of the services with the specified service type.
 ServiceDefinition[] findServiceDefinitionsByToolType(java.lang.String toolType)
          Finds the ServiceDefinitions for all of the services with the specified tool type.
 AccessMapping getAccessMapping(java.lang.String moniker)
          Gets the AccessMapping with the specified moniker.
 TeamFoundationIdentity getAuthenticatedIdentity()
           
 TeamFoundationIdentity getAuthorizedIdentity()
           
 com.microsoft.tfs.util.GUID getCatalogResourceID()
           
 AccessMapping getClientAccessMapping()
          The AccessMapping for the current connection to the server.
 AccessMapping[] getConfiguredAccessMappings()
          All of the AccessMappings that this location service knows about.
 AccessMapping getDefaultAccessMapping()
          All of the AccessMappings that this location service knows about.
 com.microsoft.tfs.util.GUID getInstanceID()
           
protected  com.microsoft.tfs.core.clients.framework.location.internal.LocationCacheManager getLocationCacheManager()
           
 ServerCapabilities getServerCapabilities()
          The capabilities of the TFS server.
 boolean hasAuthenticated()
           
 java.lang.String locationForAccessMapping(ServiceDefinition serviceDefinition, AccessMapping accessMapping)
          Returns the location for the ServiceDefinition for the provided AccessMapping.
 java.lang.String locationForAccessMapping(ServiceDefinition serviceDefinition, AccessMapping accessMapping, boolean encodeRelativeComponents)
          Returns the location for the ServiceDefinition for the provided AccessMapping.
 java.lang.String locationForAccessMapping(java.lang.String serviceType, com.microsoft.tfs.util.GUID serviceIdentifier, AccessMapping accessMapping)
          Returns the location for the ServiceDefinition that has the specified service type and service identifier for the provided AccessMapping.
 java.lang.String locationForCurrentConnection(ServiceDefinition serviceDefinition)
          Returns the location for the ServiceDefintion that should be used based on the current connection.
 java.lang.String locationForCurrentConnection(java.lang.String serviceType, com.microsoft.tfs.util.GUID serviceIdentifier)
          Returns the location for the ServiceDefintion associated with the ServiceType and ServiceIdentifier that should be used based on the current connection.
 void reactToPossibleServerUpdate(int serverLastChangeId)
          Clears any caches that it has if the server has been updated.
 void removeAccessMapping(java.lang.String moniker)
          Removes an AccessMapping and all of the locations that are mapped to it within ServiceDefinitions.
 void removeServiceDefinition(ServiceDefinition serviceDefinition)
          Removes the specified ServiceDefinition from the location service.
 void removeServiceDefinition(java.lang.String serviceType, com.microsoft.tfs.util.GUID serviceIdentifier)
          Removes the ServiceDefinition with the specified service type and service identifier from the location service.
 void removeServiceDefinitions(ServiceDefinition[] serviceDefinitions)
          Removes the specified ServiceDefinitions from the location service.
 void saveServiceDefinition(ServiceDefinition serviceDefinition)
          Saves the provided ServiceDefinition within the location service.
 void saveServiceDefinitions(ServiceDefinition[] serviceDefinitions)
          Saves the provided ServiceDefinitions within the location service.
 void setDefaultAccessMapping(AccessMapping accessMapping)
          Sets the default AccessMapping to the AccessMapping passed in.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LocationService

public LocationService(TFSConnection connection)
Construct the TFS Location Service.

Parameters:
connection - A TFS connection (must not be null)
Method Detail

getLocationCacheManager

protected com.microsoft.tfs.core.clients.framework.location.internal.LocationCacheManager getLocationCacheManager()

configureAccessMapping

public AccessMapping configureAccessMapping(java.lang.String moniker,
                                            java.lang.String displayName,
                                            java.lang.String accessPoint,
                                            boolean makeDefault)
Configures the AccessMapping with the provided moniker to have the provided display name and access point. This function also allows for this AccessMapping to be made the default AccessMapping.

Specified by:
configureAccessMapping in interface ILocationService
Parameters:
moniker - A string that uniquely identifies this AccessMapping. This value cannot be null or empty.
displayName - Display name for this AccessMapping. This value cannot be null or empty.
accessPoint - This is the base URL for the server that will map to this AccessMapping. This value cannot be null or empty. The access point should consist of the scheme, authority, port and web application virtual path of the target-able server address. For example, an access point will most commonly look like this: http://server:8080/tfs/
makeDefault - If true, this AccessMapping will be made the default AccessMapping. If false, the default AccessMapping will not change.
Returns:
The AccessMapping object that was just configured.
Throws:
InvalidAccessPointException - Thrown if the access point for this AccessMapping is invalid or if it conflicts with an already registered access point.

findServiceDefinition

public ServiceDefinition findServiceDefinition(java.lang.String serviceType,
                                               com.microsoft.tfs.util.GUID serviceIdentifier)
Finds the ServiceDefinition with the specified service type and service identifier. If no matching ServiceDefinition exists, null is returned.

Specified by:
findServiceDefinition in interface ILocationService
Parameters:
serviceType - The service type of the ServiceDefinition to find.
serviceIdentifier - The service identifier of the ServiceDefinition to find.
Returns:
The ServiceDefinition with the specified service type and service identifier. If no matching ServiceDefinition exists, null is returned.

findServiceDefinitions

public ServiceDefinition[] findServiceDefinitions(java.lang.String serviceType)
Finds the ServiceDefinitions for all of the services with the specified service type. If no ServiceDefinitions of this type exist, an empty enumeration will be returned.

Specified by:
findServiceDefinitions in interface ILocationService
Parameters:
serviceType - The case-insensitive string that identifies what type of service is being requested. If this value is null, ServiceDefinitions for all services registered with this location service will be returned.
Returns:
ServiceDefinitions for all of the services with the specified service type. If no ServiceDefinitions of this type exist, an empty enumeration will be returned.

findServiceDefinitionsByToolType

public ServiceDefinition[] findServiceDefinitionsByToolType(java.lang.String toolType)
Finds the ServiceDefinitions for all of the services with the specified tool type. If no services exist for this tool type, an empty enumeration will be returned.

Specified by:
findServiceDefinitionsByToolType in interface ILocationService
Parameters:
toolType - The case-insensitive string that will match the tool type of a set of ServiceDefinitions. If null or empty is passed in for this value then all of the ServiceDefinitions will be returned.
Returns:
ServiceDefinitions for all of the services with the specified tool type. If no services exist for this tool type, an empty enumeration will be returned.

getAccessMapping

public AccessMapping getAccessMapping(java.lang.String moniker)
Gets the AccessMapping with the specified moniker. Returns null if an AccessMapping with the supplied moniker does not exist.

Specified by:
getAccessMapping in interface ILocationService
Parameters:
moniker - The moniker for the desired AccessMapping. This value cannot be null or empty.
Returns:
The AccessMapping with the supplied moniker or null if one does not exist.

getClientAccessMapping

public AccessMapping getClientAccessMapping()
The AccessMapping for the current connection to the server. Note, it is possible that the current ClientAccessMapping is not a member of the ConfiguredAccessMappings if the access point this client used to connect to the server has not been configured on it. This will never be null.

Specified by:
getClientAccessMapping in interface ILocationService
Returns:
The AccessMapping for the current connection to the server.

getConfiguredAccessMappings

public AccessMapping[] getConfiguredAccessMappings()
All of the AccessMappings that this location service knows about. Because a given location service can inherit AccessMappings from its parent these AccessMappings may exist on this location service or its parent.

Specified by:
getConfiguredAccessMappings in interface ILocationService
Returns:
All of the AccessMappings that this location service knows about.

getDefaultAccessMapping

public AccessMapping getDefaultAccessMapping()
All of the AccessMappings that this location service knows about. Because a given location service can inherit AccessMappings from its parent these AccessMappings may exist on this location service or its parent.

Specified by:
getDefaultAccessMapping in interface ILocationService
Returns:
All of the AccessMappings that this location service knows about.

locationForAccessMapping

public java.lang.String locationForAccessMapping(java.lang.String serviceType,
                                                 com.microsoft.tfs.util.GUID serviceIdentifier,
                                                 AccessMapping accessMapping)
Returns the location for the ServiceDefinition that has the specified service type and service identifier for the provided AccessMapping. If this ServiceDefinition is FullyQualified and no LocationMapping exists for this AccessMapping then null will be returned.

Specified by:
locationForAccessMapping in interface ILocationService
Parameters:
serviceType - The service type of the ServiceDefinition to find the location for.
serviceIdentifier - The service identifier of the ServiceDefinition to find the location for.
accessMapping - The AccessMapping to find the location for.
Returns:
The location for the ServiceDefinition for the provided AccessMapping. If this ServiceDefinition is FullyQualified and no LocationMapping exists for this AccessMapping then null will be returned.
Throws:
InvalidServiceDefinitionException - The associated ServiceDefinition is not valid and no location can be found.
ServiceDefinitionDoesNotExistException - A ServiceDefinition with the provided service type and identifier does not exist.
InvalidAccessPointException - The AccessMapping passed in does not have a valid access point.

locationForAccessMapping

public java.lang.String locationForAccessMapping(ServiceDefinition serviceDefinition,
                                                 AccessMapping accessMapping)
Returns the location for the ServiceDefinition for the provided AccessMapping. If this ServiceDefinition is FullyQualified and no LocationMapping exists for this AccessMapping then null will be returned.

Specified by:
locationForAccessMapping in interface ILocationService
Parameters:
serviceDefinition - The ServiceDefinition to find the location for.
accessMapping - The AccessMapping to find the location for.
Returns:
The location for the ServiceDefinition for the provided AccessMapping. If this ServiceDefinition is FullyQualified and no LocationMapping exists for this AccessMapping then null will be returned.
Throws:
InvalidServiceDefinitionException - The ServiceDefinition passed in is not valid.
InvalidAccessPointException - The AccessMapping passed in does not have a valid access point.

locationForAccessMapping

public java.lang.String locationForAccessMapping(ServiceDefinition serviceDefinition,
                                                 AccessMapping accessMapping,
                                                 boolean encodeRelativeComponents)
Returns the location for the ServiceDefinition for the provided AccessMapping. If this ServiceDefinition is FullyQualified and no LocationMapping exists for this AccessMapping then null will be returned.

Specified by:
locationForAccessMapping in interface ILocationService
Parameters:
serviceDefinition - The ServiceDefinition to find the location for.
accessMapping - The AccessMapping to find the location for.
encodeRelativeComponents - If true, URI-encode any relative URI path components before appending to the root URI.
Returns:
The location for the ServiceDefinition for the provided AccessMapping. If this ServiceDefinition is FullyQualified and no LocationMapping exists for this AccessMapping then null will be returned.
Throws:
InvalidServiceDefinitionException - The ServiceDefinition passed in is not valid.
InvalidAccessPointException - The AccessMapping passed in does not have a valid access point.

locationForCurrentConnection

public java.lang.String locationForCurrentConnection(java.lang.String serviceType,
                                                     com.microsoft.tfs.util.GUID serviceIdentifier)
Returns the location for the ServiceDefintion associated with the ServiceType and ServiceIdentifier that should be used based on the current connection. If a ServiceDefinition with the ServiceType and ServiceIdentifier does not exist then null will be returned. If a ServiceDefinition with the ServiceType and ServiceIdentifier is found then a location will be returned if the ServiceDefinition is well formed (otherwise an exception will be thrown). When determining what location to return for the ServiceDefinition and current connection the following rules will be applied: 1. Try to find a location for the ClientAccessMapping. 2. Try to find a location for the DefaultAccessMapping. 3. Use the first location in the LocationMappings list.

Specified by:
locationForCurrentConnection in interface ILocationService
Parameters:
serviceType - The service type of the ServiceDefinition to find the location for.
serviceIdentifier - The service identifier of the ServiceDefinition to find the location for.
Returns:
The location for the ServiceDefinition with the provided service type and identifier that should be used based on the current connection.
Throws:
InvalidServiceDefinitionException - The associated ServiceDefinition is not valid and no location can be found.

locationForCurrentConnection

public java.lang.String locationForCurrentConnection(ServiceDefinition serviceDefinition)
Returns the location for the ServiceDefintion that should be used based on the current connection. This method will never return null or empty. If it succeeds it will return a target-able location for the provided ServiceDefinition. When determining what location to return for the ServiceDefinition and current connection the following rules will be applied: 1. Try to find a location for the ClientAccessMapping. 2. Try to find a location for the DefaultAccessMapping. 3. Use the first location in the LocationMappings list.

Specified by:
locationForCurrentConnection in interface ILocationService
Parameters:
serviceDefinition - The ServiceDefinition to find the location for.
Returns:
The location for the given ServiceDefinition that should be used based on the current connection.
Throws:
InvalidServiceDefinitionException - The ServiceDefinition passed in is not valid and no location can be found.

removeAccessMapping

public void removeAccessMapping(java.lang.String moniker)
Removes an AccessMapping and all of the locations that are mapped to it within ServiceDefinitions.

Specified by:
removeAccessMapping in interface ILocationService
Parameters:
moniker - The moniker for the AccessMapping to remove.
Throws:
RemoveAccessMappingException - Thrown if the caller tries to remove the default AccessMapping and this location service cannot inherit its default AccessMapping from a parent.

removeServiceDefinition

public void removeServiceDefinition(java.lang.String serviceType,
                                    com.microsoft.tfs.util.GUID serviceIdentifier)
Removes the ServiceDefinition with the specified service type and service identifier from the location service.

Specified by:
removeServiceDefinition in interface ILocationService
Parameters:
serviceType - The service type of the ServiceDefinition to remove.
serviceIdentifier - The service identifier of the ServiceDefinition to remove.
Throws:
IllegalDeleteSelfReferenceServiceDefinitionExceptio - Thrown if the caller tries to delete the self-reference (location service) ServiceDefinition.

removeServiceDefinition

public void removeServiceDefinition(ServiceDefinition serviceDefinition)
Removes the specified ServiceDefinition from the location service.

Specified by:
removeServiceDefinition in interface ILocationService
Parameters:
serviceDefinition - The ServiceDefinition to remove. This must be a ServiceDefinition that is already registered in the location service. Equality is decided by matching the service type and the identifier.
Throws:
IllegalDeleteSelfReferenceServiceDefinitionException - Thrown if the caller tries to delete the self-reference (location service) ServiceDefinition.

removeServiceDefinitions

public void removeServiceDefinitions(ServiceDefinition[] serviceDefinitions)
Removes the specified ServiceDefinitions from the location service.

Specified by:
removeServiceDefinitions in interface ILocationService
Parameters:
serviceDefinitions - The ServiceDefinitions to remove. These must be ServiceDefinitions that are already registered in the location service. Equality is decided by matching the service type and the identifier.
Throws:
IllegalDeleteSelfReferenceServiceDefinitionException - Thrown if the caller tries to delete the self-reference (location service) ServiceDefinition.

saveServiceDefinition

public void saveServiceDefinition(ServiceDefinition serviceDefinition)
Saves the provided ServiceDefinition within the location service. This operation will assign the Identifier property on the ServiceDefinition object if one is not already assigned. Any AccessMappings referenced in the LocationMappings property must already be configured with the location service.

Specified by:
saveServiceDefinition in interface ILocationService
Parameters:
serviceDefinition - The ServiceDefinition to save. This object will be updated with a new Identifier if one is not already assigned.
Throws:
InvalidServiceDefinitionException - The ServiceDefinition being saved is not valid.
AccessMappingNotRegisteredException - The ServiceDefinition references an AccessMapping that has not been registered.
DuplicateLocationMappingException - Thrown if a given AccessMapping has two or more LocationMappings on a ServiceDefinition.

saveServiceDefinitions

public void saveServiceDefinitions(ServiceDefinition[] serviceDefinitions)
Saves the provided ServiceDefinitions within the location service. This operation will assign the Identifier property on the ServiceDefinition objects if one is not already assigned. Any AccessMappings referenced in the LocationMappings property must already be configured with the location service.

Specified by:
saveServiceDefinitions in interface ILocationService
Parameters:
serviceDefinitions - The ServiceDefinitions to save. These objects will be updated with a new Identifier if one is not already assigned.
Throws:
InvalidServiceDefinitionException - The ServiceDefinition being saved is not valid.
AccessMappingNotRegisteredException - The ServiceDefinition references an AccessMapping that has not been registered.
DuplicateLocationMappingException - Thrown if a given AccessMapping has two or more LocationMappings on a ServiceDefinition

setDefaultAccessMapping

public void setDefaultAccessMapping(AccessMapping accessMapping)
Sets the default AccessMapping to the AccessMapping passed in.

Specified by:
setDefaultAccessMapping in interface ILocationService
Parameters:
accessMapping - The AccessMapping that should become the default AccessMapping. This AccessMapping must already be configured with this location service.
Throws:
AccessMappingNotRegisteredException - The AccessMapping being set to the default has not been registered.

connect

public void connect(ConnectOptions connectOptions)
Performs all of the steps that are necessary for setting up a connection with a TeamFoundationServer. This method will use the ICredentialsProvider specified in the constructor to prompt for credentials if authentication fails.

Specified by:
connect in interface ServerDataProvider
Parameters:
connectOptions - Specifies what information that should be returned from the server.

getAuthorizedIdentity

public TeamFoundationIdentity getAuthorizedIdentity()
Specified by:
getAuthorizedIdentity in interface ServerDataProvider

getAuthenticatedIdentity

public TeamFoundationIdentity getAuthenticatedIdentity()
Specified by:
getAuthenticatedIdentity in interface ServerDataProvider

hasAuthenticated

public boolean hasAuthenticated()
Specified by:
hasAuthenticated in interface ServerDataProvider

ensureAuthenticated

public void ensureAuthenticated()
Specified by:
ensureAuthenticated in interface ServerDataProvider

authenticate

public void authenticate()
Specified by:
authenticate in interface ServerDataProvider

getCatalogResourceID

public com.microsoft.tfs.util.GUID getCatalogResourceID()
Specified by:
getCatalogResourceID in interface ServerDataProvider

getInstanceID

public com.microsoft.tfs.util.GUID getInstanceID()
Specified by:
getInstanceID in interface ServerDataProvider

getServerCapabilities

public ServerCapabilities getServerCapabilities()
Description copied from interface: ServerDataProvider
The capabilities of the TFS server.

Specified by:
getServerCapabilities in interface ServerDataProvider

findServerLocation

public java.lang.String findServerLocation(com.microsoft.tfs.util.GUID serverGuid)
The function finds the location of the server that has the guid passed. Note that the server in question must be a "child" server of the server this object is providing data for. The function finds the location of the server that has the guid passed. Note that the server in question must be a "child" server of the server this object is providing data for.

Specified by:
findServerLocation in interface ServerDataProvider
Parameters:
serverGuid - the GUID for the server we are looking up
Returns:
the location for the server with the provided guid or null if this server does not have a child with the provided guid

reactToPossibleServerUpdate

public void reactToPossibleServerUpdate(int serverLastChangeId)
Description copied from interface: ServerDataProvider
Clears any caches that it has if the server has been updated.

Specified by:
reactToPossibleServerUpdate in interface ServerDataProvider


© 2015 Microsoft. All rights reserved.