The com.perforce.p4java.server.IServer interface represents a specific Perforce server in the P4Java API, with methods to access typical Perforce server services. Each instance of a IServer interface is associated with a Perforce server running at a specified location (network address and port), and each IServer instance is obtained from the P4Java server factory, com.perforce.p4java.server.ServerFactory, by passing it a suitable server URI and optional Java properties.

The snippet below is from the ServerFactoryDemo class in the sample package, and shows a very simple way to prompt the user for a Perforce server URI, connect to the server at the URI, and get basic information about that server. This is the basic “Hello World!” P4Java application, and works like the p4 info command (with suitable attention being paid to formatting details with the formatInfo method below).

BufferedReader lineReader = new BufferedReader(
                            new InputStreamReader(System.in));
try {
  for (;;) {
    System.out.print(PROMPT);
    String serverUriString = lineReader.readLine();
    if serverUriString == null) ||         serverUriString.equalsIgnoreCase("quit" {
      break;
    } else {
      IServer server = ServerFactory.getServer(serverUriString, null);
      server.connect();
      IServerInfo info = server.getServerInfo();
      if (info != null) {
        System.out.println(
          "Info from Perforce server at URI '"
          + serverUriString + "':");
        System.out.println(formatInfo(info));
      }
      if (server != null) {
        server.disconnect();
      }
    }
  }
} catch (RequestException rexc) {
  System.err.println(rexc.getDisplayString());
  rexc.printStackTrace();
} catch (P4JavaException exc) {
  exc.printStackTrace();
} catch (IOException ioexc) {
  ioexc.printStackTrace();
} catch (URISyntaxException e) {
  e.printStackTrace();
}

Multiple IServer objects can represent the same physical Perforce server, and this approach is recommended for heavyweight usage and for multi-threaded applications.

The Java properties parameter passed to the factory in the first example is null, but you can pass in a variety of generic and implementation-specific values as described in Character Set Support.

Perforce client workspaces are represented by the com.perforce.p4java.client.IClient interface, which can be used to issue Perforce client workspace-related commands such as sync commands, file add /delete / edit commands, and so on. A IClient interface is typically obtained from an IServer interface using the getClient() method, and is associated with the IServer using the setCurrentClient() method as illustrated in the ClientUsageDemo snippet below:

IServer server = null;
  try {
    server = getServer(null);
    server.setUserName(userName);
    server.login(password);
    IClient client = server.getClient(clientName);
    if (client != null) {
      server.setCurrentClient(client);
      // use the client in whatever way needed...
    }
  } catch (Exception exc) {
    // handle errors...
  }

Note also the use of the setUserName and login methods on the server to establish the current user and log them in, respectively.

Note also, that unlike the p4 command line client, there are no defaults for user and workspace. Your application must explicitly associate a workspace (an IClient client object) and user with the server using the IServer.getClient and IServer.setCurrentClient methods.

P4Java uses a small set of Java exceptions to signal errors that have occurred in either the Perforce server as a result of issuing a specific command to the server, or in the P4Java plumbing in response to things like TCP/IP connection errors or system configuration issues. (These exceptions are not used to signal file operation problems at the individual file level — see Perforce file operations for details about individual file error handling.)

In general, P4Java exceptions are rooted in two different classes: the P4JavaException classes are intended for “normal” (that is, recoverable) errors that occur as the result of things like missing client files, a broken server connection, or an inappropriate command option; the P4JavaError classes are intended for more serious errors that are unlikely to be recoverable, including unintended null pointers or P4Java-internal errors. The P4JavaException class hierarchy is rooted in the normal java.lang.Exception tree, and any such exception is always declared in relevant method “throws” clauses; the P4JavaError classes, however, are rooted in java.lang.Error, and consequently do not need to be declared or explicitly caught. This allows a developer to catch all such `P4JavaError`s, for example, in an outer loop, but to process “normal” `P4JavaException`s in inner blocks and loops as they occur.

Typically, application code should report a P4JavaError exception and then terminate either itself or whatever it was doing as soon as possible, as this exception indicates a serious error within P4Java. P4JavaException handling is more fine-grained and nuanced: A P4JavaException almost always signals a recoverable (or potentially-recoverable) error, and should be caught individually or at the class level. The following snippet represents a common pattern for P4Java error and exception handling around major functional blocks or processing loops:

try {
  // issue one or more server or client commands...
} catch (P4JavaError err) {
  panic(err); // causes app to exit after printing message to stderr...
} catch (RequestException rexc) {
  // process server-side Perforce error...
} catch (ConnectionException cexc) {
  // process Perforce connection exception...
} catch (P4JavaException exc) {
  // catchall...
} catch (Exception exc) {
  // Other-exception catchall...
}

Note the way RequestException and ConnectionException events are handled separately: RequestException exceptions are almost always thrown in response to a Perforce server error message and therefore include a Perforce severity and generic code that can be used or displayed (other P4JavaExceptions do not usually contain these), and ConnectionExceptions should normally result in the enclosing app explicitly closing or at least re-trying the associated connection, as processing can no longer continue on the current Perforce connection.

To define common Perforce-managed file attributes and options, P4Java 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 Perforce file-related methods are available on the IServer and IClient interfaces, and might also be available on other interfaces such as the IChangeList interface.

Because Perforce 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. P4Java provides helper classes and methods to detect these errors.

P4Java file methods are also designed to be composable: the valid output of one file method (for instance, IServer.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());
        }
      }
    }
  }

Note in particular the use of the FileSpecBuilder.makeFileSpecList helper method that converts a String array to a list of IFileSpec objects; note also the formatFileSpec method referenced above; this simply prints the depot path of the returned IFileSpec object if it’s valid.

The 2009.2 release of P4Java introduced the notion of “summary” and “full” representations of objects on a Perforce server. In many cases the Perforce server only returns summaries of objects that it’s been asked to list. For example, if you issue a p4 clients command to a server, what comes back is a list of client metadata for known client workspaces, but not the associated workspace views. For things like changelists, jobs, branches, and so on, to obtain the full version of the Perforce object (such as a specific client workspace), you typically do a p4 client -o with the workspace’s name.

Similarly, P4Java distinguishes between the summary objects returned from the main list methods (such as IServer.getClients()) and the full objects returned from individual retrieval methods (such as IServer.getClient()).

The snippet below, edited from the ListClientDemo sample app, illustrates a typical usage pattern for summary and full object retrieval:

try {
  IServer server = getServer(null);
  server.setUserName(userName);
  server.login(password);
  List<IClientSummary> clientList = server.getClients(
                                       userName, null, 0);
  if (clientList != null) {
    for (IClientSummary clientSummary : clientList) {
      // NOTE: list returns client summaries only; need to get
      // the full client to get the view:
      IClient client = server.getClient(clientSummary);
      System.out.println(client.getName() + " "
          + client.getDescription().trim() + " "
          + client.getRoot());
      ClientView clientView = client.getClientView();
      if (clientView != null) {
        for (IClientViewMapping viewMapping : clientView) {
          System.out.println("\t\t" + viewMapping);
        }
      }
    }
  }
} catch (RequestException rexc) {
  System.err.println(rexc.getDisplayString());
  rexc.printStackTrace();
} catch (P4JavaException exc) {
  exc.printStackTrace();
} catch (URISyntaxException e) {
  e.printStackTrace();
}

Note that only clients owned by username are returned, and that in order to print the associated client workspace view for each retrieved summary client workspace, we get the full client object. This is more common in cases where a user might iterate across a list of all workspaces known to the Perforce server in order to find a specific client workspace, then retrieve that client (and only that client) workspace in full.

P4Java uses a URI string format to specify the network location of target Perforce servers. This URI string format is described in detail in the server factory documentation, but it always includes at least the server’s hostname and port number, and a scheme part that indicates a P4Java connection (for example, p4java://localhost:1666). Note that:

The Perforce Server at release 2012.1 or higher supports 256-bit SSL connections and trust establishment by accepting the fingerprint of the SSL certificate’s public key.

Due to current US export control restrictions for some countries, the standard JDK package only comes with 128 bit encryption level cyphers. In order to use P4Java to connect to an SSL-enabled Perforce server, those living in eligible countries may download the unlimited strength JCE (Java Cryptography Extension) package and replace the current default cryptography jar files with the unlimited strength files.

To make a secure connection using P4Java, append ssl to the end of the P4Java protocol (for example, p4javassl://localhost:1667). For a new connection or a key change, you must also (re)establish trust using the IOptionsServer's addTrust method. For example:

// Create a P4Java SSL connection to a secure Perforce server
try {
  String serverUri = "p4javassl://localhost:1667";
  Properties props = null;
  IOptionsServer server = ServerFactory.getOptionsServer(serverUri,
                          props);

  // assume a new first time connection
  server.addTrust(new TrustOptions().setAutoAccept(true));

  // if all goes well...

  IServerInfo serverInfo = server.getServerInfo();
} catch (P4JavaException e) {
  // process P4Java exception
} catch (Exception e) {
  // process other exception
}

P4Java represents Perforce server objects (such as changelists, branch mappings, job specs, and so on) to the end user through associated interfaces (such as IChangeList, IBranchSpec, and so on) onto objects within P4Java that mirror or proxy the server-side originals. This means that over time, the P4Java-internal versions of the objects may get out of date with the server originals, or the server originals may need to be updated with corresponding changes made to the P4Java versions.

P4Java’s IServerResource interface is designed to support such proxying and to allow refreshes from the server or updates to the server as necessary. Virtually all useful P4Java objects or interfaces that proxy or represent Perforce server-side objects extend the IServerResource interface, and unless otherwise noted in the individual Javadoc comments, the interface methods can be used to update server- and client-side versions accordingly.

P4Java uses Java properties to set various operational values for specific IServer instances and/or for P4Java as a whole. These properties are typically used for things like preferred temporary file directory locations, application version and name information for Perforce server usage, and the location of a suitable Perforce authentication tickets file (see Authentication for details). A full list of publicly-visible properties (with default values) is given in the PropertyDefs Javadoc.

Properties intended for P4Java use can have “long form” or “short form” names. Long form names are canonical, and are always prefixed by the string represented by PropertyDefs.P4JAVA_PROP_KEY_PREFIX (normally com.perforce.p4java., for example, com.perforce.p4java.userName). Short form names are the same string without the standard prefix (for example, userName). Use long form names when there’s any chance of conflict with system or other properties; short form names, on the other hand, are convenient for putting property values onto URI strings as long as you know the property name won’t collide with another property name in use by the app or system.

Properties can be passed to P4Java in several ways:

The following code shows an example of passing properties to a IServer instance using the URI string query mechanism:

IServer server = ServerFactory.getServer(
  "p4java://test:1666?userName=test12&clientName=test12_client&"
  + "autoConnect=y", null);

Assuming no errors occur along the way, this code returns a IServer object connected to the Perforce server host test on port 1666 with the Perforce client name test12_client and Perforce user name test12 logged in automatically (note that the login only works if the underlying authentication succeeds — see Authentication for details.

Character set support is only enabled for Unicode-enabled Perforce servers. In this mode, P4Java differentiates between Perforce file content character sets (that is, the encoding used to read or write a file’s contents) and the character sets used for Perforce file names, job specs, changelist descriptions, and so on.

This distinction is made due to the way Java handles strings and basic I/O: in general, while file content character set encodings need to be preserved so that the end results written to or read from the local disk are properly encoded, P4Java does not need to know about file metadata or other string value encodings. Because Perforce servers store and transmit all such metadata and strings in normalized UTF-8 form, and because all Java strings are inherently encoded in UTF-16, the encoding to and from non-UTF-16 character sets (such as shiftjis) is done externally from P4Java (usually by the surrounding app), and is not influenced by or implemented in P4Java itself. This means that the character set passed to the IServer.setCharsetName method is only used for translation of file content. Everything else, including all file names, job specs, changelist descriptions, and so on, is encoded in the Java-native Java string encoding UTF-16 (and may or may not need to be translated out of that coding to something like shiftjis or winansi).

P4Java supports file content operations on files encoded in most of the character sets supported by the Perforce server, but not all. The list of supported Perforce file content charsets is available to calling programs through the PerforceCharsets.getKnownCharsets method. If you attempt to set a IServer object’s charset to a charset not supported by both the Perforce server and the local JDK installation, you will get an appropriate exception; similarly, if you try to (for example) sync a file with an unsupported character set encoding, you will also get an exception.

The Perforce server uses non-standard names for several standard character sets. P4Java also uses the Perforce version of the character set, rather than the standard name.

Error messages originating from the Perforce server are localized if the Perforce server is localized; error messages originating in P4Java itself are not currently localized. P4Java’s internal error messages aren’t intended for end-user consumption as-is; your applications should process such errors into localized versions that are presentable to end users.

P4Java includes a simple logging callback feature, documented in the ILogCallback Javadoc page, that enables consumers to log P4Java-internal errors, warnings, informational messages, exceptions, and so on. Logging is enabled or disabled on a P4Java-wide basis, not on a per-connection or per-server basis.

The logging feature performs no message formatting or packaging. You can put the log message through the surrounding application context’s logger as required. In general, your applications should log all error and exception messages. Informational messages, statistics, and warning messages do not need to be logged unless you are working with Perforce support to debug an issue.

The com.perforce.p4java.impl.generic package is the root for a fairly large set of standard implementation classes such as Job, Changelist, and so on. These implementation classes are used internally by P4Java, and while usage is not mandatory, you are encouraged to use them as well. This is especially useful if you wish to extend standard P4Java functionality by, for example, adding audit or authentication methods to standard classes.

The quality of P4Java’s network and file I/O in real-world usage is strongly affected by the quality of implementation of the underlying Java NIO packages. Java’s handling of file metadata also affects I/O. Although JDK 6 is an improvement over JDK 5, it can be difficult to manipulate file type and metadata (such as permissions, access/modification time, symlinks, and so on) in pure Java. These are abilities that C programmers take for granted. Issues often arise from JVM limitations such as an inability to set read-only files as writable, reset modification times, observe Unix and Linux umask values, and so on.

Because of these issues, P4Java has a file metadata helper callback scheme, defined in com.perforce.p4java.impl.generic.sys.ISystemFileCommandsHelper. This approach enables users to register their own file metadata class helper (typically using something like an Eclipse file helper or a set of native methods) with the server factory, to help in cases where the JDK is not sufficient. See the relevant ISystemFileCommandsHelper Javadoc for details.

P4Java is inherently thread-safe when used properly. The following best practices can help to ensure that users do not encounter thread-related problems:

P4Java implements both the Perforce tickets-based authentication and the Perforce single sign on (SSO) feature. Both types of authentication are described in detail in the P4Java Javadoc, but some P4Java-specific issues to note include:

Properties props = new Properties(System.getProperties());
props.setProperty(PropertyDefs.PROG_NAME_KEY, "ant-test");
props.setProperty(PropertyDefs.PROG_VERSION_KEY, "Alpha 0.9d");

    ...

server = IServerFactory.getServer(serverUriString, props);