2. Communicating with the GemStone Object Server

RPC and Linked Sessions

A Gem can run as a separate operating system process and respond to Remote Procedure Calls (RPCs) from its client, in which case the session it supports is called an RPC session.

On platforms that host the GemStone object server and its runtime libraries, one Gem can be integrated with the application into a single operating system process. That Gem is called a linked session. When running linked, an application and its Gem must run on the same machine and the runtime code requires additional memory.

An RPC session offers more flexibility because the application and its Gem are separate processes that can run on different hosts in a network. Any GemBuilder client can create RPC sessions. Where a linked session is supported, an application can create multiple sessions, but only one can be linked. To suppress linked sessions, forcing all Gems to run as RPC processes, you can load the RPC-only version of the shared libraries.

Figure 2.1 shows an application with two logged-in sessions. Gem A is an RPC session running as a separate process, while Gem B is a linked session, sharing the client Smalltalk application's process space.

Figure 2.1   RPC and Linked Gem Processes

Session Parameters

To initiate a GemStone session, you must first identify the object server and user account to which you wish to connect. This information is stored in an instance of GbsSessionParameters and added to a list maintained by GBSM. You can provide the information through window-based tools or programmatically. Both methods are described in later sections. In either case, you must supply these items:

• The name of the GemStone repository
  For a Stone running on a host other than the Gem host (described below), you must include the server’s hostname in Network Resource String (NRS) format. NRS format is described in an appendix to the System Administration Guide. For instance, for a Stone named “gs64stone” on a host named “pelican”, specify an NRS string of the form:

!@pelican!gs64stone

• GemStone user name and GemStone password
  This user name and password combination must already have been defined in GemStone by your GemStone data curator or system administrator. (GemBuilder provides a set of tools for managing user accounts—see User Account Management Tools.) Because GemStone comes equipped with a data curator account, we show the DataCurator user name in many of our examples.
• Host username and Host password (not required for a linked session, or if netldi is run in guest mode)
  This user name and password combination specifies a valid login on the Gem’s host machine (the network node specified in the Gem service name, described below). Do not confuse these values with your GemStone username and password. You do not need to supply a host user name and host password if you are starting a linked Gem process. However, an application that must control more than one GemStone session can use a linked interface for only one session. Other sessions must use the RPC interface.
• Gem service (not required for a linked session)
  The name of the Gem service on the host computer (that is, the Gem process to which your GemBuilder session will be connected). For most installations, the Gem service name is gemnetobject.

You can specify that the gem is to run on a remote host by using an NRS for the Gem service name For example:

!@pelican!gemnetobject

You do not need to supply a Gem Service name if you are starting a linked Gem process.

Once defined, an instance of GbsSessionParameters can be used for more than one session. Thus, a session description that includes the RPC-required parameters can be used for both linked and RPC logins.

Defining Session Parameters Programmatically

The instance creation method for a full set of RPC parameters is:

GbsSessionParameters newWithGemStoneName: aGemStoneName

username: aUsername

password: aPassword

hostUsername: aHostUsername

hostPassword: aHostPassword

gemService: aGemServiceName

For a shorter set of parameters that supports only linked logins, you can use a shorter creation method:

GbsSessionParameters newWithGemStoneName: aGemStoneName

username: aUsername

password: aPassword

GBSM addParameters: aGbsSessionParameters

GBSM removeParameters: aGbsSessionParameters

mySessionParameters := GbsSessionParameters

newWithGemStoneName: '!@pelican!gs64stone'

username:            'DataCurator'

password:            ''

hostUsername:        'lisam'

hostPassword:        ''

gemService:          '!@pelican!gemnetobject'

mySessionParameters rememberPassword: true;

rememberHostPassword: true

Logging In to GemStone

The protocol for logging in is understood both by GBSM and by instances of GbsSessionParameters. To log in using a specific session parameters object, send a login message to the parameters object itself:

mySession := aGbsSessionParameters login

To start multiple sessions with the same parameters, simply repeat these login messages.

An application can also send a generic login message to GBSM:

mySession := GBSM login

This message invokes an interactive utility that allows you to select among known GbsSessionParameters or to create a new session parameters object using the Session Parameters Editor.

A successful login returns a unique instance of GbsSession. (An unsuccessful login attempt returns nil.) Each instance of GbsSession maintains a reference to that session’s parameters, which you can retrieve by sending:

myGbsSessionParameters := aGbsSession parameters

GBSM maintains a collection of currently logged in GbsSessions. You can determine if any sessions are logged in with GBSM isLoggedIn and you can execute GBSM loggedInSessions to return an array of currently logged in GbsSessions.

The Current Session

When a new GbsSession is created, it is registered with GBSM, which maintains a variable that represents the current session. When a session logs in, it becomes the current session. If you execute code in a GemStone tool, the code is evaluated in the current session, or in the session that was current when you opened that tool. If you send a message to GBSM that is intended for a session, the message is forwarded to the current session.

You can send a message directly to any logged-in GbsSession, even when it is not the current session. If you send a specific session a message that executes code, that code is evaluated in the receiving session, regardless of whether it is the current session.

Most applications have only one session logged in at a time. In this case, that session will always be the current session, and it is safe to send messages to GBSM for forwarding to the session.

However, if your application concurrently logs in more than one session, your application should send messages directly to each session. If your application client uses multiple Smalltalk processes it is very difficult to accurately coordinate the changing of the current session.

Sending the message GBSM currentSession returns the current GbsSession. You can change the current session in a workspace by executing an expression of the following form:

GBSM currentSession: aGbsSession.

Your application can make another session the current session by executing code like that shown in Example 2.1:

|s1 s2|

s1 := GBSM login.

s2 := GBSM login.

GBSM currentSession: s1.  "Make s1 current" 

. 

.	"Do some work" 

.

GBSM currentSession: s2.  Make s2 current" 

Logging Out of GemStone

To instruct a session to log itself out, send logout to the session object:

aGbsSession logout

Or, you can execute the more generic instruction:

GBSM logout

This message prompts you with a list of currently logged-in sessions from which to choose.

Before logging out, GemBuilder prompts you to commit your changes, if the GbsConfiguration setting confirm is true (it is true by default). If you log out after performing work and do not commit it to the permanent repository, the uncommitted work you have done will be lost.

If you have been working in several sessions, be sure to commit only those sessions whose changes you wish to save.

Example 2.2 

| mySession |

mySession := self session.

"Add this browser to the sessions dependents list"

(session dependents includes: self)

	ifFalse: [session addDependent: self]

...

When a session receives a commit, abort, or logout request, it sends an updateRequest: message to each of its dependents, with an argument describing the nature of the request. Each registered object should be prepared to receive the updateRequest: message with any one of the following aspect symbols as its argument:

#queryCommit
The session with which this object is registered has received a request to commit. Return true to allow the commit to take place or false to prevent it.

#queryAbort
The session with which this object is registered has received a request to abort. Return true to allow the abort to take place or false to prevent it.

#queryEndSession
The session with which this object is registered has received a request to terminate the session. Return true to allow the logout to take place or false to prevent it.

Example 2.3 shows how a session dependent might implement an updateRequest: method.

Example 2.3 

updateRequest: aspect

"The session I am attached to wants to do something.

Return a boolean granting or denying the request."

^(#(queryAbort queryCommit queryEndSession)

	includes: aspect)

		ifTrue: [ self askUserForPermission ]

		ifFalse: ["Let any other action occur." 

					true]

After the action is performed, the session sends self changed: with a parameter indicating the type of action performed. This causes the session to send an update: message to each of the registered dependents with one of the following aspect symbols:

#committed
All registered objects have approved the request to commit, and the transaction has been successfully committed.

#aborted
All registered objects have approved the request to abort, and the transaction has been aborted.

#sessionTerminated
The request to log out has been approved and the session has logged out.

Each registered dependent should be prepared to receive an update: message with one of the above aspect symbols as its argument. Example 2.4 shows how a session dependent might implement an update: method.

Example 2.4 

update: aSymbol

"The session I am attached to just did something.

I might need to respond."

(aSymbol = #sessionTerminated) ifTrue: [

"The session this tool is attached to has logged out

  - close ourself."

self builder notNil ifTrue:

	[self closeWindow]]

Figure 2.2 summarizes the sequence of events that occurs when a session queries a dependent before committing. In the figure, the GemStone Launcher sends a commit request (commitTransaction) to a session (1). The session sends updateRequest: #queryCommit to each of its dependents (2). If every dependent approves (returns true), the commit proceeds (4). Following a successful commit, the session notifies its dependents that the action has occurred by sending update: #committed to each (5).

Figure 2.2   Committing with Approval From a Session Dependent