# Package com.gemstone.gbjgci

The gbjgci package provides a low-level interface layer for the GBJ package, using the GemBuilder/C Interface (GCI) and the Java JNI.

See: Description

- Class Summary
  Class | Description
  --- | ---
  GbjGciCacheStats | GbjGciCacheStats provides access to shared page cache statistics returned from GbjGciInterface calls to GCSI (GCI Cache Statistics Interface) functions.
  GbjGciInterface | GbjGciInterface provides the low-level interface to the GemStone GCI.
  GbjGciLogFormatter | GbjGciLogFormatter provides formatting for logging messages used within GBJ.
  GbjGciObject | GbjGciObject is the primary class for representing GS Objects in the GbjGci package.
  GbjGciPreferences | GbjGciPreferences uses java Preferences to determine debug trace logging levels for the various Gbj/GbjGci modules.
  GbjGciReport | GbjGciReport provides the low-level GS Object representation that is used in communication with the GS/S GCI layer.
  GbjGciSession | GbjGciSessions represent GemStone sessions.

- Exception Summary
  Exception | Description
  --- | ---
  GbjGciException | GbjGciException provides the mechanism for passing errors occuring in the GemStone GCI and JNI layers up to java.

## Package com.gemstone.gbjgci Description

The gbjgci package provides a low-level interface layer for the GBJ package, using the GemBuilder/C Interface (GCI) and the Java JNI. This package replaces the original pre-3.0 transport layer using the gem broker and object marshalling scheme with GCI calls, providing significantly improved object transport performance between GemStone and Java, plus support for some new features, including automatic notification of changes to server objects via the java Observable/Observer API, and automated export set management.

The GbjGci package can also be used stand-alone as a "GBJ Lite", providing sufficient functionality for basic java/GS applications with a smaller code footprint and less overhead than that required by the full GBJ package.

## New in GBJ 3.1

GbjGciSession.initialize() includes new argument maxSessions to specify the maximum number of sessions that can be running on a particular shared page cache. This should be set to the same value used in the GemStone configuration file parameter STN_MAX_SESSIONS.

A new class GbjGciCacheStats provides low-level access to shared page cache statistics.

A number of new methods to support shared page cache statistics access have been provided on GbjGciInterface, using the low-level GCI GCSI interface. These new methods include:

- static void GCSIinitialize( )
- static String[][] GCSIstatNames( )
- static int GCSIattach(String stoneName)
- static void GCSIdetach( )
- static int GCSIsampleStats(long[] processIds)
- static GbjGciCacheStats GCSIgetStats(long pid, GbjGciCacheStats stats)
- static GbjGciCacheStats GCSIgetStats(int index)

Refer to the javadoc documentation for these methods for details on usage.

Note that these GCSI functions provide a very low primitive level of support for shared page cache statistics. For a more application-friendly level, use class GbjCacheStats and extended versions found in package com.gemstone.gbjstats.

## New In GBJ 3.0: Major New Features

### Simpler design, improved transport performance

Removing the classes and code necessary to support the gem broker mechanism and socket-based object marshalling from GBJ provides significant performance improvements and easier system management (no broker to worry about).

### Automated Export Set Management

Objects brought over to the java client are automatically added to the export set, and removed when java finalizes the object. The application no longer needs to explicitly track this.

### Object Change Synchronization

GbjObjects now inherits from java class Observable, allowing the developer to define Observer objects that can be notified when the GS object represented by a given GbjObject is changed due to transactional activity or GS/S smalltalk code execution.

### Explicit Object Canonicalization

Objects brought over for a particular session are explicitly canonicalized, so there is only ever a single GbjObject for a given oop. This was necessary to support a number of the new features listed above.

## Major Limitation

The original GBJ design allowed for the possibility of different GbjSessions to connect to stones with different oop formats, for example, a GS/S 32-bit session along with a GS/64 64-bit session. The GCI-based design constrains all GbjSessions within this java program to belong to a single product type.

## The GbjGci Package

A number of new classes are defined that provide the connection between the original GBJ package and the GCI C layer. These classes are named with the prefix GbjGci*. For example:

- GbjGciInterface
- GbjGciReport
- GbjGciObject
- GbjGciSession
- GbjGciPreferences

A number of classes in the GBJ package now inherit from these classes. For example:

GbjSession extends GbjGciSession

GbjObject extends GbjGciObject extends GbjGciReport

GbjException doesn't extend GbjGciException, but takes GbjGciExceptions as arguments and processes them as appropriate for existing GBJ code.

The redesign of GBJ to use the GbjGci package has required some changes to the GBJ API, especially for GbjSession, GbjObject constructors, and the errors thrown under various anomalous conditions. These will be documented in the appropriate GBJ class documentation files.

## GBJ "Lite"

For certain GBJ applications requiring limited GBJ functionality, it's possible to design these using only GbjGci classes and skip the use of the higher-level Gbj classes. In these cases, the application would use GbjGciSession instead of GbjSession, GbjGciObject instead of GbjObject, and GbjGciException instead of GbjException. This is possible if the application does not require the additional functionality provided by the higher-level Gbj classes. This additional functionality includes:

### In GbjSession:

- Session observers
- Client forwarders
- Gem-to-gem signalling
- Java-to-GemStone class mapping
- Convienience methods for transaction management

### In GbjObject:

- Many convienience methods for executing server code

Refer to the additional documentation in this section to determine if the funictionality provided is adequate for your application.

## GbjGci Classes

### GbjGciInterface

Provides connectivity between java and the C-based GCI code, using the java JNI mechanism. The public API provides access to private lower level JNI methods and smooths out the flow object object data and exception handling.

### GbjGciReport

Represents basic object information being transfered to/from the GCI layer. To provide support for object change notification, this class extends java class Observable.

### GbjGciObject

A slightly higher object representation that indicates which session is associated with a given object. Extends GbjGciReport. The original GbjObject class now in turn extends GbjGciObject, and some of its original functionality has been moved to this layer.

### GbjGciSession

Represents basic session information. Includes support for GbjGciObject canonicalization, java/GbjGciObject class mapping, export set management, and changed object updating. The original GbjSession class now in turn extends GbjGciSession, and some of its original functionality has been moved to this layer.

## Installation

Follow these steps to install GBJ 3.1:

### Uncompress Delivery File

GBJ is usually delivered as a single zip/tar file. When uncompressed, a number of files and subdirectories are generated. Setup an appropriate top-level directory to hold these and unzip/untar the delivery file.

The top-level directory now contains several files and directories:

- README.txt
  Overview file documenting 3.1 changes and installation procedures
- PACKING.txt
  A list of all GBJ files/directories
- gbj312.jar
  Java JAR file containing GBJ packages/classes
- /doc
  GBJ documentation, in HTML and javadocs format
- /server
  GemStone Smalltalk source files

### Environment Configuration

- Set $GBJ to point to your GBJ 312 top-level directory.
  Needed for Smalltalk code filein
- Configure $CLASSPATH to include $GBJ/gbj312.jar.
  Needed to find the gbj312.jar file
- Configure $LD_LIBRARY_PATH to include $GEMSTONE/lib
  Needed to find the libgbjgci shared library

### Smalltalk Code Filein

Due to the changes in GBJ architecture to use the GbjGci shared library, the amount of GemStone Smalltalk code needed to support GBJ is significantly reduced. There are only 3 needed Smalltalk classes:

- GbjGciInterface
  Provides an interface between the java GbjGci package and GS Smalltalk
- GbjToolsInterface
  Provides an interface between the java GBJ tools package and GS Smalltalk
- GbjFileinReader
  Used by GbjToolsInterface to handle file read operations

New names were used for these classes so that they won't conflict with earlier versions of GBJ. This allows you to switch back-and-forth between GBJ 3.0 and earlier versions of GBJ, or to even run both in parallel.

Separate *.gs files are provided for each of these GS Smalltalk classes in directory /server, plus the file-in script install.gs which files in all three. To load these:

- Login a topaz session as SystemUser
- topaz 1@gt input $GBJ/server/install.gs
- topaz 1@gt commit

If you are not planning on using the GBJ tools graphical interface, you can omit the GbjToolsInterface and GbjFileinReader classes by doing the following:

- Login a topaz session as SystemUser
- topaz 1@gt input $GBJ/server/GbjGciInterface.gs
- topaz 1@gt commit

### GbjGci Shared Library

Newer versions of GemStone/S and GemStone/64 are now delivered with the GCI-based GbjGci shared library already included as $GEMSTONE/lib/libgbjgci312.so. Check your $GEMSTONE installation to see if this file is included. If not, contact GemStone Technical Support to request a copy. Please include your platform (Solaris, HP, AIX, Linux, Windows), product (GemStone/S or GemStone/64) and product version number with your request.

Version:
  3.1

  Last modified: Mon Jul 13 15:55:09 PDT 2020