P4 Server file operations

To define common P4 Server-managed file attributes and options, P4 for Java uses the com.perforce.p4java.core.file.IFileSpec interface. Attributes like revisions, dates, actions, and so on, are also defined in the core.file package, along with some key helper classes and methods. In general, most P4 Server file-related methods are available on the IOptionsServer and IClient interfaces, and might also be available on other interfaces such as the IChangelist interface.

Because P4 Server file operations can typically run to a conclusion even with errors or warnings caused by incoming arguments, and because the server usually interpolates error and informational messages in the list of file action results being returned, most file-related methods do not throw exceptions when a request error is encountered. Instead, the file-related methods return a Java list of results, which can be scanned for errors, warnings, informational messages, and the successful file specs normally returned by the server. P4 for Java provides helper classes and methods to detect these errors.

P4 for Java file methods are also designed to be composable: the valid output of one file method (for instance, IOptionsServer.getDepotFileList) can usually be passed directly to another file method (such as IClient.editFiles) as a parameter. This approach can be very convenient in complex contexts such as ant or Eclipse plug-ins, which perform extensive file list processing.

The snippet below, from the sample ListFilesDemo class, illustrates a very common pattern used when retrieving a list of files (in this case from the getDepotFiles method):

List<IFileSpec> fileList = server.getDepotFiles(
      FileSpecBuilder.makeFileSpecList(new String[] {"//..."}), false);
  if (fileList != null) {
    for (IFileSpec fileSpec : fileList) {
      if (fileSpec != null) {
        if (fileSpec.getOpStatus() == FileSpecOpStatus.VALID) {
          System.out.println(formatFileSpec(fileSpec));
        } else {
          System.err.println(fileSpec.getStatusMessage());
        }
      }
    }
  }