1. Installing GemBuilder for Java

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

This version of GemBuilder for Java supports only GemStone/S 64 Bit 3.7.2 and later, with server and clients on Linux only. 32-bit GemStone/S is not supported by GBJ 3.2.

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

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 or new GemStone repository, but each Java client must be configured for login.

This version of GBJ is provided with two environments:

There are differences between the low level packages com.gemstone.gbjgci between the RPC and linked interfaces. However, using the com.gemstone.gbj package (which is recommended), and provided the application does not use unavailable features, the resulting java application will run correctly in both environments, provided that the correct login parameters are used.

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

GemBuilder for Java version 3.2 is compatible with GemStone/S 64 Bit versions 3.7.2 only, on 64-bit Linux only.

Server keyfile

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 v3.2 clients are supported on 64-bit Linux only.

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/S 64 Bit server.

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 the GemBuilder for Java distribution

The following instructions describe installing GemBuilder for Java v3.2 server and java components onto your system.

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

We recommend installing GBJ at the same level as the GemStone server installation directory. You will need about 9 MB of free disk space.

2. GemBuilder for Java is provided as a zipped archive file, GemBuilderJava3.2.0.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.2.0. In the instructions that follow, we refer to this directory as gbj_directory.

gbj_directory includes the following:

version.txt

README.txt

gbj320.jar - the Java class library for the RPC/thread-safe environment.

gbjopensrc320.jar - class library with open source libraries used by the RPC/thread-safe GBJ tools.

gbjsource320.jar - additional class library to support debugging, used by the RPC/thread-safe environment.

gbjLnk320.jar - the Java class library for the linked environment.

gbjLnksource320.jar - additional class library to support debugging, for use with the linked environment.

doc - directory containing documentation for the RPC/thread-safe GBJ environment

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

docLnk - directory containing documentation for the linked GBJ environment:

api - directory containing support files for the online javadocs documentation for the linked environment.

server - directory containing:

GbjFileinReader.gs
GbjGciInterface.gs
GbjHypericServerTemplate.xml
GbjHypericServiceTemplate.xml
GbjInstant.gs 
GbjJmxCommandsTemplate.dat
GbjJmxSystemStatsTemplate.dat
GbjLocalDateTime.gs
GbjSupport.gs
GbjToolsInterface.gs
GbjUtilDate.gs
GbjZonedDateTime.gs
install.gs

Installing GBJ into your Repository

GemBuilder for Java has server components that must be installed into your GemStone repository. This process is the same if you are installing into a new repository, or upgrading from a repository containing a previous version of GBJ.

Environment Setup

GemBuilder for Java version 3.2 requires several environment variables to be set prior to installation to a server repository.

1. The $GEMSTONE environment variable should be set to the GemStone server installation directory. This is described in the GemStone server documentation. For example: 

os$ export GEMSTONE=GS64InstallDir/GemStone64Bit3.7.2-x86_64.Linux

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

os$ export PATH=$GEMSTONE/bin:$PATH

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

os$ export GBJ=gbj_directory

Prepare for installation

Before installing GBJ into the server repository for the first time, or upgrading an existing GBJ installation, verify the installation in a pilot environment. The server installation commits automatically. If the installation fails, you should correct the problem and re-run the installation.

GBJ 3.2 installation will report an error if the TimeZone configured in the server repository does not match the TimeZone configured in the OS, in /etc/timezone.

Install GBJ into server repository

1. Installation writes a log file to the current working directory. You must cd to a working directory in which you have write permission.

2. Start topaz using the -l -i options, which starts a linked topaz that does not read a topaz initialization file.

3. Log in to the GemStone server as SystemUser.

4. Input the installation script, $GBJ/server/install.gs, which files in the server components. For example:

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

During the filein operation, output is directed to the file installGbj.out in the current directory.

The filein 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 installGbj.out 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 for RPC environment

Preliminaries

Ensure that your GemStone server has successfully installed GBJ, and that the Stone and NetLDI are running.

Required Files

1. JDK environment

You must have a java environment on the client.

2. Server shared libraries

If you are running the GBJ client on the same machine as the GemStone server, or if you install the GemStone server distribution on the client node, you may use this environment for the required server shared libraries.

Otherwise, you must have an directory accessible from the client, containing the required server shared libraries listed in Table 1 .

Table 1 Client Shared Libraries for GemStone/S 64 Bit v3.7.2

 

Linux

GBJ v3.2, RPC

libgbjts320-3.7.2-64.so

libgcits3.7.2-64.so

libkrb5-3.7.2-64.so

libssl-3.7.2-64.so
3. GBJ jar files

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

If the GBJ client is on a different machine, copy the following files to the client node:

gbj320.jar

gbjopensrc320.jar. (if you are using GbjTools)

You should also copy gbjInstallDir/docs/ to the client node. The javadocs provide important documentation for GBJ functions.

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

4. Third-party jar file

To support the java BigFraction class, the Apache Commons Math 3.6.1 library jar file commons-math-3.6.1.jar must be accessible.

This library can be downloaded from the Apache Commons site at:

https://commons.apache.org/proper/commons-math/download_math.cgi

Environment Setup

$PATH

The Java executable directory should be on your path.

$GEMSTONE

GemBuilder for Java version 3.2 does not require that $GEMSTONE be defined, provided that the server shared libraries are available and the server version can be determined.

If $GEMSTONE is defined, it must include the file version.txt, and the required shared libraries must be in $GEMSTONE/lib.

If $GEMSTONE is not defined, you must include -Dgemstone.version=3.7.2 on the java command line, and either define LD_LIBRARY_PATH or the java command line -Djava.library.path= argument, to include a directory containing the required server shared libraries as listed in Table 1 .

$LD_LIBRARY_PATH

GemBuilder for Java version 3.2 does not require that $LD_LIBRARY_PATH be defined.

If $GEMSTONE is defined, $LD_LIBRARY_PATH and -Djava.library.path= are ignored.

Otherwise, if $LD_LIBRARY_PATH is defined, it must include a directory containing the required server shared libraries as listed in Table 1 .

If neither $GEMSTONE nor $LD_LIBRARY_PATH are defined, you must include -Djava.library.path= on the java command line as well as -Dgemstone.version=3.7.2.

$CLASSPATH

You may specify the java CLASSPATH either by defining the environment variable $CLASSPATH, or using the java command line argument -cp.

The CLASSPATH must include the GBJ class library, gbj320.jar, and the third-party (Apache) .jar file commons-math3-3.6.1.jar. This contains Apache’s BigFraction class is used to support GemStone server Fractions.

If you are using the GbjTools, you will also need to include the open source library gbjopensrc320.jar, which contains the Kunststoff graphic support.

For example:

os$ export CLASSPATH= gbj_jar_dir/gbj320.jar:gbj_jar_dir/gbjopensrc320.jar:apacheInstallDir/3.6.1/commons-math3-3.6.1/commons-math3-3.6.1.jar

Testing RPC login using Test.java

The GBJ distribution includes a simple java application that allows you to test your GBJ configuration.

1. Copy Test.java to a writable directory.

Find or create a directory to hold your source and class files. These instructions will call this gbj_dev. 

os$ cp $GBJ/doc/Test.java gbj_dev
os$ chmod 755 gbj_dev/Test.java
2. Edit Test.java to specify the login parameters

Edit gbj_dev/Test.java to specify the appropriate Stone name and other login parameters.

To login to a remote Stone, add a line specifying the gem service:

p.gemnetName = "!@hostname!netldiName!gemnetobject";
3. Compile and execute

Ensure your $CLASSPATH includes the gbj_dev directory as well as the correct .jar files, and that $GEMSTONE is defined, as described in previous sections.

os$ javac Test.java
os$ java Test

Client setup for Linked environment

Preliminaries

Ensure that your GemStone server has successfully installed GBJ, and that the Stone and NetLDI (for remote configurations) are running.

Required Files

1. JDK environment

You must have java environment on the client.

2. Server shared libraries

If you are running the GBJ client on the same machine as the GemStone server, or if you install the GemStone server distribution on the client node, you may use this environment for the required server shared libraries.

If you are running on a machine remote from the Stone, you must have a full GemStone installation on the client node, since it will need to start a remote cache and page server; you must have a NetLDI running on the client as well as on the server.

3. GBJ jar files

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

If the GBJ client is on a different machine, copy the following file to the client node:

gbjLnk320.jar

You should also copy gbjInstallDir/docsLnk/ to the client node. The javadocs provide important documentation for GBJ functions.

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

4. Third-party jar file

To support the java BigFraction class, the Apache Commons Math 3.6.1 library jar file commons-math-3.6.1.jar must be accessible.

This library can be downloaded from the Apache Commons site at:

https://commons.apache.org/proper/commons-math/download_math.cgi

Environment Setup

$PATH

The Java executable directory should be on your path.

$GEMSTONE

In the linked environment, you must have $GEMSTONE defined to point to a full GemStone distribution installation.

$LD_LIBRARY_PATH

Since $GEMSTONE is defined, $LD_LIBRARY_PATH and -Djava.library.path= are ignored.

$CLASSPATH

You may specify the java CLASSPATH either by defining the environment variable $CLASSPATH, or using the java command line argument -cp.

The CLASSPATH must include the GBJ class library, gbjLnk320.jar, and the third-party (Apache) .jar file commons-math3-3.6.1.jar. This contains Apache’s BigFraction class is used to support GemStone server Fractions.

Additional Requirement

When using the linked environment, the default java stack size is insufficient. You should include the java argument to increase this value, e.g. -Xss2048k.

Testing linked login using Test.java

The GBJ distribution includes a simple java application that allows you to test your GBJ configuration.

1. Copy Test.java to a writable directory.

Find or create a directory to hold your source and class files. These instructions will call this gbj_dev. 

os$ cp $GBJ/doc/Test.java gbj_dev
os$ chmod 755 gbj_dev/Test.java
2. Edit Test.java to specify the login parameters

Edit gbj_dev/Test.java to specify the appropriate Stone name and other login parameters.

To login using the linked environment, you must add the line:

p.gemnetName = "gcilnkobj";
3. Compile and execute

Ensure your $CLASSPATH includes the gbj_dev directory as well as the correct .jar files, and that $GEMSTONE is defined, as described in the previous section.

os$ javac Test.java
os$ java Test

Logging into GemStone using the GBJ Launcher

The GBJ Launcher provides a simple GUI tool that allows you to specify the name and location of the GemStone server and the other parameters that control an RPC login.

You cannot login using the linked environment to the GbjLauncher.

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.

4. Invoke the GBJ Tools Launcher.

If you have defined $GEMSTONE and $CLASSPATH, you may open the Launcher simply using: 

os$ java com.gemstone.tools.GbjLauncher

com.gemstone.tools.GbjLauncher. contains the GBJ Launcher; 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

This GBJ Tools Launcher window:

5. 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

Parameter

Description

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:

!@denali!gemnetobject

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.
6. 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:

os$ java com.gemstone.gbjgci.GbjGciPreferences set GBJ.LogLevel ALL

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.