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 provide the details of the object server (repository) that you want to connect to. 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 interfaces are described in later sections.

You may need to contact your GemStone server administrator for the specific details to supply. In distributed configurations, you will need to specify some information in GemStone’s Network Resource String (NRS) format. NRS format is described in the System Administration Guide, which also describes NetLDI security requirements.

The information needed includes the following:

• The specification of the GemStone repository
  In its simplest form, the name of the Stone repository monitor. In a distributed configuration with non-default names, you may need to include the server’s hostname and/or NetLDI name or port in NRS format.

For example, for a Stone named “gs64stone” on a host named “pelican”, where the NetLDI is listening on port 54321, specify an NRS string of the form:

!@pelican#netldi:54321!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 (if required to start a Gem)
  The host user name and password, which must specify a valid UNIX login account for the Gem’s host machine (the machine specified in the Gem service, described below).

These parameters are not needed for a linked session, since no separate Gem process is started up, nor if the NetLDI is running in guest mode.

• The specification for the Gem service (for RPC logins only)
  In its simplest form, the Gem service is gemnetobject. In a distributed configuration with non-default names, you may need to include the server’s hostname and/or NetLDI name or port, in NRS format. For example:

!@pelican#netldi:54321!gemnetobject

The gem service may include additional command-line arguments that are passed to gemnetobject, as described in the System Administration Guide.

You should not specify a Gem Service if you are starting a linked Gem process, since no separate Gem process is started up.

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

username: aUsername

password: aPassword

hostUsername: aHostUsername

hostPassword: aHostPassword

gemService: aGemServiceSpecification

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

GbsSessionParameters newWithGemStoneName: aStoneSpecification

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 message to another session 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