====================================
GemBuilder for Java 3.2.1 README.txt
====================================

GemBuilder for Java (GBJ) (C) is the property of GemTalk Systems LLC.
It may only be used in conjunction with either the GemStone/S or GemStone/64
server products and is subject to the same licensing restrictions as these 
products, as well as GBJ specific licencing. Refer to the licensing
documentation included with these products for further details.


============
Installation
============

Follow these steps to install GBJ 3.2.1:


Uncompress Delivery File
------------------------

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

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

* README.txt          -- this file.

* gbj321.jar          -- Java JAR file containing GBJ packages/classes that use the 
                         thread-safe GCI library. This jar supports multiple GemStone server 
                         sessions in a single Java VM.

* gbjopensrc321.jar   -- Java JAR file containing open source kunststoff graphic widgets used by 
                         the GBJ toolsi, for use with gbj321.jar,

* gbjLnk321.jar       -- Java JAR file containing GBJ packages/classes that use the linked GCI 
                         library. This jar supports a single GemStone server session per Java VM, 
                         and provides faster tranfer rates between Java objects and server objects.

* gbjsource321.jar    -- Contains .java files corresponding to gbj321.jar, for use in debugging as 
                         arg to jdb -sourcepath.

* gbjLnksource321.jar -- Contains .java files corresponding to gbjLnk321.jar, for use in debugging 
                        as arg to jdb -sourcepath.

* /doc                -- GBJ documentation, in javadocs HTML format

* /docLnk             -- GBJ documentation for the linked interface, in javadocs HTML format

* /server             -- GemStone Smalltalk source files and the install.gs that installs them.


Environment Configuration
-------------------------

* Set $GBJ to point to your GBJ 3.2.1 top-level directory, the one created by unzip of the 
  distribution. This is required for Smalltalk code filein.

* Note that GBJ 3.2.1 requires the use of Java 8 or later.
  Configure $CLASSPATH to include the Java 8 JDK lib directory
  Configure $PATH to include the Java 8 bin directory (for javac, java, etc)

* Configure $CLASSPATH to include $GBJ/gbj321.jar, or if using linked GBJ, $GBJ/gbjLnk321.jar

* If you're using the GBJ tools (such as GbjLauncher):
    Configure $CLASSPATH to include $GBJ/gbjopensrc321.jar

* Configure CLASSPATH to include the apache jar file commons-math-3.6.1.jar
  (see https://commons.apache.org/proper/commons-math/download_math.cgi to download the jar file)

You may also provide the CLASSPATH using -cp, e.g.
   java -cp $GBJ/gbj321.jar:$GBJ/gbjopensrc321.jar:$JDK/apache/3.6.1/commons-math3-3.6.1/commons-math3-3.6.1.jar 

* If debugging with jdb or other debugger the argument to -sourcepath should include gbjsource321.jar

* Configure access to the GS64 server shared libraries. This can be done in two ways:

   (1) Defining $GEMSTONE to point to a directory containing version.txt and the $GEMSTONE/lib 
       directory with the server shared libraries. In this case, In this case, the libgbjts or 
       libgbjlnk library is loaded directly from $GEMSTONE/lib, ignoring LD_LIBRARY_PATH and 
       ignoring any -Djava.library.path.

   (2) On the java command line, include the option -Dgemstone.version, for example 
       -Dgemstone.version=3.7.2.
       In this case, libgbjts or libgbjlnk will be loaded using java.library.path of the Java VM.
       If $GEMSTONE is also defined, the versions numbers must agree.

* if $GEMSTONE is not defined, the java library search path must be set, which can be done in two ways:

   (1) define $LD_LIBRARY_PATH to include a directory containing the server shared libraries. 

   (2) On the java command line, use -Djava.library.path=<one or more colon separated dirs>.
       In this case, the value of LD_LIBRARY_PATH is ignored.


Smalltalk Code Filein
---------------------

* From a writable directory, login a topaz session as SystemUser and filein $GBJ/server/install.gs


Example Test Application
------------------------

*  NOTE: /doc includes a simple Test.java program that can be used to confirm 
   configuration/setup is correct and for initial experiments with GBJ:
   $GBJ/doc/Test.java
   
*  Edit Test application to use appropriate stonename / username / password.

*  Compile Test application:
   unix> javac Test.java

*  Run GBJ application:
   unix> java Test


Example GUI Application
-----------------------

*  GBJ includes a simple GUI application similar to GBS.  Run using:
   java com.gemstone.tools.GbjLauncher

==========================
Changes in GBJ 3.2.1
==========================

Added support for GBJ clients on Windows, tested on Windows 11 .

GBJ 3.2.1 requires GemStone/S 64 Bit v3.7.5 server on Linux .
GBJ Clients may run on a Linux distribution supported by v3.7.5 server or on Windows 11.

==========================
Major Changes in GBJ 3.2.0
==========================

[NOTE: also repeated in javadocs $GBJBUILD/gbj/docs/index.html]

(paragraph added with GBJ 3.2.1 )
  GBJ 3.2.0 is supported with GemStone/S 64 Bit v3.7.2 through v3.7.4, with client and server
  both on Linux.

GBJ 3.2.0 is now provided with two separate interfaces; in addition to the RPC interface, which now uses 
the thread-safe GCI, support for a single linked GBJ session is provided using the classic GCI.  There are
a separate set of .jar files for each interface.

Use of the thread-safe GCI allows robust support for multiple sessions.
The linked interface permits a single session, when optimized performance is needed.

GBJ 3.2.0  provides enhanced and/or extended direct java/GS class mapping support
for a number of classes, including:

GemStone Server Class  Java Class       
-------------------    ---------------- 
LargeInteger           BigInteger
SmallDouble            double
Float                  double
SmallScaledDecimal     BigDecimal
ScaledDecimal          BigDecimal
DecimalFloat           BigDecimalFloat *
SmallFraction          BigFraction  **
Fraction               BigFraction  **
SmallDate              LocalDate          
SmallTime              LocalTime
GbjLocalDateTime*      LocalDateTime     (GbjLocalDateTime is a subclass of DateAndTime)  *
GbjZonedDateTime*      ZonedDateTime     (GbjZonedDateTime ia a subclass of DateAndTime)  *
SmallDateAndTime       OffsetDateTime
DateAndTime            OffsetDateTime
GbjInstant*            Instant
GbjUtilDate            Date  

*   = New java or GS class created to make mapping cleaner
**  = Java class included from apache library

Details on new java/GS class mappings

New java class BigDecimalFloat (a subclass of BigDecimal) created to
distinquish between [Small]ScaledDecimals and DecimalFloats.

To support the java BigFraction class, the Apache Commons Math 3.6.1 library
jar file commons-math-3.6.1.jar must be included in the $CLASSPATH.  This
library can be downloaded from the Apache Commons site at:

https://commons.apache.org/proper/commons-math/download_math.cgi
https://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/index.html

instances of Java class Calendar  are mapped to instances of DateTime .

Appropriate GbjObject methods to generate a new java instance of the appropriate
class have been added, following the original convention of <className>Value( ).
For example, to generate a BigInteger, call method
<aGbjObject>.bigIntegerValue( ).

Other bug fixes:

46427  Better handling of Utf8, Unicode7/16/32 instances
51112  GBJ does not handle codepoints in range 16r100000  to  16r10FFFF
48988  Better Java-side mapping support for various GemStone classes
49413  GbjGciInterface sendMsg conflicts with GBJ poller in server 3.6 and greater
49019  Use GciTs in GBJ for multi-session support
46531: Calling GbjLauncher from a java program had windowing problems
46532: GBJ library build information now printed during startup
46551: GbjObject.stringValue() printed wrong value on LargeIntegers
46816: Error message for "$GEMSTONE/version.txt not found" was incorrect
47078: Error in javadocs for GbjGciInterface.initialize()
47084: Enumeration over large collections could fail with ClassCastException
47289: Could get out of range error in getObjs() on GbjIterators
48138: Printout of large oop numbers in GbjObject.asString() can go negative
50994: GSCI stat library initialization error
50996: Corrupted GS Strings or Java strings with codepoints between 128 and 255 


==========================
Major Changes in GBJ 3.1.3
==========================

GBJ 3.1.3 includes several bug fixes and
restores support for GS/S 32-bit servers.  Customers on GS/S 32-bit
can request the required libgbjgci library via GemTalk Technical Support.
For GS/64, all future server releases will include the appropriate 
libgbjgci library as part of $GEMSTONE/lib (%GEMSTONE%/bin on Windows).

Because this is a new GBJ release, existing GS server products will not have
the 3.1.3 libgbjgci library immediately available.  Customers may contact
GemTalk Technical Support for a new libgbjgci library for GS/32 6.7 and 
GS/64 versions 3.2.15 and 3.3.1.

New features:

When attempting to return back an integer from the server using 
GbjObject.longValue(), if the integer is too large to fit in a java long type,
GBJ now triggers a java.lang.ArithmeticException.  If this occurs, users can
call new method GbjObject.bigIntegerValue() to return back a 
java.math.BigInteger (part of fix to 46283).


Other bug fixes:

30012:  GBJ could corrupt Strings containing non-ASCII characters
        (codepoint > 127).

46283:  Returning back instances of LargeInteger from the server would cause
        the java client to fail with a java.lang.ClassCastException.

46368:  Problems with GBJ library loading can cause problems using
        GbjGciPreferences.

Limitations:

Oracle does not provide a 32-bit version of java and the JDK for Solaris
platforms (sparc.Solaris and i386.Solaris).  Attempts to run GBJ on GS/32 using
64-bit java will trigger a "wrong ELF class: ELFCLASS32" error (bug 46359)




==========================
Major Changes in GBJ 3.1.2
==========================

Built to support the new GS/64 3.3 server release.

GBJ is now built using JDK version 1.8.0.  If you still need to use an earlier
version of Java, please contact GemTalk Technical Support (45246).

GBJ Android test application GbjTest is now built using the new
Android Studio IDE.  Refer to the file README.android.txt for more info
(45459). 

Enhanced support for object change notification (44674).  See documentation
for details.

Enhanced support for client forwarders (45770, 45749).  See documentation
for details.

Various bugfixes:

44705: Improved formatting of GbjGciException error messages
44659: Using monitorSessionSignals triggers "GBJ classes not loaded" error
44646: Using monitorChangedObjects can trigger GCI 2203 error
44618: registerStub( ) triggers "Object table put on oop zero" error
44577: Android getObjs( ) can trigger "local reference table overflow" error
44576: Android GbjTest app breaks when phone orientation changes
44523: Android GbjTest project broken on newer versions of Eclipse/ADT


==========================
Major Changes in GBJ 3.1.1
==========================

Built to support the new GS/64 3.2 server release.

New for GBJ 3.1.1 is support for development of Android applications using the
Android SDK.  This release includes the file GbjAndroid.zip containing Android
SDK files needed for building a simple example Android app that can login to 
a GemStone repository and execute simple GemStone Smalltalk commands.  
GbjTest can act as an template for your own GBJ Android applications.

See the README.android.txt for more details.

Various bugfixes:

43981:  Now compiled using JDK 1.7.
43949:  Fixed various problems with GBJ graphic interface GbjLauncher.
43387:  Fixed problem with finding GBJ stats library due to name change.
42788:  Improved diagnostic information provided on GBJ library load problems.
41890:  Fixed GBJ library load problem on AIX under JDK 1.6



==========================
Major Changes in GBJ 3.1
==========================

New package GbjStats which provides various levels of support for
accessing shared page cache statistics from either GBJ application code,
java JMX monitoring applications, or the VMware Hyperic monitoring tool.

GbjGciInterface/GbjGciSession/GbjSession initialize methods have a new 
maxSessions parameter used to determine size of internal allocated 
structures for holding session state information.

New method in GbjSession: setupExceptionHandler(), which provides a
way for applications to define java code to act as exception handlers
for various GemStone asynchronous errors, such as SigAbort and object
change notification.

Various bugfixes to 3.0:

40656: Gem-to-gem signals were sometimes lost.
40657: Improvements to login performance.
40951: GbjGemStoneErrors obsolete.
41734: GS to client java class mapping broken.
41755: Asynchronous signal processing can be delayed in "quiet" sessions.
41757: isLogged() can report true if session is terminated/killed.
41796: Excessive blocking between multiple GbjSessions
42081: Finalization of incomplete GbjGicObjects could crash gem.


==========================
Major Changes in GBJ 3.0
==========================


New in GBJ30 is the package GbjGci, which replaces the original transport
layer using the gem broker and object marshalling scheme with java JNI
code calling the GemBuilder/C Interface (GCI) used in the GBS product.

The redesign offers 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.  See 
the package documentation for details.

The GbjGci package includes classes GbjGciObject and GbjGciSession which 
are analogous to the original GBJ package variants GbjObject and GbjSession,
and the core functionality of these classes have been moved to these GbjGci
versions.  GbjObject and GbjSession now extend the GbjGci versions.

Support for the GCI interface plus the new features has required some
changes to classes in the GBJ package, especially GbjObject and GbjSession.
These changes are documented in the respective class documentation pages.
Also, a number of GBJ classes originally needed to support the original
object marshalling scheme are no longer needed and have been removed
from the product.

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.

Code for the GCI library interface is contained in a shared library
called libgbjgci30.so (gbjgci30.dll for Windows).  This library is
included with newer versions of the GemStone/S and GemStone/64 products
in the $GEMSTONE/lib directory.  Customers using older versions can
contact GemStone Technical Support for a version compatible with their
GemStone server product.


Further details on changes to the various GBj packages are summarized
below.


===========================
PACKAGE com.gemstone.gbjgci
===========================

The GbjGci package provides a new low-level interface to the GS/S GBJ
product as of GBJ30, replacing the original transport layer using the gem
broker and object marshalling scheme with code calling the GemBuilder/C 
Interface (GCI), used in the GBS product.  The redesign offers 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.


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



GbjGci Classes
==============

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
and processes them as appropriate to pass on to 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.

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.


=========================
PACKAGE: com.gemstone.gbj
=========================

Changes in GBJ 3.0 in the com.gemstone.gbj package include:



Logging
-------

Prior to GBJ30, a number of GBJ classes included the private field 
logger, which held an instance of com.gemstone.org.apache.log4j.logger
for use in tracking diagnostic messages.  This field has been made static 
and replaced with java.util.logging.Logger.


Gem-To-Gem Signalling
---------------------

Prior to GBJ30, activation of the gem-to-gem signalling mechanism was
done by executing the GS smalltalk code:

   System enableSignaledGemStoneSessionError

With GBJ30, activation is performed in java by setting the GbjSession public
boolean parameter monitorSessionSignals to true:

   MySession.monitorSessionSignals = true;


Obsolete Classes
----------------

The following classes have become obsolete and have been removed from
the GBJ package:

* GbjExternalizable
* GbjObjectInputStream
* GbjObjectOutputStream
* GbxDelay
* GbxInput
* GbxOutput
* GbxSemaphore
* GbxTransport
* GbxUtl
* UnicodeFormatter


Changed Classes
---------------

The following classes have had changes made to their API.  Developers
should review their applications and fix as necessary.


* GbjObject

  Extensive changes: see class documentation for details.

* GbjSession

  Extensive changes: see class documentation for details.

* GbjParameters

  A number of constants and fields have been deprecated.
  See class documentation for details.

* GbjKernelObjects

  Limited to just the most frequently used objects. 
  See class documentation for details.

* GbjIterator

  Constructor GbjIterator(GbjObject[] initialCache) removed.
  Constructor GbjIterator(GbjObject onCollection, long startingIdx) added.
  See class documentation for details.

* GbxLogger

  No longer using com.gemstone.org.apache.log4j logger.
  Replaced with java.util.logging.Logger. 


Deprecated Classes
------------------

The following classes are no longer necessary due to changes in the 
design of GBJ, but are kept available to minimize customer impact:


* DoubleByteString

  Java strings are now automatically converted to GS String or
  DoubleByteStrings as necessary.  


===========================
PACKAGE: com.gemstone.tools
===========================

This package is largely unchanged in the GBJ 3.0 release.  The only
user-noticable change is in the GbjLoginDialog window, where the following
obsolete GbjParameter fields have been removed:

* GemBroker Machine
* GemBroker Port
* Timeout
* Connect Timeout


======================
3.0 vs 2.X Differences
======================

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:

*  GbjGciForwarder
   Provides an interface for passing messages from GS Smalltalk objects 
   to client java objects.

*  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/GbjGciForwarder.gs
*  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/libgbjgci30.so (gbjgci30.dll for Windows).  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.


Using GBJ 3.0
-------------

Note that the new GBJ 3.0 design does not use a gem broker, so do not
attempt to start a GBJ Broker.

Also note that as documented earlier, there are many API changes.  
You will need to review your existing GBJ applications and update them
as appropriate.


