# Package com.gemstone.gbj

The GBJ package provides an application programming interface (API) for developing a Java client application that can communicate with a GemStone/S server.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  GbjClientAdapter | This interface must be implemented by objects that will forward messages from a GemStone server to a client object
  GbjObservable | This interfaces allows objects implementing GbjObserver to monitor an object such as a GbjSession
  GbjObserver | This interface allows objects to monitor events in GbjObservables such as GbjSession instances

- Class Summary
  Class | Description
  --- | ---
  BigDecimalFloat | Instances of this class represent GS DecimalFloat objects.
  DoubleByteString | This is a deprecated class .
  GbjCollection | This subclass of GbjObject represents server instances of Collection or one of its subclasses, excluding subclasses of the server class AbstractDictionary.
  GbjGemStoneErrors | This class provides variables for all of the error numbers associated with GbjExceptions that have category GemStoneError.
  GbjIterator | Instances of this class iterate over collections in the GemStone server.
  GbjKernelObjects | Instance of this class hold pre-defined stubs for many GemStone server objects.
  GbjObject | Instances of this class represent server objects in a GemStone server.
  GbjParameters | Instances of this class are used to specify the information needed to configure a GemStone session.
  GbjPoller | GbjPoller provides support for a polling thread that keeps track of asynchronous errors and triggers an appropriate method when they occur.
  GbjSession | A GbjSession is used to communicate with a GemStone server process.
  GbxConstants | Constants used internally by GBJ

- Exception Summary
  Exception | Description
  --- | ---
  GbjAbortingException | This class represents a GemStone server exception that forced a rollback of the current transaction.
  GbjCompilerException | This class represents a GemStone server compilation exception.
  GbjEventException | This class represents an event that has occurred in the server.
  GbjException | This class represents a GemStone server exception.
  GbjFatalException | This class represents a GemStone server exception that requires termination of the session.
  GbjInternalException | This class represents an unexpected GemStone server exception that could not be properly handled by GemStone.
  GbjNonKernelException | This class represents an exception that was signaled with an error category other than GemStoneError in the server.
  GbjRuntimeException | This class represents a GemStone server runtime exception, such as a key not being found in a dictionary, division by zero, message not understood, and so on.

## Package com.gemstone.gbj Description

The GBJ package provides an application programming interface (API) for developing a Java client application that can communicate with a GemStone/S server.

## New in GBJ 3.1.2: Client Forwarders

The use of client forwarders for calling java code from GS smalltalk has been cleaned up. Because of differences in method calling conventions and arguments types between java and smalltalk, a few rules need to be remembered:

### Setting up a Client Forwarder

Use the GbjSession method clientObject to setup a reference to the desired java object in GS Smalltalk. See the example below for details. You can then use either the GbjSession methods execute() or perform() or embed an appropriate call within GS smalltalk code to trigger the client forwarder and execute the java method on the java client.

### Method Naming Conventions

Because of the differences in syntax for method names between java and smalltalk, use these rules when calling a java method from smalltalk:

In the following examples, "cf" indicates the client forwarder used in smalltalk.

For methods with no arguments, use the same name. For example, to call "next( )" in java, use "cf next".

For methods with one argument, add a ":" to the end of the java name. For example, to call "println(aString)" in java, use "cf println: aString".

For methods with more than one argument, add a ":" to the end of the java name as above, and then for each subsequent argument include an additional "xxx:" separator ending in ":" -- the characters are not significant. For example, to call "doComplexTask(x,y,z)" in java, use "cf doComplexTask: x arg2: y arg3: z" (note that "arg2:" and "arg3:" are not important, you could have just as easily used "y:" and "z:").

### Argument Types

Arguments passed via client forwarders are limited to these classes:

- Boolean
- Long
- Double
- String

Note that when defining your java methods, arguments *must* be one of these immutable class wrapper classes, *not* a primitive Java data type. For example, use Boolean and not boolean. Because of this limitation you may not be able to directly call a given java method, but may need to define a wrapper method around it that complies with these argument limitations.

### Return Values

Besides void, java methods can have return values that include the same types as for arguments, but they can also be primitive:

- boolean / Boolean
- long / Long
- double / Double
- String

### Example

As an example, say you wanted to setup a client forwarder to java object System.out so you could print directly to the java output file. The following code example sets up the client forwarder in UserGlobals so it's easy to reference later, and then demonstrates two approaches for triggering the client forwarder:

    GbjSession s;  // already connected
    GbjObject sysout = s.clientObject(System.out);
    GbjObject userGlobals = s.execute("UserGlobals");
    GbjObject[] args = new GbjObject[2];
    args[0] = s.execute("#sysout");
    args[1] = sysout;
    s.perform(userGlobals, "at:put:", args, 2);
    // Now we can use the UserGlobals reference sysout to act as a client forwarder
    // By using GS smalltalk code: "sysout println: 'desired string'".

    // calling System.out.println("Now is the time..");
    s.execute("sysout println: 'Now is the time..'");

    // another way
    args[0] = new GbjObject("Now is the time..", s);
    s.perform(sysout, "println:", args, 1);

## New in GBJ 3.1

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

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.

## New 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 that 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.

## 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. Refer to the package documentation for GbjGci to dtermine if this would work for your application.

## Synchronizing changes between java and GS objects

You can synchronize changes between a java object and it's GS equivalent, similar to the use of replicates in GBS (although not quite as transparent). To do this you first must define your java class as a subclass of GbjObject. Use GbjSession methods registerStub() or registerStaticStub() to provide GS to java class mapping so that java-side proxies are instances of the correct java class. In your java subclass, override the method updateClient() to perform appropriate actions to update the state of the java object based on the data in the GS object, and for any java methods that change fields in the java object, include code that updates GS as appropriate. See the next two sections for details.

### Synchronizing java changes back to GS

In any java code that makes changes to the object, make equivalent calls to appropriate GbjObject methods. Useful methods for this purpose are:

- putByte()
- putBytes()
- putObj()
- putObjs()
- putNamedObj()
- putNamedObjs()
- perform()
- sendMsg()

For example, say you have a GS Class Person with instvar name and associated method #setName: which sets this instvar. On the java side, you have the class Person with field name. You could then define java method setName():

    public void setName(String newName) {
       name = newName;
       sendMsg("setName:", newName);
    }

### Synchronizing GS changes back to java

First, enable object change notification by setting the GbjGciSession flag monitorChangedObjects to true. There are two major approaches to handling replication of GS changes back to java:

- Define subclasses of Gbj[Gci]Object that override updateClient()
- Use the java Observer API to add observers to appropriate Gbj[Gci]Objects

Using our earlier example for class Person and instvar/field name, on java class Person, updateClient() might look like:

    protected void updateClient() {
       ...
       name = sendMsg("name");
       ...
    }

Refer to the section on Object Change Synchronization in the javadocs for GbjGciObject for more details.

## GBJ30 Changes

### 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
- GbxClientInterface
- GbxDelay
- GbxInput
- GbxOutput
- GbxSemaphore
- GbxTransport
- GbxUtl
- GbxLogger
- 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.

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

Version:
  3.1

  Last modified: Mon Jul 13 16:40:02 PDT 2020