Basic P4Java usage model
The following basic model for P4Java reflects typical Helix Server usage:
- 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. - The application optionally logs in to the Helix Server through the IOptionsServer's login and associated methods.
- The application obtains a suitable
IClient
interface into a Helix Server client workspace through the IOptionsServer interface’s “getClient()” method. - The application syncs the
Helix Server
client workspace through the
IClient
interface’s sync method. - 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 andIClient
interfaces. - 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 moreIChangelist
interfaces, which are obtained through theIClient
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. - 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 theIJob
interface. - 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. - 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.