P4Java Release Compatibility

Article #:1306Created:10/21/10Modified:10/21/10

The P4Java API maintains binary forward and backward compatibility with applications using P4Java in the face of new functionality continually being added to the Perforce server.

P4Java's strategy for binary forward and backward compatibility was introduced in the 2010.1 release.  Binary compatibility allows for a later P4Java jar file to replace an older one without needing to recompile the implementing application.  See Oracle's Binary Compatibility Guide for more information on binary compatibility. P4Java is guaranteed to be binary forward and backward compatible for version 2009.3 and later.

Make a distinction between "fundamental" and behavioral" parameters.

Fundamental parameters are things such as filespecs that a command needs to execute. Behavioral parameters are the various modifying flags you can pass to the command.

Move behavioral parameters into new "Options" classes.

Each supported Perforce command has its own Options class (for example, SyncOptions).

Passing null for an options parameter is the same as passing a new Options object, and has the same effect as passing no flags to a p4 command. List files = sync(FileSpecBuilder.makeFileSpecList("//depot/..."), null);is equivalent to List files = sync(FileSpecBuilder.makeFileSpecList("//depot/..."), new SyncOptions());Use of chainable setters is encouraged List files = sync(FileSpecBuilder.makeFileSpecList("//depot/..."), new SyncOptions().setClientBypass(true).setForceUpdate(true));Use a more general "throws" clause.

Method signatures throw P4JavaException rather than the various possible exceptions such as ConnectionException, AccessException, and RequestException. Each of these exceptions extend P4JavaException, and the method may continue to throw the extending exceptions classes, allowing the developer to manage the various exceptions separately if desired. Should a new exception class be added, it will also extend P4JavaException.

Implement new method signatures via a new server interface, IOptionsServer.

IOptionsServer extends IServer. All existing commands are reimplemented in IOptionsServer according to the new paradigm. All new functionality will be added to IOptionsServer following the new implementation style.

NOTE:  The older style of P4Java methods will be deprecated in a future release.   Ample time will be given to P4Java users to modify their existing code to the new style.

View the original article here