Basic P4 for Java usage model

The following basic model for P4 for Java reflects typical P4 Server usage:

  1. A Java application uses the P4 for Java ServerFactory class to obtain an IOptionsServer interface onto a specific P4 Server at a known network address and port, and connects to this P4 Server through the IOptionsServer interface that is returned from the factory.
  2. The application optionally logs in to the P4 Server through the IOptionsServer's login and associated methods.
  3. The application obtains a suitable IClient interface into a P4 Server client workspace through the IOptionsServer interface’s “getClient()” method.
  4. The application syncs the P4 Server client workspace through the IClient interface’s sync method.
  5. The application gets and processes (Java java.util.List) lists of depot, client, and local files in (or associated with) the P4 Server client workspace, through the IOptionsServer and IClient interfaces.
  6. The application adds, edits, or deletes files in the local P4 Server client workspace using the IClient interface. These files are added to the default or a numbered P4 Server changelist represented by one or more IChangelist interfaces, which are obtained through the IClient or IOptionsServer interfaces. There are often several ways to obtain a specific type of object depending on context, but these tend to be convenience methods rather than fundamental.
  7. The application submits a specific changelist using the associated IChangelist interface. This submission can be linked with one or more P4 Server jobs, represented by the IJob interface.
  8. The application can switch between P4 Server workspaces, browse P4 Server jobs and changelists, log in as a different user, and add, edit, or delete files, using the relevant IOptionsServer or IClient interfaces.
  9. To disconnect from a P4 Server, the application calls the disconnect method on the IOptionsServer interface.

It is good practice to determine how to obtain and work with data using the p4 command line client before implementing it in P4 for Java. In general, the methods and options available on the various P4 for Java API interfaces map to the basic P4 Server commands (or the familiar p4 command line equivalent), but there are exceptions. Not all P4 Server commands are available through the P4 for Java API.

This usage model relies heavily on representing all significant P4 Server objects — clients, servers, changelists, jobs, files, revisions, labels, branches, and so on — as first-class Java interfaces, classes, or enums, and, where appropriate, returning these objects as ordered Java lists so that the developer can iterate across the results using typical Java iterator patterns. P4 for Java uses JDK 5 (and later) parameterized types for these lists.

P4 for Java represents most recoverable usage errors and P4 Server errors as Java exceptions that are subclassed out of the main P4JavaException class, and thrown from nearly every significant IOptionsServer and IClient interface method (and from subsidiary and associated class methods). Most such errors are connection errors (caused by a network or connectivity issue), access errors (caused by permissions or authentication issues), or request errors (caused by the P4 Server detecting a badly-constructed request or non-existent file spec). P4 for Java applications catch and recover from these errors in standard ways, as discussed in Exception and error handling.

Exceptions are not used in methods that return multiple files in lists, because the server typically interpolates errors, informational messages, and valid file specs in the same returns. P4 for Java provides a single method call as a standard way of identifying individual returns in the (often very long) list of returns, discussed in detail in P4 Server file operations.

Unlike the P4 API for C/C++ or the p4 command-line client, P4 for Java is not intended for direct end-user interaction. Rather, P4 for Java is intended to be embedded in GUI or command-line applications to provide P4 Server client/server communications, and P4 for Java assumes that the surrounding context supplies the results of user interaction directly to P4 for Java methods as Java objects. Consequently, many of the environment variables used by command-line client users (such as P4PORT or P4USER) are deliberately ignored by P4 for Java. The values they usually represent must be explicitly set by appropriate IOptionsServer methods or other methods.

The standard default P4 for Java server and client implementations are basically thread-safe. To avoid deadlock and blocking, refer to Threading issues.