1. Installing GemBuilder for Java

This Installation Guide describes how to install GemBuilder for Java (GBJ) into a GemStone Repository, and how to configure Java clients to log in to GemStone using GBJ.

This version of GemBuilder for Java supports both 32-bit GemStone/S, and GemStone/S 64 Bit 3.2.x and 3.3.x.

For details on the changes in this version of GBJ, see the GemBuilder for Java Release Notes for version 3.1.3.

The GemBuilder for Java installation process includes installing the GBJ interface files into the GemStone repository, and configuring your system to allow a GBJ Java application to log into GemStone. You need only install the GBJ interface files into the server once for each release of GBJ, but each Java client must be configured for login.

System Requirements

GemBuilder for Java includes components that are part of both the GemStone server and the Java client. A supported GemStone server product and version, and a supported client platform, are required

GemStone Server

Product and Platform

A supported GemStone object server version, installed on a network-accessible host.

GemBuilder for Java version 3.1.3 is compatible with 32-bit GemStone/S versions 6.7 and above, GemStone/S 64 Bit versions 3.2.15 and later 3.2.x versions, and 3.3.1 and above.

GemBuilder for Java v3.1.3 has been tested with the following server versions:

  • GemStone/S 64 Bit v3.3.1
  • GemStone/S 64 Bit v3.2.15
  • GemStone/S (32-bit) v6.7

Supported platforms

Supported platforms for the GemStone Server are provided in the Installation Guide for your server product and version.

Server keyfile

With versions of GemStone/S 64 Bit after v3.2 and GemBuilder for Java v3.1.3, authorization for using GemBuilder for Java is provided by the GS/64 keyfile. You will need to have a keyfile that provides authorization for use with GemBuilder for Java in order to use GemBuilder for Java. If you require a keyfile, write to keyfiles@gemtalksystems.com, or contact GemTalk Technical Support.

GemBuilder for Java Client

Supported Platforms

GemBuilder for Java clients are supported for the same set of platforms as the GemStone server that these clients will connect to. These platforms are provided in the Installation Guide for your server product and version.

You may run GBJ clients on supported platform other than the one your GemStone server is running on, provided you use the appropriate client libraries.

With GemStone/S 64 Bit, which does not support running the server on Windows, you may run GBJ clients on Windows by using the Gemstone/S 64 Bit Windows client distribution.

Note that since Oracle does not provide 32-bit versions of Java 1.8 on Solaris, GBJ 3.1.3 and later clients cannot be used on Solaris with 32-bit GemStone/S servers.

Server Shared Libraries

GBJ clients must have access to shared libraries that are linked for a specific version of GBJ and a specific version of the GemStone server. These shared libraries are distributed with the GemStone server with GemStone/S 64 Bit.

Each GemStone/S 64 Bit distribution includes the GBJ shared libraries for the most recent previous GBJ version. For a GBJ release such as this that does not coincide with the GemStone server release, please contact GemTalk Technical Support for the correct libraries for your server version/s and platform/s.

Java JDK

A Java 8 development environment. This release was built and tested with Java Development Kit (JDK) version 1.8.0_102. Later versions of the JDK are expected to work.

Installing GemBuilder for Java into the GemStone Server

The following instructions describe installing the GemBuilder for Java Smalltalk code into your GemStone/S or GemStone/S 64 Bit repository. Once the GemBuilder for Java code is installed, you will configure your client machines to log in to this repository.

If you are upgrading from an older version of GemBuilder for Java, follow this process to install version 3.1.3.

Note that if you are upgrading from a GBJ 2.x version, the GBJ 3.x class names are different; both the 2.x and 3.x versions of GBJ will be available after this installation process. Carefully review the GBJ 3.0 Release Notes , as well as the Release Notes for all intermediate versions, to determine how the changes affect your application.

Prepare for Installation

1. Select an installation directory, installdir, and make this directory the current working directory.

You can install GemBuilder for Java in any directory. We recommend installing GBJ at the same level as the GemStone server installation directory. You will need about 6 MB of free disk space.

2. GemBuilder for Java is provided as a zipped archive file, GemBuilderJava3.1.3.zip. Move this distribution file to the directory location in which GemBuilder for Java will be installed.

3. Unzip the distribution file using unzip.

InstallDir now contains a GemStone directory with a name similar to GemBuilderJava3.1.3. In the instructions that follow, we refer to this directory as gbj_directory.

gbj_directory includes the following:

- list of file contents
gbj313.jar - the Java class library
gbjopensrc313.jar - class library with open source libraries used by the GBJ tools
GbjTest.zip - example Android application
README.android.txt - readme for Android application

doc - directory containing GemBuilder for Java javadocs documentation:

index.html - the entry point for the online javadocs documentation
api - directory containing support files for the online javadocs documentation.
copyinfo.html - intellectual property ownership information
open_source_licenses.txt - licenses for open-source components.
sources.html - Further information and GemStone Technical Support

server - directory containing:


Environment Setup

GemBuilder for Java version 3.1.3 requires several environment variables to be set prior to installation, including the path.

1. The GEMSTONE environment variable, $GEMSTONE or %GEMSTONE%, should be set to the GemStone server installation directory. This is described in the GemStone server documentation. Verify that this is set correctly.

2. Your path should include the path for the Gemstone Server executables,
$GEMSTONE/bin or %GEMSTONE%\bin.

3. $GBJ or %GBJ% should be set to the GemBuilder for Java installation directory.

C shell:

% setenv GBJ gbj_directory

Bash, Bourne or Korn shell:

$ GBJ=gbj_directory
$ export GBJ

On Windows, you may set this using the System control panel, or execute the following:

c:\> set GBJ=gbj_directory

Installing GemBuilder for Java into your Repository

1. If necessary, start up the GemStone repository monitor (Stone). You may also want to start a NetLDI for use later in testing the GBJ installation.

2. At a command prompt, cd to a working directory, in which you want the installation log to be created. You must have write permission for this directory.

3. Log in to the GemStone server as SystemUser, using linked Topaz. Use the -i switch, which keeps Topaz from reading any initialization file you might have.

4. File in the server component, which is located in the server directory of the GemBuilder for Java installation tree.

If you are installing into GemStone/S 64 Bit, use the file install.gs; if you are installing into 32-bit GemStone/S, file in install32.gs.

For example:

topaz 1> input $GBJ/server/install.gs

During the file-in operation, output is directed to the file Gbj313ServerFilein.log in the current directory.

The file-in operation should end with a message that the errorcount is 0. If errorcount is not 0, errors have occurred; contact GemStone Technical Support, providing the file Gbj313ServerFilein.log as well as details about the installation process.

The installation script performs the commit, so you do not need to commit.

5. Exit Topaz:

topaz 1> quit

Your GemStone server is now ready for use by GemBuilder for Java clients.

Client Setup


Verify that TCP/IP networking is functional on your client machine, and that there is a network path to the Stone’s host. You will need to have the Stone and a NetLDI running, and the GBJ server component should have been successfully installed in the Stone.

Copy GBJ files to the client

If you are running the GBJ client on the same machine as the GemStone server, you can set your GEMSTONE, CLASSPATH and PATH or LD_LIBRARY_PATH to existing GBJ and server installation directories. However, if you are running the GBJ client on a separate machine, you will need to set up the client machine with the correct files.

1. GBJ jar files

If you are running the GBJ client on the same machine as the server, use the existing location configured in $GBJ.

If the GBJ client is on a different machine, install the GBJ distribution on the client. You may install these from the distribution archive as was done on the server, as described under Prepare for Installation. You may also copy the required files from the server installation.

The required files from the GBJ distribution are the jar file gbj313.jar and, if you are using the GBJ development tools, gbjopensrc313.jar. However, the javadocs provide key documentation for GBJ functions and should also be copied to the client.

The directory containing the GBJ jar files accessible to the client will be referred to as gbj_jar_dir.

2. GBJ and GCI client shared libraries

The GBJ clients require access to both the GCI (GemStone server) shared libraries and the GBJ shared libraries. All these shared libraries are specific to the server product and version and to the client platform; the GBJ shared libraries are also specific to the version of GBJ.

If you are running the GBJ client from a machine other than the GemStone server machine, copy the GCI client libraries to a location accessible from the client machine. If this is a different platform than the one the GemStone server is running on, you may need to use the GemStone server distribution for a platform other than your server platform to locate the correct libraries. Contact GemStone Technical Support if you cannot locate the correct client libraries.

The client libraries are located in the directory $GEMSTONE/lib on UNIX or Linux, or %GEMSTONE%\bin on Windows.

There are also linked versions of the GCI client libraries, which you may use in custom GBJ applications. The GBJ tools support only RPC logins.

Note that only 64-bit applications are supported with GBJ with GemStone/S 64 Bit, and only 32-bit application with GBJ with 32-bit GemStone/S. Libraries are provided for 32-bit java applications for GemStone/S 64, for convenience, but these have not been certified.

The server shared libraries may be located in any directory on your library load path, with the exception of the GCI library for GemStone/S 64 Bit Windows clients. For GemStone/S 64 Bit clients on Windows, you should copy the libgcirpc-NNN-64.dll library to the %GEMSTONE%/lib directory.

The following table lists the names of the required shared library files, including both the GBJ shared libraries and the GCI shared libraries.

Table 1 Client Shared Libraries for GBJ 3.1.3


Solaris, Linux, and AIX


GemStone/S 64 Bit v 3.3.1

(contact GemTalk Technical Support)



libgbjgci313-3.3.1-64.dll (contact GemTalk Technical Support)




GemStone/S 64 Bit v

libgbjgci313-3.2.15-64.so (contact GemTalk Technical Support)



libgbjgci313-3.2.15-64.dll (contact GemTalk Technical Support)





libgbjgci313.so (contact GemTalk Technical Support)


gbjgci313.dll (contact GemTalk Technical Support)




The directory containing the server GBJ and GCI shared library files will be referred to as shared_library_dir.

Set environment variables


Verify that your GEMSTONE environment variable is set correctly.


Set the GBJ_GSVERSION environment variable to the GemStone server version. For example (UNIX or Linux, using bash shell):

% export GBJ_GSVERSION=3.3.1

This environment variable is not required if you have a complete GemStone installation; GBJ can also read the version number from $GEMSTONE/version.txt. or %GEMSTONE%\version.txt.


The CLASSPATH environment variable must include the GBJ class library, gbj313.jar, and (if you are using the GBJ Tools) the open source library gbjopensrc313.jar. These must be in a directory accessible from the client, as described above in GBJ jar files. F

For example, to set the CLASSPATH on UNIX or Linux using bash shell:

$ export CLASSPATH=$JDK/lib:gbj_jar_dir/gbj313.jar:gbj_jar_dir/gbjopensrc313.jar

On Windows, you may set this using the System control panel, or execute the following:

c:> set CLASSPATH=%JDK%\lib;gbj_jar_dir\gbj313.jar;gbj_jar_dir\gbjopensrc313.jar
4. Shared Library Path

Set the shared library path environment variable to include the client library directory, shared_library_dir, as described above in GBJ and GCI client shared libraries.

On UNIX and Linux, the LD_LIBRARY_PATH environment variable must include the directories containing the GCI and GBJ shared libraries. For example, using bash:

$ export LD_LIBRARY_PATH=shared_library_dir

On Windows, the %PATH% environment variable must include the directories containing the GCI and GBJ shared libraries. You may set this using the System control panel, or execute the following:

c:> set PATH=%PATH%;shared_library_dir
5. Executable path

If you have not already done so, add the Java executable directory to the path. To use the GBJ tools, you must have the Java executable directory, such as the JDK bin directory, on your path.

To set this on UNIX or Linux, for example, using bash:

$ export PATH=$JDK/bin:$PATH

On Windows, you may set this using the System control panel, or execute the following:

c:\> set PATH=%PATH%;C:\jdk1.8.0_102\bin

Start up the GBJ Launcher and log into GemStone

The GBJ Launcher allows you to specify the name and location of the GemStone server and the other parameters that control the login. Note that to log in to GemStone, you must have the GemStone server and a NetLDI running on the GemStone server machine, and be otherwise configured to allow login.

1. Invoke the GBJ Tools Launcher.

The GBJ Launcher is in com.gemstone.tools.GbjLauncher.This tool supports the following options on the command line:

  • help — print a help message (to standard output)
  • version — print GBJ version information
  • UseLogFile filename — write log output to the specified file
  • NoFileLogger — send log output to standard output rather than to a file
  • UsePrefFile filename — use the specified file for the preferences file
  • NoPrefFile — do not load or save a preferences file

To open the Launcher, with GemStone/S 64 Bit:

prompt> java -d64 com.gemstone.tools.GbjLauncher [options]

With GemStone/S 32 Bit:

prompt> java com.gemstone.tools.GbjLauncher [options]

This opens the GBJ Tools Launcher

2. Enter Login Parameters

In the Tools Launcher, click Login to begin a session. A Session Parameters Dialog appears, prompting you for the session parameters.

Fill in the session parameters, as described in Table 2 . More detail on the specific details for configuring login parameters can be found in the GemStone/S System Administration Guide.

Table 2 Session Parameters



GemStone Server

(Required.) The name of the Stone process. For a Stone running on a remote server, this may include the Network Resource String (NRS), although this is only needed if the gem service is not on the same machine as the stone.

For more information on NRS and distributed configurations, see the System Administration Guide for your GemStone server.

GemStone User

(Required) Your GemStone username, such as DataCurator.

GemStone Password

(Required) Your GemStone password.

Gem Service

The default is gemnetobject, which is not shown; if you are running with the default NetLDI on the same machine as the Stone, you may leave this unchanged.

Otherwise, include the appropriate information in NRS format. For example, with the Stone example above, you would specify this NRS string for the Gem Service:


Host User

The username for your account on this machine.

Host authentication may be omitted if you are using another method of network authentication, such as running the NetLDI in guest mode. See the System Administration Guide for your GemStone server for more information on the options.

Host Password

The password for your unix account, if Host authentication is required.

Transaction Mode

One of the following:

Auto — Places your session in a GemStone transaction and starts a new one each time you commit or abort.

Manual — You must explicitly begin transactions before making changes that you want to commit.

3. Click Ok to log in

When the session parameters are correct, click Ok.

A successful login results in the event being recorded in the Launcher’s Text Pane, which serves as a transcript. Additional buttons are activated, and the Login button becomes Logout.

After you have successfully logged in to the GemStone server, you have verified that your GemBuilder installation is correct.

If the login attempt did not complete or if login fails, the console will contain log messages with java error details.

If this is not sufficient to determine the problem, you can configure more complete error messages by setting full logging. To do this, execute:

prompt>  java com.gemstone.gbjgci.GbjGciPreferences set GBJ.LogLevel ALL

On Windows, running with Administrator privileges may be needed to allow registry update.

For more information on login parameters and on using the GBJ tools available from the GBJ Launcher, see the GemBuilder for Java Programming Guide and the GemBuilder for Java Tools Guide.