com.gemstone.gbj

## Class GbjSession

- java.lang.Object
- - com.gemstone.gbjgci.GbjGciSession
  - - com.gemstone.gbj.GbjSession

- All Implemented Interfaces:
    GbjObservable

      public class GbjSession
      extends GbjGciSession
      implements GbjObservable

  A GbjSession is used to communicate with a GemStone server process. It must be configured with a GbjParameters instance to be useful, and must be connected to a server peer with the connect() method. GbjSession maintains translation information for Java and GemStone as well as export sets and other low-level information. In this GBJ jar, a single instance of GbjSession is supported within a Java VM. Access to server state associated with a GbjSession is through static synchronized methods in com.gemstone.gbjgci.GbjGciInterface . Thus only one Java thread can be making calls to the server at a time.

  ## New in GBJ 3.2

  The method commit() was added.

  ### Deprecated Methods

  Methods that are still available but deprecated due to changes in design:
  - public GbjObject putInServer() putInServer
  Version:
    3.2

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `GbjKernelObjects` | `kernel` A collection of frequently accessed objects from the server Globals dictionary.
    `java.lang.RuntimeException` | `lastError` lastError is deprecated.
    `boolean` | `monitorSessionSignals` Flag used to control if session signals should be monitored
    `boolean` | `objChgNotify` Flag used to control if object change notification should be active
    `int` | `pollInterval` The polling interval used to check for asynchronous signals (sigAbort, gem-to-gem signals, changed objects).
    `java.lang.Object` | `userData` userData is for customer use.
    `static java.lang.String` | `version` The version of the interface

    - ### Fields inherited from class com.gemstone.gbjgci.GbjGciSession

      `gbjGciInterface, isDEBUG, monitorChangedObjects`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GbjSession()`
    `GbjSession(GbjParameters sessionParameters)` GbjSession() requires a sessionParameters object, which tells the session the host and port for the connection as well as the type of session requested

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `abortTransaction()` abortTransaction() rolls back the current transaction in the database.
    `void` | `addObserver(GbjObserver obs)` add an observer to the receiver
    `void` | `beginTransaction()` beginTransaction() starts a new transaction in the database.
    `void` | `checkConnected()` checkConnected() will throw a GbjException if the session is not in a connected state.
    `GbjObject` | `clientObject(java.lang.Object o)`
    `void` | `close()` close() closes the connection.
    `boolean` | `commit()` commit() commits the current transaction in the database.
    `boolean` | `commitAndReleaseLocks()` commitAndReleaseLocks() is like commitTransaction but any locks held are released if the commit succeeds.
    `boolean` | `commitTransaction()` Deprecated. use commit() for new code to ensure that conflicts signal a GbjException.
    `void` | `connect()` connect() is usually sent soon after instantiating a session to connect to the server .
    `GbjObject` | `doit(java.lang.String smalltalkCode)` doit() sends the given @param smalltalkCode string to the server for compilation and execution.
    `GbjObject` | `execute(java.lang.String smalltalkCode)` Execute smalltalk code on the server.
    `byte[]` | `getBytes(GbjObject obj, long startIndex, int numBytes)` Retrieve the designated bytes from this byte-based GS object.
    `java.lang.String` | `getName()` getName() will return an identifying description of a session.
    `GbjObject[]` | `getNamedObjs(GbjObject obj, long startIndex, int numOops)` Retrieve the designated GS objects from the named instvars for this GS object.
    `GbjObject[]` | `getObjs(GbjObject obj, long startIndex, int numOops)` Retrieve the designated GS objects from this indexable GS object
    `java.lang.String` | `getShortName()` getShortName() will return a short identifying description of a session.
    `java.lang.String` | `getTransactionMode()` getTransactionMode() returns a string describing the current transaction mode.
    `static void` | `initialize(boolean useLinked, java.lang.String appName, int bufSize, int preloadSize, int maxSessions)` Initializes the GBJ environment.
    `static void` | `initialize(boolean useLinked, java.lang.String appName, int bufSize, int preloadSize, int maxSessions, java.lang.Class objectClass)` Initializes the GBJ environment.
    `boolean` | `inTransaction()` Returns true if the GemStone server has started a transaction and false if not.
    `boolean` | `isAutomaticTransactionModeSet()` isAutomaticTransactionModeSet() will return true if the server is in automatic transaction mode and false if not.
    `boolean` | `isConnected()` isConnected indicates whether the session is able to communicate with its server.
    `void` | `notifyObservers(java.lang.String notificationMessage, java.lang.Object argument)` notify observers of a change
    `GbjObject` | `objectNamed(java.lang.String smalltalkObjectName)` objectNamed() is a name lookup service.
    `GbjObject` | `perform(GbjObject receiver, java.lang.String selector, GbjObject[] args, int argCount)` Perform a particular smalltalk method against a particular object.
    `java.lang.String` | `printit(java.lang.String smalltalkCode)` printit() is the same as doit(), but the message "printString" is sent to the result and the answer of this message is returned.
    `GbjObject` | `putInServer(java.lang.Object obj)` Deprecated. use GbjObject constructor
    `void` | `registerAdapter(java.lang.String className, GbjClientAdapter adapter)` registerAdapter specifies an object to be used in forwarding messages for the given Java class.
    `static void` | `registerStaticAdapter(java.lang.String className, GbjClientAdapter adapter)` registerStaticAdapter specifies an object to be used in forwarding messages for the given Java class.
    `static void` | `registerStaticStub(GbjObject stubInstance, java.lang.String gemstoneClassName)` registerStaticStub allows building of a GemStone@lt-@gtJava class correspondence at static initialization time.
    `void` | `registerStub(GbjObject stubInstance, GbjObject classStub)` registerStub allows building of a GemStone<->Java class correspondence at run time.
    `void` | `registerStub(GbjObject stubInstance, java.lang.String gemstoneClassName)` registerStub allows building of a GemStone@lt-@gtJava class correspondence at run time.
    `void` | `removeObserver(GbjObserver obs)` remove an observer
    `void` | `rollbackTransaction()` rollbackTransaction() rolls back the current transaction in the database.
    `void` | `setAutomaticTransactionMode()` setAutomaticTransactionMode() will set the GemStone transaction mode to automatic (chained transactions, with an implicit begin after a commit or abort).
    `void` | `setDebugOptions(boolean verboseClient, boolean verboseServer)` Set debugging options.
    `void` | `setManualTransactionMode()` setManualTransactionMode() will set the GemStone transaction mode to manual (explicit beginTransaction required).
    `void` | `setName(java.lang.String newName)` setName() will assign an identifying description to a session.
    `void` | `setToolData(java.lang.Object o)`
    `void` | `setTransactionlessMode()` setTransactionlessMode() will set the GemStone transaction mode to transactionless transaction mode.
    `void` | `setTransactionMode(java.lang.String mode)` setTransactionMode() sets the transaction mode of the session.
    `void` | `setupExceptionHandler(int errCode, java.lang.Object handlerObject, java.lang.String handlerMethodName)` Specify an object and method to execute when a particular GbjException is received.
    `static java.lang.String` | `stackTraceString(java.lang.Throwable t)`
    `java.lang.Object` | `toolData_()`
    `java.lang.String` | `toString()` return a description of this session.

    - ### Methods inherited from class com.gemstone.gbjgci.GbjGciSession

      `checkErrors, execute, getBytes, getNamedObjs, getNamedObjs, getObjs, getObjs, getSessionId, hashCode, isKindOf, isLoggedIn, login, logout, mapGsToJavaClass, mapGsToJavaClass, objectNamedOrNil, objWithOop, perform, putBytes, putNamedObjs, putObjs, waitForDebug`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### kernel

          public GbjKernelObjects kernel

      A collection of frequently accessed objects from the server Globals dictionary. GBJ30: due to design changes for GbjGciInterface requiring these to be fetched from the server, now limited to just the essentials, rather than *all* Globals.

    - #### lastError

          public java.lang.RuntimeException lastError

      lastError is deprecated. It is initialized to null.

    - #### userData

          public java.lang.Object userData

      userData is for customer use. Any session-related information may be placed here for convenient access.

    - #### monitorSessionSignals

          public boolean monitorSessionSignals

      Flag used to control if session signals should be monitored

    - #### objChgNotify

          public boolean objChgNotify

      Flag used to control if object change notification should be active

    - #### version

          public static java.lang.String version

      The version of the interface

    - #### pollInterval

          public int pollInterval

      The polling interval used to check for asynchronous signals (sigAbort, gem-to-gem signals, changed objects).

  - ### Constructor Detail

    - #### GbjSession

          public GbjSession()

    - #### GbjSession

          public GbjSession(GbjParameters sessionParameters)

      GbjSession() requires a sessionParameters object, which tells the session the host and port for the connection as well as the type of session requested
      Parameters:
        `sessionParameters` - a configured instance of GbjParameters

  - ### Method Detail

    - #### isConnected

          public boolean isConnected()

      isConnected indicates whether the session is able to communicate with its server. Using a session that is not connected will throw an Error.
      Returns:
        boolean result

    - #### setToolData

          public void setToolData(java.lang.Object o)

    - #### toolData_

          public java.lang.Object toolData_()

    - #### stackTraceString

          public static java.lang.String stackTraceString(java.lang.Throwable t)

    - #### registerStaticStub

          public static void registerStaticStub(GbjObject stubInstance,
                                                java.lang.String gemstoneClassName)

      registerStaticStub allows building of a GemStone@lt-@gtJava class correspondence at static initialization time. The stub instance is used to clone new proxies to represent instances of the given GemStone class at run time.
      Parameters:
        `stubInstance` - an instance of the stub class (must currently be a GbjObject)
        `gemstoneClassName` - the name of the GemStone class, which is found at session initialization time

    - #### registerStub

          public void registerStub(GbjObject stubInstance,
                                   java.lang.String gemstoneClassName)
                            throws GbjException

      registerStub allows building of a GemStone@lt-@gtJava class correspondence at run time. The stub instance is used to clone new proxies to represent instances of the given GemStone class.
      Parameters:
        `stubInstance` - an instance of the stub class (must currently be a GbjObject)
        `gemstoneClassName` - the name of the GemStone class
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### registerStub

          public void registerStub(GbjObject stubInstance,
                                   GbjObject classStub)
                            throws GbjException

      registerStub allows building of a GemStone<->Java class correspondence at run time. The stub instance is used to clone new proxies to represent instances of the given GemStone class.
      Parameters:
        `stubInstance` - an instance of the stub class (must currently be a GbjObject)
        `classStub` - a GbjObject stub for the server class object
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### registerStaticAdapter

          public static void registerStaticAdapter(java.lang.String className,
                                                   GbjClientAdapter adapter)

      registerStaticAdapter specifies an object to be used in forwarding messages for the given Java class. The adapter is sent the receiver, method name, and a Vector holding the arguments and must forward the message to the object. This part of the API will be removed when Java has enough reflective access to allow the GemStone interface to dispatch messages automatically. The static form of registration establishes the adapter for all subsequently instantiated sessions. An class can function as its own adapter without need of registration by implementing the interface GMsgAdapter. See documentation on the GMsgAdapter interface for more information on implementing an adapter.
      Parameters:
        `className` - A fully qualified class name. E.g., java.util.Stack
        `adapter` - The object that will forward messages
      See Also:
        `registerAdapter(java.lang.String, com.gemstone.gbj.GbjClientAdapter)`

    - #### registerAdapter

          public void registerAdapter(java.lang.String className,
                                      GbjClientAdapter adapter)

      registerAdapter specifies an object to be used in forwarding messages for the given Java class. The adapter is sent the receiver, method name, and a Vector holding the arguments and must forward the message to the object. This part of the API will be removed when Java has enough reflective access to allow the GemStone interface to dispatch messages automatically. An class can function as its own adapter without need of registration by implementing the interface GMsgAdapter. See documentation on the GMsgAdapter interface for more information on implementing an adapter.
      Parameters:
        `className` - A fully qualified class name. E.g., java.util.Stack
        `adapter` - The object that will forward messages
      See Also:
        `registerStaticAdapter(java.lang.String, com.gemstone.gbj.GbjClientAdapter)`

    - #### initialize

          public static void initialize(boolean useLinked,
                                        java.lang.String appName,
                                        int bufSize,
                                        int preloadSize,
                                        int maxSessions,
                                        java.lang.Class objectClass)

      Initializes the GBJ environment.

      If used, this method should be called before the first GbjSession.connect( ). If not explicitly called first by the application, this method will be automatically called during the first GbjSession.connect( ), using the default values specified below.

      Parameters:
        `useLinked` - Must be true, only linked login is supported. This GBJ jar supports only a single linked session per Java VM .
        `appName` - Optional application name. The name that is displayed in the GS/S session cache statistics and statmonitor/VSD output for this gem process. Default is "GbjApplication".
        `bufSize` - Maximum size (in bytes) for internal byte/oop buffers. The maximum number of bytes that can be transfered in a single getOops()/getNamedOops()/getBytes() operation. Exceeding this value will trigger a GbjGciException. The value is used to allocate internal buffers for storage during transfer. Default is 100000.
        `preloadSize` - Maximum size (in bytes) for initial preload of objects When an object is initially fetched from the server, this parameter specifies how many bytes are preloaded with the initial fetch. These are cached, and subsequent getOops()/getNamedOops()/getBytes() calls can retrieve their results from this cache if available. Application developers can tune performance by sizing this as appropriate -- larger sizes will improve the performance of subsequent getX operations at the expense of a slower initial object fetch. 1000 bytes is a good starting value. Default is 1000.
        `maxSessions` - Maximum number of sessions that will be run on this Stone. This should be equal to or greater than the setting of the stone configuration file parameter STN_MAX_SESSIONS. Default is 1000.
        `objectClass` - Defines what class of object is returned from the server (unless overriden by registerStub()). If the Application extends GbjObject functionality, supply the appropriate application class here so that results are returned as the appropriate class. Defaults to GbjObject.

    - #### initialize

          public static void initialize(boolean useLinked,
                                        java.lang.String appName,
                                        int bufSize,
                                        int preloadSize,
                                        int maxSessions)

      Initializes the GBJ environment.

      See initialize(useLinked, appName, bufSize, preloadSize, maxSession, objectClass) for parameter details.

      Parameters:
        `useLinked` - See initialize( ... objectClass) must be true
        `appName` - See initialize( ... objectClass)
        `bufSize` - See initialize( ... objectClass)
        `preloadSize` - See initialize( ... objectClass)
        `maxSessions` - See initialize( ... objectClass)

    - #### getBytes

          public byte[] getBytes(GbjObject obj,
                                 long startIndex,
                                 int numBytes)

      Retrieve the designated bytes from this byte-based GS object.
      Parameters:
        `obj` - The GS object to retrieve the bytes from.
        `startIndex` - The starting index (1-based)
        `numBytes` - The number of bytes to retrieve
      Returns:
        the retrieved bytes
      Throws:
        `GbjGciException` - thrown on any errors

    - #### getObjs

          public GbjObject[] getObjs(GbjObject obj,
                                     long startIndex,
                                     int numOops)

      Retrieve the designated GS objects from this indexable GS object
      Parameters:
        `obj` - The GS object to retrieve the GS objects from.
        `startIndex` - The starting index (1-based)
        `numOops` - The number of objects to retrieve
      Returns:
        An array of GS objects containing the results
      Throws:
        `GbjGciException` - thrown on any errors

    - #### getNamedObjs

          public GbjObject[] getNamedObjs(GbjObject obj,
                                          long startIndex,
                                          int numOops)

      Retrieve the designated GS objects from the named instvars for this GS object.
      Parameters:
        `obj` - The GS object to retrieve the GS objects from.
        `startIndex` - The starting index (1-based)
        `numOops` - The number of objects to retrieve
      Returns:
        An array of GS objects containing the results
      Throws:
        `GbjGciException` - thrown on any errors

    - #### setDebugOptions

          public void setDebugOptions(boolean verboseClient,
                                      boolean verboseServer)

      Set debugging options. These debugging options can be used to diagnose problems in the interface. While debugging options may be set at any time, they are most useful if turned on before connecting to the server.
      Setting verboseClient to true will cause the interface to write messages to Java's System.out stream. Messages are also sent to observers of the session with a "message" designator and the string as an argument.
      Setting verboseServer to true will cause the server to write messages to the session's log file on the server.
      Parameters:
        `verboseClient` - display debugging information on System.out, and notify observers
        `verboseServer` - write debugging information to gbj<sessionId>.log on server

    - #### connect

          public void connect()
                       throws GbjException

      connect() is usually sent soon after instantiating a session to connect to the server . The session is not very usable until it's been connected. In this Jar, only a single instance of GbjSession may be connected at at time.
      Throws:
        `GbjException` - thrown if there is a server exception while connecting
      See Also:
        `close()`

    - #### close

          public void close()

      close() closes the connection.
      See Also:
        `connect()`

    - #### clientObject

          public GbjObject clientObject(java.lang.Object o)

    - #### abortTransaction

          public void abortTransaction()
                                throws GbjException

      abortTransaction() rolls back the current transaction in the database.
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `beginTransaction()`, `commitTransaction()`, `commitAndReleaseLocks()`

    - #### rollbackTransaction

          public void rollbackTransaction()
                                   throws GbjException

      rollbackTransaction() rolls back the current transaction in the database. This is the same as abortTransaction().
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `abortTransaction()`, `beginTransaction()`, `commitTransaction()`, `commitAndReleaseLocks()`

    - #### beginTransaction

          public void beginTransaction()
                                throws GbjException

      beginTransaction() starts a new transaction in the database. This will throw a GbjException with number RT_ERR_BEGIN_TRANS if a transaction is already in progress. You must specify ExplicitTransactions in the transactionMode parameter for a session, or set manual transaction mode with System/transactionMode: before using this method. The default transaction mode for Java sessions explicit transactions.
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `abortTransaction()`, `commitTransaction()`, `commitAndReleaseLocks()`

    - #### commitTransaction

          public boolean commitTransaction()
                                    throws GbjException

      Deprecated. use commit() for new code to ensure that conflicts signal a GbjException.
      commitTransaction() commits the current transaction in the database.
      This will throw a GbjException with number RT_ERR_PRIM_OUTSIDE_TRANS if a transaction is not in progress.
      In GemStone, a commit may fail due to read-write/write-read conflicts or write/write conflicts. If the commit operation should fail due to one of these conditions, this method returns false. If the commit is successful, this method returns true.
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `abortTransaction()`, `beginTransaction()`, `commitAndReleaseLocks()`

    - #### commit

          public boolean commit()
                         throws GbjException

      commit() commits the current transaction in the database.
      Returns:
        boolean true , or throws a GbjException if commit failed
      Throws:
        `GbjException` - thrown if the session is not connected , if the session is not in a transcation, or there is a server exception, or if there are conflicts

    - #### commitAndReleaseLocks

          public boolean commitAndReleaseLocks()
                                        throws GbjException

      commitAndReleaseLocks() is like commitTransaction but any locks held are released if the commit succeeds. This is equivalent to the ODMG commit operation while the commitTransaction() method is equivalent to the ODMG checkpoint operation.
      This will throw a GbjException with number RT_ERR_PRIM_OUTSIDE_TRANS if a transaction is not in progress.
      In GemStone, a commit may fail due to read-write/write-read conflicts or write/write conflicts. If the commit operation should fail due to one of these conditions, this method returns false. If the commit is successful, this method returns true.
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `abortTransaction()`, `beginTransaction()`, `commitTransaction()`

    - #### inTransaction

          public boolean inTransaction()
                                throws GbjException

      Returns true if the GemStone server has started a transaction and false if not.
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `beginTransaction()`, `setAutomaticTransactionMode()`, `setManualTransactionMode()`

    - #### setManualTransactionMode

          public void setManualTransactionMode()
                                        throws GbjException

      setManualTransactionMode() will set the GemStone transaction mode to manual (explicit beginTransaction required). This is the default transaction mode for connections from Java clients.
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `GbjParameters.transactionMode`, `setAutomaticTransactionMode()`, `setTransactionlessMode()`

    - #### setAutomaticTransactionMode

          public void setAutomaticTransactionMode()
                                           throws GbjException

      setAutomaticTransactionMode() will set the GemStone transaction mode to automatic (chained transactions, with an implicit begin after a commit or abort).
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `GbjParameters.transactionMode`, `setManualTransactionMode()`, `setTransactionlessMode()`

    - #### setTransactionlessMode

          public void setTransactionlessMode()
                                      throws GbjException

      setTransactionlessMode() will set the GemStone transaction mode to transactionless transaction mode. This mode is intended for idle sessions. Applications using transactionless mode may see an inconsistent view of the database.
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception
      See Also:
        `GbjParameters.transactionMode`, `setAutomaticTransactionMode()`, `setManualTransactionMode()`

    - #### isAutomaticTransactionModeSet

          public boolean isAutomaticTransactionModeSet()
                                                throws GbjException

      isAutomaticTransactionModeSet() will return true if the server is in automatic transaction mode and false if not.
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### getTransactionMode

          public java.lang.String getTransactionMode()
                                              throws GbjException

      getTransactionMode() returns a string describing the current transaction mode. The string will be one of "autoBegin", "manualBegin", or "transactionless".
      Returns:
        string result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### setTransactionMode

          public void setTransactionMode(java.lang.String mode)
                                  throws GbjException

      setTransactionMode() sets the transaction mode of the session. Acceptable values are "autoBegin", "manualBegin" or "tranactionless".
      Parameters:
        `mode` - String
      Throws:
        `GbjException` - thrown if passed an invalid transaction mode, if the session is not connected or there is a server exception.

    - #### objectNamed

          public GbjObject objectNamed(java.lang.String smalltalkObjectName)
                                throws GbjException

      objectNamed() is a name lookup service. The @param smalltalkObjectName must refer to a name in the symbolList of the GemStone user-account on the server. If the name is found, a stub is returned for the object, otherwise null is returned.
      Overrides:
        `objectNamed` in class `GbjGciSession`
      Parameters:
        `smalltalkObjectName` - String
      Returns:
        GbjGciObject result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### execute

          public GbjObject execute(java.lang.String smalltalkCode)
                            throws GbjException

      Execute smalltalk code on the server.
      Overrides:
        `execute` in class `GbjGciSession`
      Parameters:
        `smalltalkCode` - String containing code
      Returns:
        a GS object representing the results of execution.
      Throws:
        `GbjException`

    - #### perform

          public GbjObject perform(GbjObject receiver,
                                   java.lang.String selector,
                                   GbjObject[] args,
                                   int argCount)

      Perform a particular smalltalk method against a particular object.
      Parameters:
        `receiver` - GbjObject to send message against
        `selector` - string with method name
        `args` - GbjObject array containing arguments
        `argCount` - number of arguments in args array
      Returns:
        GbjObject result

    - #### doit

          public GbjObject doit(java.lang.String smalltalkCode)
                         throws GbjException

      doit() sends the given @param smalltalkCode string to the server for compilation and execution. The code may have temporaries and return ("^") statements, but may not refer to "self", or "super". The result of execution (a stub for a remote object) is returned.
      Parameters:
        `smalltalkCode` - String containing code
      Returns:
        GbjObject result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### printit

          public java.lang.String printit(java.lang.String smalltalkCode)
                                   throws GbjException

      printit() is the same as doit(), but the message "printString" is sent to the result and the answer of this message is returned. The answer will always hold a string value (see GbjObject.stringValue()).
      Parameters:
        `smalltalkCode` - String containg code
      Returns:
        String result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### putInServer

          @Deprecated
          public GbjObject putInServer(java.lang.Object obj)
                                            throws GbjException

      Deprecated. use GbjObject constructor
      putInServer() puts the given object in the server and returns a GbjObject stub for it. This does not make the object persistent - to make it persistent it must be named, or reachable from a named object.
      Parameters:
        `obj` - Object to put on server
      Returns:
        GbjObject result
      Throws:
        `GbjException` - thrown if the session is not connected or there is a server exception

    - #### getName

          public java.lang.String getName()

      getName() will return an identifying description of a session. The default name is the session broker's machine, an underscore, and the session id assigned at connect time (nil if not connected).
      Returns:
        String value
      See Also:
        `setName(java.lang.String)`

    - #### getShortName

          public java.lang.String getShortName()

      getShortName() will return a short identifying description of a session. The short name includes the string "Session: " followed by the sessionId.
      Returns:
        String result

    - #### setName

          public void setName(java.lang.String newName)

      setName() will assign an identifying description to a session. If a name is not assigned, a system-generated name is used.
      Parameters:
        `newName` - String for name
      See Also:
        `getName()`

    - #### toString

          public java.lang.String toString()

      return a description of this session.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        String containing description.

    - #### checkConnected

          public void checkConnected()
                              throws GbjException

      checkConnected() will throw a GbjException if the session is not in a connected state. It checks the state of the connected flag to determine if the session is connected.
      Throws:
        `GbjException` - thrown if this session is not connected

    - #### addObserver

          public void addObserver(GbjObserver obs)

      add an observer to the receiver
      Specified by:
        `addObserver` in interface `GbjObservable`

    - #### removeObserver

          public void removeObserver(GbjObserver obs)

      remove an observer
      Specified by:
        `removeObserver` in interface `GbjObservable`

    - #### notifyObservers

          public void notifyObservers(java.lang.String notificationMessage,
                                      java.lang.Object argument)

      notify observers of a change
      Specified by:
        `notifyObservers` in interface `GbjObservable`

    - #### setupExceptionHandler

          public void setupExceptionHandler(int errCode,
                                            java.lang.Object handlerObject,
                                            java.lang.String handlerMethodName)
                                     throws java.lang.NoSuchMethodException

      Specify an object and method to execute when a particular GbjException is received. This method provides a way of establishing client-side exception handlers for any exception, but is particularly useful for the following GemStone error codes:
      - 6008 - Changed object notification
      - 6009 - SigAbort handling
      - 6010 - Gem-to-Gem signals
      Arguments are:
      - 1. The GS error code
      - 2. The object to send the message to.
      - 3. The method to execute.
      Method must be recognized by the object, and have two arguments:
      - 1. The GbjSession receiving the exception
      - 2. The GbjException that was triggered
      Method must return a GbjObject as a result
      Parameters:
        `errCode` - The int error code to be handled
        `handlerObject` - The designated object to handle the exception
        `handlerMethodName` - The name of the method to be called when the exception is raised
      Throws:
        `java.lang.NoSuchMethodException` - thrown if method doesn't exist