Release Notes for P4Java, the Perforce Java API Version 2009.3 Introduction P4Java is a Java-native API for accessing Perforce SCM services from within Java applications, servlets, plugins, and other Java contexts. Perforce numbers releases YYYY.R/CCCCC, for example, 2002.1/30547. YYYY is the year; R is the release of that year; CCCCC is the bug fix change level. Each bug fix in these release notes is marked by its change number. Any build includes (1) all bug fixes of all previous releases and (2) all bug fixes of the current release up to the bug fix change level. Please send all feedback to support@perforce.com Requirements * Perforce server at Release 2005.2 or higher. * Java: full standard JDK 6 or later, or JDK 5 with file helper class. implementation as discussed in "Known Limitations" below. * Supported Platforms: * Windows XP/2003/Vista/7 * Linux (x86) * Mac OSX 10.5+ (Mac/Carbon) Documentation P4Java interfaces, classes, methods, etc., are documented in the Javadoc tree included in the P4Java distribution and by the P4Java User Guide PDF also included in the distributed zip file. Advanced usage issues, example patterns, etc., are documented in the User Guide PDF. Installation After downloading the P4Java zip distribution file, unzip the file's contents to a suitable directory. Copy or move the enclosed P4Java p4java.jar JAR file to a suitable location for use by IDEs, compilers, applications etc. Similarly copy or move the enclosed Javadoc tree to a suitable place for browsing. Known Limitations * P4Java is limited to working in JDK 6 or later environments unless you supply a suitable implementation of the P4Java com.perforce.p4java.impl.generic.sys.P4JSystemFileCommandsHelper interface as described in the P4Java User Guide and associated Javadoc documents. * P4Java does not honor Unix / Linux umask settings on file creation and sync operations by default (this is a general Java JVM issue, not a P4Java issue). If this is an issue, you can supply a suitable 'com.perforce.p4java.impl.generic.sys.P4JSystemFileCommandsHelper' interface as described in the P4Java User Guide and associated Javadoc documents. * P4Java does not correctly implement or deal with Unix / Linux symbolic links. This is a known issue related to Java's inability to itself implement symbolic links. * P4Java is heavily reliant on the quality and performance of the underlying JVM's NIO implementation; if these are in any way limited or restricted on a target platform, performance and even correctness may suffer. P4Java is known to work correctly on the platforms listed above under "Requirements". * P4Java can not reliably be used in Unicode contexts where files have been added to a Perforce server as "shiftjis" when they are in fact CP932 (or MS932) encoded, and vice-versa. The usual symptoms of this problem include being unable to sync or submit affected files, with an error message that includes the string "Translation of file content failed". This is a known problem due to the inability to define a robust round-trip encoding / decoding between these encodings and the inaccurate use of "shiftjis" to mean either true shift-jis or CP932 by the Perforce server and many Windows tools. There is currently no workaround known. ------------------------------------------- Major new functionality in 2009.3 #234216 (Bug #37582) The undoc interchanges command has been implemented in P4Java. #231905 (Bug #37568) Diff2 command implemented in P4Java. #231806 (Bug #37558) Job deletion now available through P4Java. #220561 (Bug #32576) Implemented zeroconf-based browsing in P4Java based on JmDNS. Note that JmDNS is not bundled with P4Java -- it just has to be on the classpath somewhere for zeroconf to work; if it's not there, you just can't do zeroconf browsing. Minor new functionality in 2009.3 #245412 (Bug #38974) Added a new System property, PropertyDefs.WRITE_IN_PLACE_KEY, that if set to "true", will allow sync file writes to be performed in place rather than to a temporary file (which is then renamed). The motivation here is that on Windows systems, the JVM does not do atomic renames properly (see Sun's bug ID 4017593 for a discussion of this), which can have a performance impact with forced syncs when a file already exists. Do not use this feature unless you have been advised to by Perforce support personnel, and / or you are fully aware of the consquences of doing this, which include possible partial reads of the target file(s) during the sync or improper file contents after network problems. Both cases are highly unlkiely, and in any case no data corruption will occur. #238378 (Bug #38059) IServerInfo now has a method that returns the Proxy Server version if a proxy is being used. #234798 (Bug #37750) Added IServer.isCaseSensitive method to test if a Perforce server is case sensitive or not. This should return true on Linux servers and false on Windows servers. #248702 (Bug #039041) Support reusing sockets for multiple commands run against an IServer object. com.perforce.p4java.rpc.socketPoolSize can now be configured as a property specified to the ServerFactory class when requesting a server that will control how many sockets are retained when a command completes to be used by subsequent commands. This option is off by default and a value of greater than zero must be set to turn on socket pooling. A system property, com.perforce.p4java.RPC_SOCKET_IDLE_TIME, now controls how much time a socket can be idle for before it is closed by the client. Bugs fixed in 2009.3 #262259 (Bug #40201) Tightened up file / stream / socket close logic and error reporting as a side effect of fixing bug #40241. This should help Perforce support debug left-open system file descriptor issues and reduce P4Java resource usage. #261907 (Bug #40241) In certain cases of binary file transfers during sync operations, file CRC values were incorrectly logged as "bad". The file contents were correctly transferred, but sockets and / or file handles were being left open in P4Java as a side-effect. #253486 (Bug #039486) Submit failure was not handled properly; in some situation, it was possible to submit files despite submit failure. #253486 (Bug #039304) Users erroneously saw a "A revision specification (# or @) cannot be used here." message when using IServer.getProtectionEntries(). #248698 (Bug #039012) IFileAnnotation.getLine(boolean processLineEndings) no longer returns incorrect line endings when running annotate against a Windows server. Previously when true was specified as the first parameter to a Windows server the String returned would contain an extra '\r' character. ------------------------------------------- Major new functionality in 2009.2 #216495 (Bug #35310) P4Java type and method names refactored to conform to the following general rules: * "P4J" prefix deleted; * Use "I" as interface name prefix; * "Impl" suffix for impl classes deleted; * Regularize "ChangeList" to "Changelist"; * Deleted "List" and "Summary" suffixes for methods, eg. getClientSummaryList -> getClients; * Normalized "new" prefix to "create" prefix, e.g. newClient -> createClient. #214537 (Bug #35428) P4Java public interface definitions now include setter methods as well as getters for all public fields. #216787 (Bug #35545) P4Java filespec-related interfaces have been refactored to simplify access and functional relationships. #216659 (Bug #35550) IServerResource-based resource (clients, jobs, changelists, labels, and branches) interfaces and associated functionality have been refactored to syntactically and semantically distinguish between "summary" and "full" versions of the associated objects. #216095 (Bug #35674) View-based objects (clients, labels, branches, etc.) now use a unified view map class (ViewMap) as the basis for all view map functionality. #216679 (Bug #32564) P4Java now supports the full creation / deletion / updating of Perforce users through the IServer interface. #216828 (Bug #35810) P4Java now supports the full creation / deletion / updating of Perforce user groups through the IServer interface. #211525 (Bug #34925) P4Java now supports the annotate command for files under its control. #216488 (Bug #35239) P4Java now supports the "protects" command. #216531 (Bug #35797) P4Java now supports counter create / set / delete operations. #216555 (Bug #35801) P4Java now supports the reviews command. #211334 (Bug #35000) P4Java now supports the dbschema and export commands (with documented limitations). Minor new functionality in 2009.2 #216412 (Bug #35081) P4Java now supports the "-k" option to the move and edit commands. #216463 (Bug #35444) P4Java now supports the -a option to login. #216876 (Bug #34567) IServer.deletePendingChangelist now returns a status string on completion. #216871 (Bug #34596) IServer.deleteClient now returns a status string on completion. Bugs fixed in 2009.2 #240240 (Bug #38402) P4Java now reports the have revision correct under all circumstances when using the file spec operations. Previous releases occasionally showed the have revision as either higher or lower than the actual have revision. #240240 (Bug #38015) P4Java now correctly releases file handles on sync and other file operations with binary files. As a side effect, P4Java should no longer log "Bad PKZIP trailer length" messages on syncs and other file operations. Note that even when the file handles were not released or the bad PKZIP trailer messages appeared, data was being correctly transferred and file contents were not being affected. #240240 (Bug #38231) Added IProtectionEntry excluded path methods to detect and / or set excluded paths for protection entries. #240240 (Bug #37980) IServer.getProtectionEntries now returns correct data when used with a file specification parameter. #238859 (Bug #37970) P4Java now works correctly with proxied servers when local proxy caches are out of date. #238858 (Bug #37980) P4Java now returns correct protection entries when used with file specification arguments. #232364 (Bug #37598) P4Java now sets a file's head modification time correctly on submits; this value is now available properly when using the getExtendedFileSpecs method on the IServer interface. #231471 (Bug #37521) P4Java now does a better job of detcting known binary file types and Unicode files on both Unicode and non-Unicode servers. Please note, however, that customers are always strongly encouraged to use explicit type maps for all file types, as file type inference in the absence of type maps or -t flags (etc.) is heuristic and is not guaranteed to get the "correct" answer in all circumstances. #228643 (Bug #36781) P4Java's Metadata class methods getP4JVersionString() and getP4JDateString() now return P4Java release version and date metadata useful for debugging (note that the 2009.2 Metadata class was known as the P4Java class in previous releases). #228609 (Bug #37128) P4Java can now communicate properly with the Perforce server when used with the tr_TR locale. #226748 (Bug #36923) Fixed bug where merge operations sometimes resulted in a ConnectionException with the message "No metadata defined for RPC function encoding: client-OpenMerge2". As a side effect, two-way merges are now implemented in P4Java, allowing for (safe) merges on binary files. #225502 (Bug #36870) P4Java now properly handles submits of files that don't exist on the local client; the error message no longer mentions the "lbr-FosakeFile" function. #219483 (Bug #36074) Clients with no Host field updated through P4Java no longer have the Host field set to 'null' after the update. #217317 (Bug #35376) P4Java authentication ticket system now checks properties for relevant property definitions when saving a ticket value. #217319 (Bug #35378) Tickets files used by P4Java are no longer set read-only with JDK5 and / or Windows systems. #217322 (Bug #35850) When marking a JAR file for add, P4Java correctly detects the type as binary (this is true now for PKZIP-derived files in general). #216522 (Bug #35104) IServer.execMapCmd(CmdSpec.INFO.name(), ... ) correctly down-cases the command name with the RPC implementation. #216289 (Bug #35240) P4Java correctly manages an empty authentication tickets file on Windows platforms. #216261 (Bug #35252) P4Java now uses an 'unset' value for client names rather than defaulting to local host names when no client is set. #216315 (Bug #35290) P4Java now correctly parses and respects the IFileSpec endRevision field value with file history commands.