com.starteam
Class Application

java.lang.Object
  com.starteam.Application

public class Application
extends java.lang.Object

The StarTeam SDK's interface to the client application.

Nested Class Summary

static class

Application.ResolveOptions Options that control the behavior of an Application's resolve operations.

Constructor Summary

Application()
Create an Application with a default name.

Application(java.lang.String name)
Create an Application with the given name.

Application(java.lang.String name, ClientContext context)
Create an Application with the given name and client context.

Method Summary

void	close() Closes the client application.
ClientContext	getClientContext() Gets the client context associated with this application.
static java.lang.String	getDefaultName() Gets the client application name.
ServerInfo	getDefaultServerInfo(java.lang.String address, int port) Creates a default ServerInfo for the server at the given address and port.
java.lang.String	getDescription() Gets a verbose description of the client application and runtime environment.
java.lang.String	getName() Gets the client application name.
StarTeamRepositoryIDs	getRepositoryIDs() Returns a StarTeamRepositoryIDs instance, loaded from the local file of server GUIDs
Application.ResolveOptions	getResolveOptions() Gets the options that affect resolve operations for this Application.
Server[]	getServers() Gets the list of Servers that the client application is currently connected to.
TraceFinder	getTraceFinder() Creates a new TraceFinder instance for searching Traces across StarTeam servers.
Server	newServer(ServerInfo info) Creates a new Server object, using the given connection information.
Server	newServer(java.lang.String serverName) Looks up the given server name in starteam-servers.xml, and uses the resulting ServerInfo to construct the server.
Server	newServer(java.lang.String address, int port) Creates a new Server object, using the given host address and port.
java.lang.Object	resolve(java.lang.String url) Resolves the given StarTeam URL/ALM URI to the corresponding StarTeam resource.
Folder	resolveFolder(View view, java.lang.String folderPath) Given a view and a path to a sub-folder return the sub-folder if found.
Project	resolveProject(Server server, int projectID) Resolves the given project ID to a Project object.
Project	resolveProject(Server server, java.lang.String name) Resolves the project name to a Project object.
Server	resolveServer(GUID repositoryID) Resolves the given repository ID to a Server object that has already been connected and logged on as the given user.
Server	resolveServer(GUID repositoryID, java.lang.String userName, java.lang.String password) Resolves the given repository ID to a Server object that has already been connected and logged on as the given user.
Server	resolveServer(java.lang.String address, int port) Resolves the given address and port to a Server object that has already been connected and logged on as the given user.
Server	resolveServer(java.lang.String address, int port, java.lang.String userName, java.lang.String password) Resolves the given address and port to a Server object that has already been connected and logged on as the given user.
ServerInfo	resolveServerInfo(java.lang.String servername) Obtains a ServerInfo for the server with the given description.
View	resolveToView(java.lang.String url) Resolves the given StarTeam URL/ALM URI down to the view.
View	resolveView(Project project, int viewID) Resolves the given view ID to a View object.
View	resolveView(Project project, java.lang.String name) Resolves the view name to a view object.
static void	setDefaultName(java.lang.String name) Sets the client application name.
void	setResolveOptions(Application.ResolveOptions options) Sets the options that affect resolve operations for this Application.
java.lang.String	toStarTeamURL(java.lang.Object object) Resolves the given StarTeam resource to a corresponding URL using an ID based scheme
java.lang.String	toStarTeamURL(java.lang.Object object, boolean useIDBasedScheme, boolean useGUIDbasedScheme) Resolves the given StarTeam resource to a corresponding URL

Methods inherited from class java.lang.Object

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

Constructor Detail

Application

public Application()

Create an Application with a default name.

Application

public Application(java.lang.String name)

Create an Application with the given name.

Parameters:

name - The client application name. The application name is reported to the StarTeam Server at connect time for diagnostic purposes.

Application

public Application(java.lang.String name,
                   ClientContext context)

Create an Application with the given name and client context.

Parameters:

name - The client application name. The application name is reported to the StarTeam Server at connect time for diagnostic purposes.

context - Describes aspects of the client runtime environment.

Method Detail

getDefaultName

public static java.lang.String getDefaultName()

Gets the client application name.

Returns:

The client application name. Default is "<Unknown Application>". To report a specific application name to the StarTeam Server for diagnostic purposes, set the application name prior to connecting.

setDefaultName

public static void setDefaultName(java.lang.String name)

Sets the client application name.

Parameters:

name - The client application name. Default is "<Unknown Application>". To report a specific application name to the StarTeam Server for diagnostic purposes, set the application name prior to connecting.

getName

public java.lang.String getName()

Gets the client application name. Reported to the StarTeam Server for diagnostic purposes.

Returns:

The client application name.

getClientContext

public ClientContext getClientContext()

Gets the client context associated with this application.

Returns:

The client context.

getDescription

public java.lang.String getDescription()

Gets a verbose description of the client application and runtime environment. For example: "<Unknown Application>; SDK 6.0.0.039; JVM 1.4.2_01-b06; Windows XP" .

Returns:

A verbose description of the client application.

getTraceFinder

public TraceFinder getTraceFinder()

Creates a new TraceFinder instance for searching Traces across StarTeam servers.

Returns:

a TraceFinder that can be used to search for Traces across servers

See Also:

TraceFinder

newServer

public Server newServer(ServerInfo info)

Creates a new Server object, using the given connection information.

The Server is automatically added to the application's server collection by Server.connect(), and is removed from the collection by Server.disconnect().

Parameters:

info - Server connection information.

See Also:

ServerInfo, Server.connect(), Server.disconnect(), Server.enableMPX()

newServer

public Server newServer(java.lang.String serverName)

Looks up the given server name in starteam-servers.xml, and uses the resulting ServerInfo to construct the server. If no ServerInfo with that name is found, assumes that servername is the address, and uses the default port.

The Server is automatically added to the application's server collection by Server.connect(), and is removed from the collection by Server.disconnect().

Parameters:

serverName - A server name in starteam-servers.xml.

newServer

public Server newServer(java.lang.String address,
                        int port)

Creates a new Server object, using the given host address and port.

The Server is automatically added to the application's server collection by Server.connect(), and is removed from the collection by Server.disconnect().

Parameters:

address - The server's host address.

port - The server's TCP/IP port.

getServers

public final Server[] getServers()

Gets the list of Servers that the client application is currently connected to.

Servers are added to the collection automatically via Server.connect(), and are removed from the collection via Server.disconnect(). Only Server object created through one of the Application server factory methods are added to the collection. Servers objects created through one of the Server constructors create a default Application of their own.

Returns:

The application's server collection.

close

public void close()

Closes the client application. Any Server objects remaining in the application's server list are disconnected.

resolveServer

public Server resolveServer(java.lang.String address,
                            int port)

Resolves the given address and port to a Server object that has already been connected and logged on as the given user.

The default implementation looks for a matching Server in the application's server collection:

 Server server = resolveUsingServerCollection(address, port, userName);
 if (server != null) {
        return server;
 }
 

If an existing Server cannot be found, then an attempt is made to create a new Server instance:

 ServerInfo info = resolveServerInfo(address, port);
 return resolveToNewServer(info, null, userName, password);
 

An application that wants to extend this algorithm will probably override resolveToNewServer().

Parameters:

address - The desired server's host address.

port - The desired server's port number.

Returns:

The resolved Server, or null if it could not be resolved.

resolveServer

public Server resolveServer(java.lang.String address,
                            int port,
                            java.lang.String userName,
                            java.lang.String password)

Resolves the given address and port to a Server object that has already been connected and logged on as the given user.

The default implementation looks for a matching Server in the application's server collection:

 Server server = resolveUsingServerCollection(address, port, userName);
 if (server != null) {
        return server;
 }
 

If an existing Server cannot be found, then an attempt is made to create a new Server instance:

 ServerInfo info = resolveServerInfo(address, port);
 return resolveToNewServer(info, null, userName, password);
 

An application that wants to extend this algorithm will probably override resolveToNewServer().

Parameters:

address - The desired server's host address.

port - The desired server's port number.

userName - The desired user name, or null if any logged on user is acceptable.

password - The desired password, or null if not known.

Returns:

The resolved Server, or null if it could not be resolved.

resolveServer

public Server resolveServer(GUID repositoryID)

Resolves the given repository ID to a Server object that has already been connected and logged on as the given user.

The default implementation looks for a matching Server in the application's server collection:

 Server server = resolveUsingServerCollection(repositoryID, userName);
 if (server != null) {
        return server;
 }
 

If an existing Server cannot be found, then an attempt is made to find a connect string for the given repository ID:

 String[] candidates = findRepositoryID(repositoryID);
 

We iterate over the candidate connect strings, looking for one that we are able to resolve:

 ServerInfo info = resolveServerInfo(candidates[i]);
 server = resolveToNewServer(info, repositoryID, userName, password);
 

An application that wants to extend this algorithm will probably override resolveToNewServer().

Parameters:

repositoryID - The desired server's repository ID.

Returns:

The resolved Server, or null if it could not be resolved.

resolveServer

public Server resolveServer(GUID repositoryID,
                            java.lang.String userName,
                            java.lang.String password)

Resolves the given repository ID to a Server object that has already been connected and logged on as the given user.

The default implementation looks for a matching Server in the application's server collection:

 Server server = resolveUsingServerCollection(repositoryID, userName);
 if (server != null) {
        return server;
 }
 

If an existing Server cannot be found, then an attempt is made to find a connect string for the given repository ID:

 String[] candidates = findRepositoryID(repositoryID);
 

We iterate over the candidate connect strings, looking for one that we are able to resolve:

 ServerInfo info = resolveServerInfo(candidates[i]);
 server = resolveToNewServer(info, repositoryID, userName, password);
 

An application that wants to extend this algorithm will probably override resolveToNewServer().

Parameters:

repositoryID - The desired server's repository ID.

userName - The desired user name, or null if any logged on user is acceptable.

password - The desired password, or null if not known.

Returns:

The resolved Server, or null if it could not be resolved.

getRepositoryIDs

public StarTeamRepositoryIDs getRepositoryIDs()
                                       throws java.io.IOException

Returns a StarTeamRepositoryIDs instance, loaded from the local file of server GUIDs

Returns:

a StarTeamRepositoryIDs instance, loaded from the local file of server GUIDs

Throws:

java.io.IOException - if an I/O error occurs

resolveServerInfo

public ServerInfo resolveServerInfo(java.lang.String servername)

Obtains a ServerInfo for the server with the given description.

Default implementation searches for a matching ServerInfo in the application's default server-list.xml. If no matching entry is found, it tries to find a matching entry by host address.

Parameters:

servername - Target server description.

Returns:

The matching ServerInfo, or a default ServerInfo if no matching one was found.

See Also:

Application.resolveServerInfo(String,int)

resolveToView

public View resolveToView(java.lang.String url)

Resolves the given StarTeam URL/ALM URI down to the view. Throws an exception if the URL/URI has the wrong format,

Parameters:

url - the StarTeam URL/ALM URI to be resolved

Returns:

View the resolved StarTeam view, or null if the view could not be resolved.

getDefaultServerInfo

public ServerInfo getDefaultServerInfo(java.lang.String address,
                                       int port)

Creates a default ServerInfo for the server at the given address and port.

Parameters:

address - String

port - int

Returns:

ServerInfo

resolveProject

public Project resolveProject(Server server,
                              int projectID)

Resolves the given project ID to a Project object.

The default implementation looks for a matching Project in the server's project collection.

If an existing Project cannot be found, and the Application has enabled auto-refresh for projects, then the Server's project collection is refreshed, and searched again.

If none of these strategies are successful, then resolveProject() returns null.

Parameters:

server - The server that contains the desired project.

projectID - The project ID.

Returns:

The resolved Project, or null if it could not be resolved.

See Also:

Application.ResolveOptions.isAutoRefreshProjectsEnabled()

resolveProject

public Project resolveProject(Server server,
                              java.lang.String name)

Resolves the project name to a Project object.

The default implementation looks for a matching Project in the server's project collection.

If an existing Project cannot be found, and the Application has enabled auto-refresh for projects, then the Server's project collection is refreshed, and searched again.

If none of these strategies are successful, then resolveProject() returns null.

Parameters:

server - The server that contains the desired project.

name - The project name.

Returns:

The resolved Project, or null if it could not be resolved.

See Also:

Application.ResolveOptions.isAutoRefreshProjectsEnabled()

resolveView

public View resolveView(Project project,
                        int viewID)

Resolves the given view ID to a View object.

The default implementation looks for a matching View in the project's view collection.

If an existing View cannot be found, and the Application has enabled auto-refresh for views, then the Project's view collection is refreshed, and searched again.

If none of these strategies are successful, then resolveView() returns null.

Parameters:

project - The project that contains the desired view.

viewID - The view ID.

Returns:

The resolved View, or null if it could not be resolved.

See Also:

Application.ResolveOptions.isAutoRefreshViewsEnabled()

resolveView

public View resolveView(Project project,
                        java.lang.String name)

Resolves the view name to a view object.

The default implementation looks for a matching View in the project's view collection.

If an existing View cannot be found, and the Application has enabled auto-refresh for views, then the Project's view collection is refreshed, and searched again.

If none of these strategies are successful, then resolveView() returns null.

Parameters:

project - The project that contains the desired view.

name - The view name.

Returns:

The resolved View, or null if it could not be resolved.

See Also:

Application.ResolveOptions.isAutoRefreshViewsEnabled()

resolveFolder

public Folder resolveFolder(View view,
                            java.lang.String folderPath)

Given a view and a path to a sub-folder return the sub-folder if found. Return null if the specified folder can not be found. The specified path should be relative to the root folder of the view being searched, and should specify the full hierarchy from the root folder to the one being searched. Does a case sensitive comparison of folder names on platforms which support case sensitivity (e.g. Unix)

Parameters:

view - the view in which the folder is to be found

folderPath - the path to the sub-folder

Returns:

the specified sub folder or null if not found.

getResolveOptions

public final Application.ResolveOptions getResolveOptions()

Gets the options that affect resolve operations for this Application.

Returns:

ResolveOptions that affect resolve operations for this Application

setResolveOptions

public final void setResolveOptions(Application.ResolveOptions options)

Sets the options that affect resolve operations for this Application.

Parameters:

options - that affect resolve operations for this Application

resolve

public java.lang.Object resolve(java.lang.String url)

Resolves the given StarTeam URL/ALM URI to the corresponding StarTeam resource. Throws an exception if the URL/URI has the wrong format, or if the referenced resource cannot be resolved.

Parameters:

url - the StarTeam URL/ALM URI to be resolved

Returns:

Object the resolved StarTeam component

toStarTeamURL

public java.lang.String toStarTeamURL(java.lang.Object object)

Resolves the given StarTeam resource to a corresponding URL using an ID based scheme

Parameters:

object - the StarTeam resource to be resolved

Returns:

a String URL that uniquely identifies the resource

toStarTeamURL

public java.lang.String toStarTeamURL(java.lang.Object object,
                                      boolean useIDBasedScheme,
                                      boolean useGUIDbasedScheme)

Resolves the given StarTeam resource to a corresponding URL

Parameters:

object - the StarTeam resource to be resolved

useIDBasedScheme - True to use an ID Based Scheme, False to use a Name Based Scheme

useGUIDbasedScheme - True to use a GUID Based Scheme, False to use a {host name, port} Based Scheme

Returns:

a String URL that uniquely identifies the resource