QVCS-Enterprise QVCS-Enterprise

Understanding the Client API

QVCS-Enterprise includes support for a client-side API. This API allows a Java developer to create a Java application that can query the server for information about the projects and files under version control.

By default, the client API is stateless -- each call to the API will invoke the complete set of requests to the server that are needed to satisfy the request. Typically, this means that for each client API call, under the hood, the client API will:

  1. Login to the server
  2. Perform the set of requests needed to fetch the requested information.
  3. Logoff from the server.

The API does permit more stateful operation so that each operation does not require the login/logoff steps. See the javadocs for setPreserveStateFlag in the the ClientContextAPI interface for more details.

Javadocs that describe the details of the API are available here.

To make use of the client API, you need to include gui_out.jar in your classpath.


Sample code to get the list of projects from the QVCS-Enterprise server.

Using the client API, you can fetch the list projects that are visible to a given user using the following code snippet:

    import com.qumasoft.clientapi.ClientAPI;
    import com.qumasoft.clientapi.ClientAPIContext;
    import com.qumasoft.clientapi.ClientAPIFactory;
    ...
    ClientAPIContext clientAPIContext = ClientAPIFactory.createClientAPIContext();
    clientAPIContext.setUserName(USERNAME);
    clientAPIContext.setPassword(PASSWORD);
    clientAPIContext.setServerIPAddress(SERVER_IP_ADDRESS);
    clientAPIContext.setPort(Integer.valueOf(SERVER_PORT));
    ClientAPI clientAPI = ClientAPIFactory.createClientAPI();
    List<String> projectList = clientAPI.getProjectList(clientAPIContext);
    

where USERNAME should be a valid QVCS-Enterprise username; PASSWORD should be that user's password; SERVER_IP_ADDRESS should be the IP address of the QVCS-Enterprise server; and SERVER_PORT should be the port number (typically 9889) that the server is listening on for connections from clients.

The list of projects will consist only of those projects that are visible to the USERNAME user. A project is 'visible' to a user if that user has the 'Get File' privilege for the given project.


Sample code to get the list of views for a given project

Proceeding from the code snippet above, assume that the bolded line in the code snippet in the preceeding section returned several project names. For the purposes of this example, suppose you want retrieve the names of the views of the first project returned from that call to the client API. To do that, you could do something like:

    ...
    String projectName = projectList.get(0);
    clientAPIContext.setProjectName(projectName);
    List<String> viewList = clientAPI.getViewList(clientAPIContext);

The bolded line immediately above will fetch a list of views that are available for the given project. This list will always have at least the "Trunk" view.

Sample code to get the list of directories for a given project/view

Continuing with the code we've written so far... Suppose we want to fetch the list of directories for the "Trunk" view of the projectName project. We would use code like the following:

    ...
    String viewName = viewList.get(0);  // Get the name of the 1st view (probably 'Trunk').
    clientAPIContext.setViewName(viewName);
    List<String> directoryList = clientAPI.getProjectDirectoryList(clientAPIContext);

The list of directories returned by the getProjectDirectoryList call is a list of all the directories for the given project/view. The directory strings themselves are project relative paths. For example, the String for the project/view root directory is the empty string; other entries include just the project/view relative path component used to uniquely identify the given directory within the chosen project/view. The relative directory paths are called the directory's AppendedPath in QVCS terminology.

Sample code to get the list of files in a given directory

Continuing with our code... To fetch the list of files for a given directory, we need to specify the directory that we are interested in. We do that by setting the appended path in the clientAPIContext. So for example, suppose we know that our project/view has a directory of com/qumasoft/utility that we are interested in. We could get a list of version controlled files in that directory with the following code:

    import com.qumasoft.clientapi.FileInfo;
    ...
    String appendedPath = "com/qumasoft/utility";
    clientAPIContext.setAppendedPath(appendedPath);
    List<FileInfo> fileInfoList = clientAPI.getFileInfoList(clientAPIContext);

You can set/reset the recursion flag in the clientAPIContext to control whether the returned list of FileInfo objects is for just the directory defined by the appended path, or whether the list should also include all the FileInfo objects of all directories beneath the directory defined by the appended path. For example, to retrieve the list of all the files in a given project/view, you would set the appended path to the empty string, and enable the recursion flag:

    import com.qumasoft.clientapi.FileInfo;
    ...
    String appendedPath = "";
    clientAPIContext.setAppendedPath(appendedPath);
    clientAPIContext.setRecurseFlag(true);
    List<FileInfo> fileInfoList = clientAPI.getFileInfoList(clientAPIContext);

Sample code to get the list of revisions for a given file

Suppose you want to see the list of revisions for a particular file. For the purposes of the code example, we'll suppose that the file we're interested in is named "Sample.java" and that it is in the project/view we've been working worth to this point, and is located in the directory identified with an appended path of com/qumasoft/samplecode. We could fetch the list of revisions for that file using the following code snippet:

    import com.qumasoft.clientapi.RevisionInfo;
    ...
    String appendedPath = "com/qumasoft/samplecode";
    String fileName = "Sample.java";
    clientAPIContext.setAppendedPath(appendedPath);
    clientAPIContext.setFileName(fileName);
    List<RevisionInfo> revisionInfoList = clientAPI.getRevisionInfoList(clientAPIContext);