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

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 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

public int execCheckInFiles(String[] files, String comment, boolean keepCheckedOut, boolean removeLocal, boolean wholeProject, boolean projectRecursively)
                      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

projectRecursively - if true, proceed the project recursively

public int execCheckOutFiles(String[] files, String comment, boolean wholeProject, boolean projectRecursively)
                       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

public int execGetFiles(String[] files, boolean wholeProject, boolean projectRecursively)
                  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

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:

diff - a StringBuffer instance to return diff data in

fileName - name of file in the current working directory

ignoreCase - if true, perform compare ignoring case

ignoreSpace - if true, perform compare ignoring whitespace

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

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

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

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

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

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

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

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

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

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

public int execUpdateFiles(String[] files, boolean wholeProject, boolean projectRecursively)
                     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

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 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