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> input $GBJ/server/install.gs
- topaz 1> 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> input $GBJ/server/GbjGciInterface.gs
- topaz 1> 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.