com.togethersoft.openapi.vcs
Interface VcsProvider

All Known Implementing Classes:

DefaultVcsProvider

public interface VcsProvider

This interface is to be implemented by a class supporting specific VCS.
VCS provider is a version control system interface such as SCC or command
line tools. It has functinality common to most version control system interfaces suitable to call from IDE.

Author:

TogetherSoft

Since: Together 4.0

public void addListener(VcsProviderListener listener)

Adds provider event listenter

Stereotype new

public void changeWorkingDirectory(File workingDirectory)
                             throws VcsProviderException

Changes current working directory. The passed directory must be a (sub)
child of root working directory specified in startSession. A session must be started already.
Additional (sub) projects of the one opened in startSession must be created if needed.
As a result of this method invoked, further commands received by VcsProvider
instance expect passed file names to be located in new working directory and this
directory associated with correct project in the repository.

Parameters:

workingDirectory new working directory

public void clearAdvancedOptions(String command)
                           throws VcsProviderException

Clear advanced.
A session must be started prior to call this method.

Parameters:

command command to clear advanced options for

Since:

Together 5.0

public void endSession()
                 throws VcsProviderException

Ends current session. After this method called, current working directory and root working
directory, as well as current and root projects are undefined.
It's possiblie to execute only commands not requiring running session.

public int execAddFiles(String[] files, int[] fileTypes, String comment, boolean makeCheckedOut, boolean removeLocal)
                  throws VcsProviderException

Add files from current working directory to the repository.
Parameters keepCheckedOut and removeLocal cannot be used together. A session must be started prior to call this method.

Parameters:

files array of file names in working directory

fileTypes array of file type constants, one for each element of 'files';
Each element of 'fileTypes' is a collection of bitflags from FILE_TYPE_*

comment comment to be applied to all files

makeCheckedOut if true, make all files checked out to working directory immediately after add

removeLocal if true, remove local copies of files

Returns: result of command execution from EXEC_RESULT_*

public int execChangeFileType(String fileName, int newFileType)
                        throws VcsProviderException

Change file type

Parameters:

fileName a file in current working directory

newFileType one of VcsProviderConstants.FILE_TYPE_*

Returns: result of command execution from EXEC_RESULT_*

Stereotype new

public int execCheckInFiles(String[] files, String comment, boolean keepCheckedOut, boolean removeLocal, boolean wholeProject, boolean projectRecursively, VcsCommitInfo info)
                      throws VcsProviderException

Check in files. Commit the changes made to files (update the repository) and make them uneditable (optionally).
Parameters keepCheckedOut and removeLocal cannot be used together. A session must be started prior to call this method.

Parameters:

files array of file or directory names in working directory; if 'wholeProject'
is true this parameter may be null and thus should be ignored

comment comment to be applied to all files

keepCheckedOut if true, do not perform uncheckout of files

removeLocal if true, remove local copies of files

wholeProject is true, act on all contents of the project; 'files' parameter should be ignored in this case

info information about status of check in operation

projectRecursively if true, proceed the project recursively

Returns: result of command execution from EXEC_RESULT_*

public int execCheckOutFiles(String[] files, String comment, boolean wholeProject, boolean projectRecursively, VcsUpdateInfo updateInfo)
                       throws VcsProviderException

Check out files. Make the specified files available for editing, that is
set them writable. A session must be started prior to call this method.

Parameters:

files array of file or directory names in working directory;
if 'wholeProject' is true this parameter may be null and thus should be ignored

comment comment to be applied to all files

wholeProject is true, act on all contents of the project; 'files' parameter should be ignored in this case

projectRecursively if true, proceed the project recursively

updateInfo - information about updated files (conflicts, merges,...)

Returns: result of command execution from EXEC_RESULT_*

public VcsVersionInfo execFindVersionChangeAuthor(String fileName, String versionId, int lineNo)
                                            throws VcsProviderException

Find the first version in which specified string appears
A session must be started prior to call this method.

Parameters:

fileName - name of file in the current directory

versionId - identifier of version iof the file from which line is taken

lineNo - line number to be searched in the specified version of the file

Returns: information about the version where the specified line first appeared

Stereotype new

public int execGetFileHistory(String file, List versions)
                        throws VcsProviderException

Returns the result of getting history of changes to specified file
A session must be started prior to call this method.

Parameters:

file name of the file in working directory

versions array to receive list of file versions (0 is root version)

Returns: result of command execution from EXEC_RESULT_*

Stereotype new

public int execGetFileInfo(String[] files, boolean wholeProject, boolean projectRecursively, List fileInfo)
                     throws VcsProviderException

Retrieves the information about files
Information is returned as array list of VcsFileInfo objects
A session must be started prior to call this method.

Parameters:

files array of file names in working directory; if 'wholeProject'
is true this parameter may be null and thus should be ignored

wholeProject if true, act on all contents of the project; 'files' parameter should be ignored in this case

projectRecursively if true, proceed the project recursively

fileInfo array list with project files information

Returns: result of command execution from EXEC_RESULT_*

Stereotype new

public int execGetFiles(String[] files, boolean wholeProject, boolean projectRecursively, VcsUpdateInfo updateInfo)
                  throws VcsProviderException

Retrieve files from repository to working directory. A session must be started prior to call this method.

Parameters:

files array of file or directory names in working directory; if 'wholeProject'
is true this parameter may be null and thus should be ignored

wholeProject is true, act on all contents of the project; 'files' parameter should be ignored in this case

projectRecursively if true, proceed the project recursively

updateInfo - information about updated files (conflicts, merges,...)

Returns: result of command execution from EXEC_RESULT_*

public int execGetFilesStatuses(String[] files, int[] statuses)
                          throws VcsProviderException

Retrieves the statuses of files from current working directory with names
specified in files array. Returns result in
statuses array. A session must be started prior to call this method.

Parameters:

files array of file names in current working directory

statuses array of int to be filled with statuses

Returns: result of command execution from EXEC_RESULT_*

public int execGetMissingFiles(Vector files)
                         throws VcsProviderException

Retrieves the list of file names in current VCS project missing in current
working directory, that is which are to be downloaded from VCS on next
get project operation. A session must be started prior to call this method.

Parameters:

files java.util.Vector instance to be filled up with file names missing in working directory

fileName name of file in the current working directory

Returns: result of command execution from EXEC_RESULT_*

public int execGetRawFileDiff(String fileName, boolean ignoreCase, boolean ignoreSpace, StringBuffer diff)
                        throws VcsProviderException

Returns the raw result of diff command run on a file. The data returned
will then be parsed and displayed in IDE owned window. A session must be started prior to call this method.

Parameters:

fileName name of file in the current working directory

ignoreCase if true, perform compare ignoring case

ignoreSpace if true, perform compare ignoring whitespace

diff a StringBuffer instance to return diff data in

Returns: result of command execution from EXEC_RESULT_*

public int execGetRawFilesHistory(String[] files, boolean wholeProject, boolean projectRecursively, StringBuffer buffer)
                            throws VcsProviderException

Returns the raw result of getting history of changes to specified files
or whole project.
A session must be started prior to call this method.

Parameters:

files array of file names in working directory; if 'wholeProject'
is true this parameter may be null and thus should be ignored

wholeProject if true, act on all contents of the project; 'files' parameter should be ignored in this case

projectRecursively if true, proceed the project recursively

buffer a StringBuffer instance to return history data in

Returns: result of command execution from EXEC_RESULT_*

public int execGetRawVersionsDiff(String versionID1, String versionID2, boolean ignoreCase, boolean ignoreSpace, StringBuffer buf)
                            throws VcsProviderException

Returns the raw result of diff command for two versions of the file. The data returned
will then be parsed and displayed in IDE owned window.
A session must be started prior to call this method.

Parameters:

versionID1 identifier of one version to be compared

versionID2 identifier of another version to be compared

ignoreCase if true, perform compare ignoring case

buf a StringBuffer instance to return diff data in

Stereotype new

public int execGetVersion(String versionID, OutputStream stream)
                    throws VcsProviderException

Retrieve specified version of the file

Parameters:

versionID - provider specific version identifier

stream output stream to which version content will be fetched

Returns: result of command execution from EXEC_RESULT_*

Stereotype new

public int execLockFiles(String[] files, boolean wholeProject, boolean projectRecursively)
                   throws VcsProviderException

Locks file(s) or whole project in repository, so that no one is allowed
to edit files but the current user. A session must be started prior to call this method.

Parameters:

files array of file names in current directory to execute command on

wholeProject if true, the command should be performed on the project
rather than on files, parameter files may be ignored

projectRecursively if true operation on project should be performed recursively

Returns: result of command execution from EXEC_RESULT_*

public int execRemoveFiles(String[] files, String comment, boolean removeLocal)
                     throws VcsProviderException

Remove files from current working directory from repository. A session must be started prior to call this method.

Parameters:

comment comment to be applied to all files

files array of file names in working directory

removeLocal if true, remove local copies of files

Returns: result of command execution from EXEC_RESULT_*

public int execRenameFile(String fileName, String newFileName)
                    throws VcsProviderException

Rename a file from current working directory in repository. A session must be started prior to call this method.

Parameters:

fileName a file in current working directory

newFileName new name for the file

Returns: result of command execution from EXEC_RESULT_*

public int execSearchFileHistory(String file, String pattern, List searchResult)
                           throws VcsProviderException

Search for versions of the file containing specified pattern
A session must be started prior to call this method.

Parameters:

file name of the file in working directory

string pattern to be searched

searchResults array of VcsVersionInfo objects with versions which matched search criteria

Returns: result of command execution from EXEC_RESULT_*

Stereotype new

public int execSelectProject(String defaultProject, File workingDir, boolean createNewProject, StringBuffer selectedProject)
                       throws VcsProviderException

Displays a dialog which allows the user to select a project in repository.
This command can be executed with session not started. If a session is already started, it may be closed.

Parameters:

defaultProject project to be used as default. If null assume none is specified

workingDir the working directory assumed to be associated with the project selected by the user

createNewProject if true, allow the user to create new project.

selectedProject a StringBuffer to return user selected project in

Returns: result of command execution from EXEC_RESULT_*

public int execSetFilesLabel(String[] files, String label, boolean wholeProject, boolean projectRecursively)
                       throws VcsProviderException

Applies a label to latest version of specified files or project in repository.
A session must be started prior to call this method.

Parameters:

files array of file names in current directory to execute command on

label label to apply

wholeProject if true, the command should be performed on the project
rather than on files, parameter files may be ignored

projectRecursively if true operation on project should be performed recursively

Returns: result of command execution from EXEC_RESULT_*

public int execShowAdvancedOptions(String command, boolean project)
                             throws VcsProviderException

Shows dialog with advanced options for command to the user.
A session must be started prior to call this method.

Parameters:

command command to show advanced options for

project if true, the options expected to be project-specific, rather than file-specific

Returns: result of command execution from EXEC_RESULT_*

public int execShowFileDiff(String fileName, boolean ignoreCase, boolean ignoreSpace)
                      throws VcsProviderException

Invokes file difference dialog for specified file or directory.
By default a difference of local copy of file with latest version stored
in repository is shown. The implementation of VcsProvider might choose to
show a dialog to allow the user for selection of other options for diff.
A session must be started prior to call this method.

Parameters:

fileName name of file in the current working directory

ignoreCase if true, perform compare ignoring case

ignoreSpace if true, perform compare ignoring whitespace

Returns: result of command execution from EXEC_RESULT_*

public int execShowFileProperties(String fileName)
                            throws VcsProviderException

Invokes a dialog specific to souce control system with detailed properties for a file.
A session must be started prior to call this method.

Parameters:

fileName name of file in the current working directory

Returns: result of command execution from EXEC_RESULT_*

public int execShowFilesHistory(String[] files, boolean wholeProject, boolean projectRecursively)
                          throws VcsProviderException

Invokes a dialog which shows history of changes to specified files or whole project.
A session must be started prior to call this method.

Parameters:

files array of file names in working directory; if 'wholeProject'
is true this parameter may be null and thus should be ignored

wholeProject if true, act on all contents of the project; 'files' parameter should be ignored in this case

projectRecursively if true, proceed the project recursively

Returns: result of command execution from EXEC_RESULT_*

public int execUnCheckOutFiles(String[] files, boolean removeLocal, boolean wholeProject, boolean projectRecursively)
                         throws VcsProviderException

Undo check out files. Cancel previous checkOut command. Update files from
repository (loose changes) and make them not checked out (readonly).
A session must be started prior to call this method.

Parameters:

files array of file names in working directory

removeLocal if true, remove local copies of files

wholeProject is true, act on all contents of the project; 'files' parameter should be ignored in this case

projectRecursively if true, proceed the project recursively

Returns: result of command execution from EXEC_RESULT_*

public int execUnLockFiles(String[] files, boolean wholeProject, boolean projectRecursively)
                     throws VcsProviderException

Unlock file(s) or the whole project. A session must be started prior to call this method.

Parameters:

files array of file names in current directory to execute command on

wholeProject if true, the command should be performed on the
project rather than on files, parameter files may be ignored

projectRecursively if true operation on project should be performed recursively

Returns: result of command execution from EXEC_RESULT_*

public int execUnSetFilesLabel(String[] files, String label, boolean wholeProject, boolean projectRecursively)
                         throws VcsProviderException

Remove the label from the files
A session must be started prior to call this method.

Parameters:

files array of file names in current directory to execute command on

label label to be removed

wholeProject if true, the command should be performed on the project
rather than on files, parameter files may be ignored

projectRecursively if true operation on project should be performed recursively

Returns: result of command execution from EXEC_RESULT_*

Stereotype new

public int execUpdateFiles(String[] files, boolean wholeProject, boolean projectRecursively, VcsUpdateInfo updateInfo)
                     throws VcsProviderException

Update files with latest version in the repository. Get latest version of files and delete removed files.
A session must be started prior to call this method.

Parameters:

files array of file or directory names in working directory;
if 'wholeProject' is true this parameter may be null and thus should be ignored

wholeProject is true, act on all contents of the project; 'files' parameter should be ignored in this case.

projectRecursively if true, proceed the project recursively

updateInfo - information about updated files (conflicts, merges,...)

Returns: result of command execution from EXEC_RESULT_*

public void free()

Called by the user of VcsProvider when this instance is not used anymore.
Implementation should free all allocated objects and be prepared for garbage collector.

public String getCurrentProject()

Returns currently opened project, or null if no session is opened.

public File getCurrentWorkingDirectory()

Returns working directory for currently opened project, or null if no session is opened.

public int getFileStatus(String filename)
                   throws VcsProviderException

Used to query status information about a list of selected files. This function
must provide fast retrieving of files status, possibly cache the status within a session.

Parameters:

name of file in current working directory

Returns: status of file: collection of bitflags from FILE_STATUS_*

public String getID()

Returns a string which is a unique identifier of VcsProvider.

Returns: Unique identifier for VcsProvider

public String getRootProject()

Returns version control project associated with root working directory

public File getRootWorkingDirectory()

Returns root working directory.

public boolean isSessionStarted()

Returns true if there is currently a session opened, false otherwise

public boolean isValid()

Returns true if this VcsProvider instance is valid and can accept calls to any methods.

public boolean isVcsInternalFile(String fileName)

Checks whether file or directory is internal file used by version
control system

Parameters:

fileName name of file or directory

Returns: true if file or directory is internal resource
used by version control system to maintain information about the project

Stereotype new

public void removeListener(VcsProviderListener listener)

Removes provider event listenter

Stereotype new

public void startSession(String rootProject, File rootWorkingDir, String user, String password)
                   throws VcsProviderException

Starts new session. A session is defined by the root working directory and associated version
control system's project. VcsProvider interface assumes all files in root
working directory and all its subdirectories may be put udner version
control in root project and its subprojects. After session has started,
current working directory is assumed to be the root one.

Parameters:

rootProject VCS project to be associated with root working directory

rooWorkingDir root working directory

user - login user name

password - users's password to login

Stereotype new

public void startSession(String rootProject, File rootWorkingDir)
                   throws VcsProviderException

Starts new session. A session is defined by the root working directory and associated version
control system's project. VcsProvider interface assumes all files in root
working directory and all its subdirectories may be put udner version
control in root project and its subprojects. After session has started,
current working directory is assumed to be the root one.

Parameters:

rootProject VCS project to be associated with root working directory

rooWorkingDir root working directory