com.qumasoft.clientapi
Interface ClientAPI


public interface ClientAPI

Define the QVCS-Enterprise client API interface.

A vanilla Java application can use this API to retrieve data from a QVCS-Enterprise server. Currently, the API only supports retrieval of version control history information from the server; it does not support performing any version control operations, nor does it support fetching actual files or file revisions. All calls on this API are fully synchronous.

If you need to perform version control operations, you should try using the custom ant task included with QVCS-Enterprise.

In typical use, a client would:

  1. Use the ClientFactory.createClientAPIContext() static method to create a ClientAPIContext object, and fill in the username/password, serverIP address, and port number values in that object.
  2. Use the ClientFactory.createClientAPI() static method to create an instance of a class that implements this ClientAPI interface.
  3. Call the getProjectList(ClientAPIContext) method on the ClientAPI object returned by the factory to get a list of projects available from the QVCS-Enterprise server, passing in the ClientAPIContext object that you have filled in with the username/password, etc. data.
  4. Choose an interesting project, and set that project name on the ClientAPIContext object.
  5. Optionally call the getViewList(ClientAPIContext) method on this interface to get a list of available views for the given project.
  6. Optionally set the view name on the ClientAPIContext object. (if you choose not to set the view, then the 'Trunk' view will be used by default).
  7. Call the getProjectDirectoryList(ClientAPIContext) method on this interface to get a list of all the directories for the given project/view.
  8. Choose an interesting directory, and use that directory string to set the appended path on the ClientAPIContext object.
  9. Call the getFileInfoList(ClientAPIContext) method on this interface to get a list of FileInfo objects; each object provides summary information for one file.
  10. Choose an interesting file, and set the filename on the ClientAPIContext object.
  11. Call the getRevisionInfoList(ClientAPIContext) to get a list of RevisionInfo objects; each object provides summary information about a revision associated with the selected file.

The recurse flag in the ClientAPIContext can be used when you want to see all the files in a given directory tree. When the flag is true, then the List of FileInfo objects returned from the getFileInfoList method will include all the files in the appendedPath directory and all the files in all sub-directories beneath the appended path directory.


Method Summary
 java.util.List<FileInfo> getFileInfoList(ClientAPIContext clientAPIContext)
          Get the list of FileInfo objects for the directory specified via the ClientAPIContext.setAppendedPath(java.lang.String) attribute on the clientAPIContext object.
 java.util.List<java.lang.String> getProjectDirectoryList(ClientAPIContext clientAPIContext)
          Get the list of directories for the given project/view.
 java.util.List<java.lang.String> getProjectList(ClientAPIContext clientAPIContext)
          Get the list of projects from the QVCS-Enterprise server.
 java.util.List<RevisionInfo> getRevisionInfoList(ClientAPIContext clientAPIContext)
          Get the list of RevisionInfo objects for the file specified by the clientAPIContext.
 java.util.List<java.lang.String> getViewList(ClientAPIContext clientAPIContext)
          Get the list of views for a given project.
 

Method Detail

getProjectList

java.util.List<java.lang.String> getProjectList(ClientAPIContext clientAPIContext)
                                                throws ClientAPIException
Get the list of projects from the QVCS-Enterprise server. The list of projects returned will depend on the username/password supplied in the clientAPIContext object. Only those projects visible to the given user will be returned. A project is 'visible' to a user if that user has the 'Get File' privilege. Typically, any QVCS-Enterprise user with a READER role, or a DEVELOPER role will have the 'Get File' privilege.

Parameters:
clientAPIContext - the client API context object used to define the username/password and server connection information.
Returns:
a List<String> of project names visible to the username defined in the clientAPIContext.
Throws:
ClientAPIException - if there are any problems.

getViewList

java.util.List<java.lang.String> getViewList(ClientAPIContext clientAPIContext)
                                             throws ClientAPIException
Get the list of views for a given project. To use this method, you must set the name of the project in the clientAPIContext as well as the other parameters needed for the getProjectList method.

Parameters:
clientAPIContext - the client API context object used to define the username/password, server connection information, and project name.
Returns:
a List<String> of view names. At the very least, this List will include the 'Trunk' view.
Throws:
ClientAPIException - if there are any problems, or if the requested project is not found.

getProjectDirectoryList

java.util.List<java.lang.String> getProjectDirectoryList(ClientAPIContext clientAPIContext)
                                                         throws ClientAPIException
Get the list of directories for the given project/view. To use this method, you must set the view name in the clientAPIContext, as well as all the other parameters needed for the getViewList method.

Parameters:
clientAPIContext - the client API context object used to define the username/password, server connection information, project name, and view name.
Returns:
a List<String> of appended path strings for all the directories of a project/view. Each string represents one directory. The empty string "" is used to represent the root directory of the project/view. The Strings for sub-directories are relative to the project root directory and in QVCS-Enterprise terminology are called the directory's 'appendedPath'.
Throws:
ClientAPIException - if there are any problems.

getFileInfoList

java.util.List<FileInfo> getFileInfoList(ClientAPIContext clientAPIContext)
                                         throws ClientAPIException
Get the list of FileInfo objects for the directory specified via the ClientAPIContext.setAppendedPath(java.lang.String) attribute on the clientAPIContext object. If you set the recurse flag to true (via the ClientAPIContext.setRecurseFlag(boolean) attribute), then the returned List will contain elements for the directory identified by the appended path, as well as all the directories beneath that directory.

Parameters:
clientAPIContext - the client API context object used to define the username/password, server connection information, project name, view name, appended path, and optionally, the recurse flag.
Returns:
a List of FileInfo objects; one per file.
Throws:
ClientAPIException - if there are any problems.

getRevisionInfoList

java.util.List<RevisionInfo> getRevisionInfoList(ClientAPIContext clientAPIContext)
                                                 throws ClientAPIException
Get the list of RevisionInfo objects for the file specified by the clientAPIContext.

Parameters:
clientAPIContext - the client API context object used to define the username/password, server connection information, project name, view name, appended path, and the file name.
Returns:
the List of RevisionInfo objects for the file specified by the clientAPIContext. The List could be empty if the file is not under version control. Be careful to identify the location of the file correctly -- i.e. the project name, view name, appended path, and file name must be correct in order for the server to find the file and report its revision information.
Throws:
ClientAPIException - if there are any problems.