1. GemBuilder for Java 3.2 Release Notes

Supported Java JDK

GBJ v3.2 requires Java version 8.

It was built and tested using 1.8.0_102 on Linux on x86_64, and with 1.8.0_402 on Linux on ARM.

Multithreaded RPC

To support performant multiple session GBJ applications, gbj320.jar loads the server thread-safe libraries, rather than the classic GCI libraries used in previous releases of GBJ. A related sources file is provided for debugging, gbjsource320.jar.

gbj320.jar loads the server shared library libgcits* and the GBJ-specific libgbjts*, which use GemStone/S 64 Bit’s thread-safe GCI interface, with the API defined in gcits.hf.

The multiheaded RPC configuration using gbj320.jar has some limitations:

• linked logins are not supported
• client side user actions are not supported
• GsFile operations on the client are not supported

Single Linked Session

To allow linked logins, gbjLnk320.jar is provided, which allows only a single instance of GbjSession to be logged in at a time. Using this .jar file provides the highest performance for a Java VM that only needs a single server session, with one Java thread executing queries. A related sources file is provided for debugging, gbjLnksource320.jar.

gbjLnk320.jar loads the server shared library libgcilnk*, and the GBJ-specific library libgbjlnk*, using the classic GCI defined in gci.hf.

A separate set of javadocs for this environment is provided under docsLnk/.

Using gbjLnk320.jar, the default java stack size is insufficient. The java argument to increase this value should be used; for example, -Xss2048k.

Changes in synchronization for multithreading performance

Previous releases of GBJ used the classic GCI, which required significant extra handling to support multiple sessions.

gbj320.jar supports a Java VM containing multiple logged in instances of GbjSession. Access to the server is by synchronized methods in com.gemstone.gbjgci.GbjGciSession. This provides synchronizing on the instances of GbjSession, allowing multiple Java threads to simultaneously execute queries against multiple server sessions.

Previous releases of GBJ contained static synchronized native methods, which synchronized on the com.gemstone.gbjgci.GbjGciInterface class, which does not allow multithreaded execution of queries. Multiple sessions were supported by nonblocking executions. This access is now only used by the linked interface, and nonblocking executions have been removed. All access to the server is via blocking GCI calls.

New required .jar file

GBJ v3.2 relies on BigFraction for Fraction support. This class is from Apache; see https://commons.apache.org/proper/commons-math/.

Your CLASSPATH or -cp argument must include the .jar file that supports this, commons-math3-3.6.1.jar.

This file can be downloaded from https://dlcdn.apache.org//commons/math/binaries/

New semantics for handling GEMSTONE and locating shared libraries

GBJ requires access to a directory containing the GemStone server shared libraries, and it must know the version of the server that you are intended to connect to.

The process has changed in this release to unambiguously handle the expected configurations.

The follow are expected configurations:

• If you have a full GemStone installation (specifically with the shared libraries in $GEMSTONE/lib/, and version.txt present), and you defined the $GEMSTONE environment variable to point to this directory, then you do not need to do anything further. GBJ looks in the $GEMSTONE/lib directory and does not look in any specification for LD_LIBRARY_PATH or -Djava.library.path=.
• If you do not have a full GemStone installation, for example if you want to compose a directory containing only the shared libraries on a client, do not define $GEMSTONE. You must use the java command line option -Dgemstone.version=3.7.2 and specify either $LD_LIBRARY_PATH or -Djava.library.path=.

The $GBJ_GSVERSION environment variable is no longer used.

TimeZone in Repository must match OS TimeZone during install

To avoid issues where a java.time.ZonedDateTime, which is based on /etc/timezone, and a GemStone server DateTime, which is based on TimeZone current, are not equal, the server’s TimeZone must now match the OS’s configured timezone.

The installation process verifies that the TimeZone installed in the repository (reported by TimeZone current) matches the TimeZone configured in the OS (in /etc/timezone), and reports an error if it does not match.

The GemStone/S 64 Bit v3.7.2 now includes support for updating the timezone by executing code, using TimeZone >> installOsTimeZone. See the GemStone/S 64 Bit v3.7.2 Release Notes or image method comments for more information.

GbjCollection and GemStone Collections

Mapping Collections to GbjCollection did not work correctly for operations such as enumerations, when used against GemStone Collections that are not implemented by the collection directly containing the content elements. These kinds of Collections are now mapped to GbjObject rather than GbjCollection.

Attempting to use GbjCollection with these kinds of collections is no longer allowed.

This includes: Set and Bag, as well as other GemStone specific collections such as GsPipe and RcQueue. Dictionaries are also not supported, due to variations in the implementations.

See GbjGciInterface class >> excludeFromGbjCollectionMapping for the excluded classes.

Improved GemStone-Java class mapping

New class mappings have been added to better support recently added GemStone server specials.

The following table lists the current class mappings:

Obsolete Class no longer installed

GBJ Shared Library information printed

When logging in using GBJ, the specific build information for the server and GBJ shared libraries is printed to stdout.

Handling strings with codepoints over 128

Previously, there were a number of issues in the way java strings outside the ASCII range were handled in GemStone. A number of specific bugs have been fixed, and extensive testing and cleanup has been done in this area.

GCSI statistics initialization failed

When running with GemStone/S 64 Bit v3.7 or later, GCSI statistics initialization failed, as a larger Array size was needed to hold results. (#50994)

GbjIterator raised exception when accessing elements outside of the batch size range

When using an instance of GbjIterator to enumerate over a large collection, if the collection was larger than GbjIterator.BatchSize (which defaults to 1000), then an exception "startindex/numObjs out of range in getObjs()" was raised when attempting to enumerate to an element beyond the batch size. (#47289)

Enumeration over large collection of registered class instances can fail with ClassCastException

When using registerStub to establish a correspondence between a java and GemStone Smalltalk class, and enumerating over a collection of instances of this class that was replicated from the server, and the size of the preload buffer (as set in GbjSession.initialize()) is smaller than the number of objects in the replicated collection, then retrieval of elements that were not preloaded failed with a java.lang.ClassCastException. (#47084)

Incorrect results for GbjObject.stringValue() on very large integers

Using the GbjObject.stringValue() method returned incorrect results on LargeInteger objects. (#46551)

Printout of OOP in GbjObject toString can be negative

When OOPs are printed using GbjObject asString(), for OOPs greater than 1152921504606846975, the printed version wrapped, and was printed as an incorrect negative value. (#48138)

Problems using GbjLauncher programmatically

Calling up the GbjLauncher from a java program on an open session (via "new GbjLauncher(mySession)") worked, but subsequent subwindows could not be opened. This way of invoking GbjLauncher did not execute code that set GemStone-to-java class mappings correctly. (#46531)