Skip navigation links

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

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:

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

In GbjObject:

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:

Environment Configuration

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

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

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: Thu Aug 6 10:10:40 PDT 2015
Skip navigation links