com.microsoft.tfs.core.clients.framework.location
Interface ILocationService

All Known Subinterfaces:
ServerDataProvider
All Known Implementing Classes:
FrameworkServerDataProvider, LocationService, PreFrameworkServerDataProvider

public interface ILocationService

The service responsible for providing a connection to a Team Foundation Server as well as the locations of other services that are available on it.

Since:
TEE-SDK-10.1

Method Summary
 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.
 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.
 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.
 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 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.
 

Method Detail

getClientAccessMapping

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.

Returns:
The AccessMapping for the current connection to the server.

getDefaultAccessMapping

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.

Returns:
All of the AccessMappings that this location service knows about.

getConfiguredAccessMappings

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.

Returns:
All of the AccessMappings that this location service knows about.

saveServiceDefinition

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.

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

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.

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

removeServiceDefinition

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.

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

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

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

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

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.

findServiceDefinition

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.

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

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.

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

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.

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.

locationForCurrentConnection

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.

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

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.

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.

locationForAccessMapping

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.

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

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.

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

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.

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.

configureAccessMapping

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.

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.

setDefaultAccessMapping

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

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.

getAccessMapping

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.

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.

removeAccessMapping

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

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.


© 2015 Microsoft. All rights reserved.