The following basic model for P4Java reflects typical Helix Server usage:
ServerFactory
class
to obtain a IServer
interface onto a specific Helix Server at a known network address and port, and connects to this Helix Server through the IServer
interface that is returned from
the factory.IServer
's login and associated
methods.IClient
interface
into a
Helix Server
client workspace through the IServer
interface’s “get
client” method.IClient
interface’s sync
method.java.util.List
)
lists of depot, client, and local files in (or associated with) the
Helix Server
client workspace, through the IServer
and
IClient
interfaces.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
IServer
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.)IChangeList
interface. This submission can be linked with
one or more
Helix Server
jobs, represented by the IJob
interface.IServer
or
IClient
interfaces.disconnect
method on the
IServer
interface.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
P4JException
class, and thrown from nearly every significant
IServer
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.
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.
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
IServer
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.