Skip navigation links

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

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

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

Changed Classes

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

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:
Version:
3.1
Last modified: Tue Oct 20 16:38:53 PDT 2015
Skip navigation links