Basic P4Java usage model

The following basic model for P4Java reflects typical Helix Server usage:

  1. A Java application uses the P4Java ServerFactory class to obtain an IOptionsServer interface onto a specific Helix Server at a known network address and port, and connects to this Helix Server through the IOptionsServer interface that is returned from the factory.
  2. The application optionally logs in to the Helix Server through the IOptionsServer's login and associated methods.
  3. The application obtains a suitable IClient interface into a Helix Server client workspace through the IOptionsServer interface’s “getClient()” method.
  4. The application syncs the Helix 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 Helix Server client workspace, through the IOptionsServer and IClient interfaces.
  6. The application adds, edits, or deletes files in the local Helix Server client workspace using the IClient interface. These files are added to the default or a numbered Helix 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 Helix Server jobs, represented by the IJob interface.
  8. The application can switch between Helix Server workspaces, browse Helix 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 Helix 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 P4Java. In general, the methods and options available on the various P4Java API interfaces map to the basic Helix Server commands (or the familiar p4 command line equivalent), but there are exceptions. Not all Helix Server commands are available through the P4Java API.

This usage model relies heavily on representing all significant Helix 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. P4Java uses JDK 5 (and later) parameterized types for these lists.

P4Java represents most recoverable usage errors and Helix 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 Helix Server detecting a badly-constructed request or non-existent file spec). P4Java 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. P4Java 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 Helix Server file operations.

Unlike the Helix C/C++ API or the p4 command-line client, P4Java is not intended for direct end-user interaction. Rather, P4Java is intended to be embedded in GUI or command-line applications to provide Helix Server client/server communications, and P4Java assumes that the surrounding context supplies the results of user interaction directly to P4Java 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 P4Java. The values they usually represent must be explicitly set by appropriate IOptionsServer methods or other methods.

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