12. Using the GemStone Programming Tools
GemBuilder provides a set of code browsers that allow you to browse and edit code residing on the GemStone server. Writing code in GemStone Smalltalk is similar to writing code in client Smalltalk, but there are some important differences. Some of these differences are mentioned in this chapter; for more detail on programming in GemStone Smalltalk, see the GemStone/S Programming Guide.
In addition to the browsers and related tools provided by GBS, menus in client Smalltalk tools will have additional menu options to execute GemStone Smalltalk code.
12.1 Browsing Code
GemBuilder includes a number of Code Browsers, allowing you to browse all code in the System, or browse smaller subsets of code. These browsers are similar to the client Smalltalk browsers, allowing you access source code and other information about each of the kernel classes and methods, and create classes and methods in the GemStone repository.
System Browser
When logged in to GemStone, you can open a GemStone System Browser by choosing Browse > System, or by selecting the icon on the GemStone Launcher Toolbar.
The System Browser is similar to the client Smalltalk System Browser. The GemStone System Browser allows you access source code and other information about each of the kernel classes and methods, and create classes and methods in the GemStone repository.
Each pane of the each of the GemStone Browsers also has pop-up menus that are specific to that pane; these menus are also available from the appropriate menu on the menu bar. Some of these operations are also available via shortcuts on the ToolBar.
Figure 12.1 GemStone System Browser
Most of the features of the system browser are likely to be familiar from client Smalltalk browsers, although there are some features and menus that are unique.
- Text Modification Indicator. This icon on the Text View tabs Source, Definition or Comment becomes red if you have modified the code in the text pane. You can use the Accept or Cancel menu options to save or discard the changes.
- Refresh From GS Server. Clicking on this pink diamond refreshes the view in the current browser from the GemStone server.
Find Menu
The Find menu allows you to find 
Symbol Dictionaries, Classes, and Methods within GemStone.
The options available on this menu are:
Find Dictionary... Prompts for the name of a SymbolDictionary, and opens a SymbolDictionary Browser on the result.
Find Class... Opens a Select Class dialog, which allows you to select the name of a class from a list of available classes. Navigates to the selected class and Symbol dictionary, or opens a Hierarchy Browser on the selection, depending on the Browser.
References to... Prompts for the name of a variable, then opens a References Method List Browser listing all methods that refer to that variable. Search accepts wildcard characters * and ?, and is case-insensitive unless any uppercase characters are used.
Implementors of... Prompts for the name of a message selector, then opens an Implementors Method List Browser showing all methods that implement that selector. Search accepts wildcard characters * and ?, and is case-insensitive unless any uppercase characters are used.
Senders of... Prompts for the name of a message selector, then opens a Senders Method List Browser showing all methods that send that selector. Search accepts wildcard characters * and ?, and is case-insensitive unless any uppercase characters are used.
Methods with String Matching...
Prompts for a string, then opens a browser listing all methods whose source code contains the specified string. The search is case-sensitive.
Symbol Dictionaries Pane and the Dictionary menu
The Symbol Dictionaries Pane displays the current GemStone user’s SymbolList, which is a collection of Symbol Dictionaries. Symbol Dictionaries are comparable to Namespaces; they contain a collection of classes, and their ordering controls the resolution of Class and variables names. For more on how Symbol Dictionaries resolve symbols, refer to GemStone/S Programming Guide.
You can reorder Symbol Dictionaries by dragging and dropping within the Symbol Dictionaries pane.
Each user normally has a different set of symbol dictionaries. Symbol dictionary access is managed using tools that are described in Chapter 14.
When you select a symbol dictionary in the Symbol Dictionaries pane, all classes defined in that dictionary appear in the Classes pane to the right. (Symbols other than classes can be viewed by opening an inspector on the symbol dictionary in question, or by selecting Browse > Symbol Lists from the GemStone Launcher).
The following menu items are in this pane’s pop-up menu and under the menu bar Dictionary menu.
File Out As... Prompts a file name to save all the class and method definitions for all the classes in the selected SymbolDictionary.
File Out Methods As... Prompts a file name to save all the method definitions for all the classes in the selected SymbolDictionary.
Browse Open a SymbolDictionary Browser on the selected SymbolDictionary.
Add... Add a new Symbol Dictionary
Rename As... Rename the selected SymbolDictionary.
Remove... Remove the selected SymbolDictionary (does not apply to Globals).
Inspect Open an inspector on the selected SymbolDictionary. This allows you to see Globals in the SymbolDictionary as well as the classes.
Classes Pane and the Class menu
The Class pane displays a list of the classes in the selected symbol dictionary.
Selecting a class displays the list of categories in this class in the Category pane, all methods of that class in the methods pane, and sets the Text View Tabs to the Definition tab so the class definition is shown in the Text pane.
When you have a class selected, the Text View Tabs on the Text pane can be used to control what is viewed: the class definition, hierarchy, or class comment.
The following menu items are in this pane’s pop-up menu and under the menu bar Class menu.
File Out As... Prompts for a file name under which to save the class definition and all methods of the selected class.
File Out Methods As... Prompts for a file name under which to save all methods of the selected class, but not the class definition itself.
Browse Class Open a Class Browser on the selected class.
Browse Hierarchy Open a Hierarchy Browser on the selected class.
Browse Versions Open a Class Version Browser on the selected class.
Browse References Open a References Browser on all references to an instance variable, a class variable, to the current version of the class, or to all versions of the class.
Add Open a dialog allowing you to create a new class, or to add an instance variable to the currently selected class.
Move to... Prompt for another SymbolDictionary to which to move the selected class.
Remove... Remove the selected class.
Create Accessors... Opens a dialog allowing you to create setter and getter methods for instance variables of the selected class.
Create Client Class Creates a client Smalltalk class having the same name and structure as the selected GemStone Smalltalk class, if one doesn’t already exist. If it does exist, executing this menu item has no effect. The client class will not have any methods.
Compile Client Class Creates a client Smalltalk class having the same name and structure as the selected GemStone Smalltalk class, and compiles all currently defined methods for the class. If necessary, a notifier lists any methods that cannot be compiled in client Smalltalk.
Inspect All Instances Performs a server allInstances operation, and opens a browser on the results. Prompts for confirmation.
Categories Pane and the Category Menu
The Categories pane displays a list of the method categories that are in the selected class. Instance and Class tabs control whether the instance method categories or class method categories are displayed. Selecting a category displays the methods in that category in the Methods pane.
In addition to the Instance and Class tabs, there is an Instance Variable tab that allows you to view a list of the instance variables in that class, rather than Categories. Selecting an instance variable displays the methods that directly reference that instance variable.
The following menu items are in this pane’s pop-up menu and under the menu bar Category menu.
File Out As... Prompts you for a file name under which to save all methods of the selected category.
Browse Open a Category Browser on the selected Category.
Add... Open a dialog allowing you to create a new category.
Rename As... Open a dialog to enter a new name for the selected category.
Remove... Remove the selected category and all methods contained in it.
Find Method... Open a dialog allowing you to find a method within the class of the category.
Compile Client Protocol
Compile all methods in the selected category on the client class that is connected to the currently selected class.
Methods Pane and the Method Menu
The Methods pane displays a list of methods in the selected category, or if the Instance Variable tab is selected, the list of methods that reference that instance variable.
When you select a method, its source code is displayed in the lower portion of the browser, the text pane. In this pane, you can edit and recompile the method, set breakpoints in it, or execute fragments of GemStone Smalltalk code as in a workspace.
You may select multiple methods, or drag a selected method or methods to another category.
The following menu items are available on the methods pane pop-up menu and on the Method menu.
File Out As... Prompts you for a file name under which to save the selected method or methods.
Browse Open a Method Browser on the selected method.
Browse Hierarchy Open a Hierarchy Browser on the class of the selected method.
Browse Senders Open a Senders Method List Browser on all methods that send the selector of the method or any of the messages it sends.
Browse Implementors Open a Implementors Method List Browser on all methods that implement the selector of the method or any of the messages it sends.
Browse Hierarchy Senders
Open a Hierarchy Senders Method List Browser on all methods within the hierarchy of the selected class that send the selector of the method or any of the messages it sends.
Browse Hierarchy Implementors
Open a Hierarchy Implementors Method List Browser on all methods within the hierarchy of the selected class that implement the selector of the method or any of the messages it sends.
Move To... Open a dialog to select the name of an existing category to which to move the selected method or methods, or allowing you enter a new category.
Remove... Remove the selected method or methods.
Compile Client Method
Compile the selected method on the client class that is connected to the currently selected class.
Text Pane
The Text Pane displays source code or class information, depending on the selection of the Class View Tabs.
If any changes are made in the text in the Text pane, the Code Modification Indicator turns on (becomes red), to alert you to the unsaved changes. Changing tabs or navigating off of a pane with Code Modification Indicator on prompts you to save or discard your work.
Text View Tabs
When a method is selected, the Source tab is selected and the method source is displayed. You can use the other tabs to access other information about the class. When no method is selected and a class is selected, the class definition will be displayed.
Source Displays source code for a selected method, or the method template if no method is selected. If any changes are made to this method source, the Text Modification Indicator on that tab becomes red.
Definition Displays the class definition for the class. If any changes are made to this definition text, the Text Modification Indicator on that tab becomes red.
Hierarchy Displays the hierarchy of the class
Comment Displays the class comment, if any. Accept saves the class comment according to the rules for the particular server version you are logged into. If any changes are made to this comment, source, the Text Modification Indicator on that tab becomes red.
The Text pane has a pop-up menu, which provides commands similar to that of the corresponding menu in the client Smalltalk browser’s text pane; i.e. Accept and Format have the same behavior as in the client Smalltalk, as does Cut, Copy, and Paste, and so on.
The following GemStone-specific menu items are also available on the text pane pop-up menu
:
Set Breakpoint Insert a breakpoint at the step point nearest the cursor location. If the cursor is not exactly at a step point, scans the method from the current cursor location on and sets a breakpoint at the next step point. See Breakpoints for a further discussion of using breakpoints, and the Breakpoint Browser.
Remove Breakpoint Remove selected breakpoint.
Remove All Breakpoints
Remove all breakpoints in the method.
GS-Do it Executes the selected code in GemStone.
GS-Print it Executes the selected code in GemStone, and displays the result in the text pane.
GS-Inspect it Executes the selected code in GemStone and opens an inspector on the result.
GS-Debug it Opens a GemStone Debugger on the selected code, allowing you to step through it in the Debugger.
Session Menu
The Session menu provides convenience methods for managing the session that opened this browser. The operations on this menu apply to all browsers open for that session, not just the current browser. 
Auto-Commit Turn on or turn off auto-commit for this session.
Commit Transaction Attempts to commit modifications to the repository that occurred during the current GemStone transaction.
Abort Transaction Undoes all changes that you have made in the repository since the beginning of the current transaction. You are asked to confirm.
Begin Transaction Undoes all changes that you have made in the repository since the beginning of the current transaction, and begins a new Transaction.
Window Menu
The Window menu provides options that operate on the given browser, or on all GemStone windows.
The following items are on the Windows menu.
Raise GemStone Windows
Expands all minimized GemBuilder for Smalltalk windows.
Collapse GemStone Windows
Minimizes all GemBuilder for Smalltalk windows, except the GemStone Launcher.
Refresh From GS Server
Update the current window with any changes to be consistent with the current view from the GemStone Server. This does not commit or abort, so no new committed changes from the GS Server are visible. This is valuable when you are modifying code in multiple browsers.
Raise GemStone Launcher
Opens the GemStone Launcher if it is not already open, and brings it to the front.
Status Bar
The status bar, along the bottom of the window, keeps you updated on the specific Symbol Dictionary, Class, Protocol and Method you are viewing. The specific display will depend on the selections in your browser.
The Status Bar is particularly useful for browsers other than the System Browser that allow you to browse individual classes, protocols, methods or lists of methods. In these browsers, described in the next sections, the class or protocol may not be otherwise visible in the browser.
Other Code Browsers
There are a number of other browsers available that allow you to browse a subset of the code that is visible in the System Browser. These behavior of these browsers and the available menu operations are the same as the equivalent pane or panes in the System Browser; refer to the earlier sections in this chapter for details.
SymbolDictionary Browser
The SymbolDictionary Browser allows you to browse all classes and code within a single SymbolDictionary. Menu items and behavior are similar to the System Browser when a SymbolDictionary is selected.
Figure 12.1 SymbolDictionary Browser
Hierarchy Browser
The Hierarchy Browser lets you browse a class and its super and subclasses.
This browser is reached by double-clicking on a class in the System Browser, or by selecting a class and using the Class menu item “Browse Hierarchy” or the Method menu item “Browse Hierarchy”. Menu items and behavior are similar to a System Browser when a Class is selected.
Figure 12.2 Hierarchy Browser
Class Browser
The Class Browser allows you to browse the class definition and all methods for a single class. This browser is reached by selecting a class and using the Class menu item “Browse Class”. Menu items and behavior are similar to the System Browser when a Class is selected.
Figure 12.3 Class Browser
Category Browser
The Category browser allows you to browse all methods within a single method category.
The Category Browser is reached by double-clicking on a category in the System, Class, or Hierarchy Browser, or by using the Category menu item “Browse”.
Menu items and behavior are similar to the System Browser when a Category is selected.
Figure 12.4 Category Browser
12.2 Adding and Modifying Classes and Methods
This section explains how to define new GemStone classes and methods, and describes aspects of coding unique to GemStone Smalltalk. Only a brief summary is provided here; the detailed aspects of coding in GemStone Smalltalk are described in the GemStone/S Programming Guide.
Classes in GemStone Smalltalk
Classes in GemStone Smalltalk are similar to classes in client Smalltalk. There are a number of more advanced attributes for classes, provided as keywords during class creation. These are described in the GemStone/S Programming Guide.
Subclass creation messages
There are a variety of subclass creation messages, depending on the type of class you want to create. The set of subclass creation messages varies for different server products and versions. The class creation template displayed in the browsers will be appropriate for the currently logged in GemStone server version. For more details on subclass creation methods, see the instance methods on Class in the GemStone server, or refer to the GemStone/S Programming Guide.
When you redefine a class in GemStone, it does not modify the class; instead a new version of the class is created, linked to the original class via a class history. This is described in more detail in Modifying an Existing Class: Class Versions.
Modifiable classes
Classes may be created as modifiable or not modifiable. Classes that are modifiable can be modified, e.g. you may add and remove instance, class, and class instance variables; but you cannot create instances of a modifiable class. Before you can create instances of a modifiable class, you must send the message #immediateInvariant to the class, to make it non-modifiable.
To make a class modifiable, use the #modifiable keyword in the options: array, or check the Modifiable checkbox in the Add GemStone Class dialog.
Defining a New Class
You may define a new GemStone class using the Add Class dialog or by using the template provided in the Code Browser Text pane.
When you add a new class, if there is an existing class with the same name in the same SymbolDictionary, your new class will be a version of the existing class. In this case, a dialog will ask if you want to commit your changes and migrate instances.
If your new class has the same name as an existing class in a different SymbolDictionary, then both classes will exist, unrelated. References to the class’s name will resolve to the class in the SymbolDictionary that is higher in the SymbolList. Note that this resolution is at compile time, not runtime. For more information on symbol resolution, see the GemStone/S Programming Guide.
Add Class Dialog
The Add Class Dialog, accessed from the menu item Class > Add, allows you to create a class in the currently selected SymbolDictionary. It prompts you for the name of the new class, the superclass, and instance and class variables.
Using the Template
The Class creation template is displayed in the System Browser when a SymbolDictionary is selected but no class is selected, or in the SymbolDictionary, Class, and Class Hierarchy Browsers when no class is selected.
The browser displays the class definition template, which will vary between server products and versions. For example, in GemStone/S 64 Bit 3.x:
NameOfSuperclass subclass: 'NameOfClass' instVarNames: #() "example: 'instVar1' 'instVar2' " classVars: #() "example: 'ClassVar1' 'ClassVar2' " classInstVars: #() "example: 'classIvar1' 'classIvar2' " poolDictionaries: {} inDictionary: SelectedSymbolDictionary options: #()
You may replace this template with another class creation method, if you prefer; for example, if you want to create an indexable or byte format class.
Edit the template to replace NameOfSuperclass and NameOfClass with your desired superclass and class names, and provide instance, class and class instance variable and pool dictionaries that you want your class to include.
SelectedSymbolDictionary determines which Symbol Dictionary will contain the new class; by default, the selected Symbol Dictionary.
The array following the options: keyword allows you to specify symbols to define specific features of the new subclass. This particular keyword is only available in class creation protocol in GemStone/S 64 Bit 3.x; in earlier products and versions, other class creation protocol is used to define the available class features. For details on these options, see the Programming Guide for your server product and version.
Modifying an Existing Class: Class Versions
If you select an existing GemStone Smalltalk class, then modify and save the class definition within the same symbol dictionary, you create a new version of that class and all of its subclasses. This is discussed in Chapter 8, “Schema Modification and Coordination”. The browser attempts to recompile all methods from the previous version into the new version. Methods that fail to recompile are presented in a method list browser, from which you can correct the errors. If the class has subclasses, they are also versioned and their methods are recompiled.
You can only modify classes for which you have write authorization. When running as a user other than SystemUser, you cannot modify GemStone kernel classes.
When you modify an existing class, in addition to recompiling the class and its subclasses, the tools will ask if you wish to commit the transaction and migrate all instances of the selected class to the new version of the class. If you choose not to do this, you can later explicitly migrate some or all instances of one version of a class to another version. Migration is described in detail in the Programming Guide for your server version and product.
Class Version Browser
Classes that are versions of each other are linked by a shared classHistory. Only the latest version is displayed in the browsers; the display includes the sequence number of the class within the class history, in brackets; for example if you have two versions of Customer class, the latest one will appear as Customer [2].
You can examine and manage the versions of a class using the Class Version Browser. To open a Class Version Browser, select a class in a browser and choose Browse Versions from the Class menu. If more than one version of a class has been created, the Class List in the spawned Class Version Browser displays the version number next to the class name.
Figure 12.7 Class Version Browser
The Class Version Browser’s menus are similar to the menus for the Class Browser, with a few exceptions. In the Class Version Browser, the Class menu includes the additional items Make Current and Migrate Instances; the Classes menu items Move To... is not available, and Remove... has more limited scope.
Remove... Remove the selected class version from this classes’ class History.
Make Current Makes the selected class version to be the current class version.
Migrate Instances Migrate all instances of the selected versions. Prompts you to select which version to migrate to. The user can only migrate to another version of the same class history, so if all versions are selected there is no migration destination and the item should be grayed out. Otherwise, prompt for the version to migrate to by popping up a list of versions not selected. Allow the user to cancel the operation by clicking a cancel button.
Adding and Modifying Methods
To add a method, select the Class, then select or create a Category for the new method. This displays the add method template. If you do not select a Category, the new method will be placed in the “unknown” category, which will be created if necessary.
Adding a method to a class, or modifying a method for a class, requires that you have write authorization to that class.
When running as a user other than SystemUser, you cannot add methods nor modify methods for any of the GemStone kernel classes (the predefined classes supplied with the GemStone system).
Public and Private Methods
GemStone includes both public and private methods. Public GemStone methods are fully supported with the specified behavior. Private GemStone methods are those implemented to support the public protocol; they are not supported, and are subject to change without notice.
Private GemStone methods are those whose selector is prefixed with an underscore (_), that explicitly say they are private within the method comment, or that are in a category labeled Private. They appear in the browsers along with the public methods, and you can display the source for them.
CAUTION
Private methods are subject to change. Do not depend on the presence or specific implementation of any private method when creating your own classes and methods.
Reserved and Optimized Selectors
The GemStone Smalltalk compiler optimizes certain frequently-used selectors. These selectors cannot be overridden in subclasses; the optimized code ignores any redefinitions. Some examples are ==, ifTrue:, and to:do:.
The specific list of selectors will vary by GemStone server product and version, and can be found in the GemStone Programming Guide for that version, Appendix A.
12.3 Fileout and Filein of Class and Method Definitions
It is often useful to store the GemStone Smalltalk source code in text files. Such files make it easy to:
- transport your code to other GemStone systems,
- perform global edits and recompilations,
- produce paper copies of your work, and
- recover code that would otherwise be lost if you are unable to commit.
File Out
To save GemStone code in a file, use any of the GemStone browser’s File Out As... or File Out Methods As... menu items.
You may file out all classes in a symbol dictionary, all methods without the class definitions within a symbol dictionary, a single class with its methods, just the methods of a single class, all methods within a single category, or a single method.
File In
To read and compile a saved file, use the File Browser menu item Gs-File In or GS-File it in, or a Workspace GS-File it in menu item.
Class definitions and methods that were filed out from a particular product and version may or may not file into a different GemStone product and version. You may need to edit the fileout text file if you wish to file in code from a different product or version.
Handling Errors While Filing In
If one of the modules that you’re filing in contains a GemStone Smalltalk syntax error, GemStone displays a compilation error notifier that contains the erroneous module in a text editor. If you correct the error and then choose Save, GemStone recompiles the module and then processes the rest of the file.
In the case of authorization problems, commands that the file-in mechanism doesn’t recognize, or other errors, GemStone displays a simple error notifier without an editor and stops processing the file.
Fileout text format
Saved GemStone files are written as sequences of Topaz commands. Example 12.1 shows a class definition in Topaz format. The details may vary according to the specific server version you are using.
Example 12.1
doit
Object subclass: 'Address'
instVarNames: #( street zip)
classVars: #()
classInstVars: #()
poolDictionaries: #()
inDictionary: UserGlobals
options: #()
%
! Remove existing behavior from Address
doit
Address removeAllMethods.
Address class removeAllMethods.
%
set compile_env: 0
! ------------------- Class methods for Address
! ------------------- Instance methods for Address
category: 'Accessing'
method: Address
street
"Return the value of the instance variable 'street'."
^street
%
category: 'Updating'
method: Address
street: newValue
"Modify the value of the instance variable 'street'."
street := newValue
%
category: 'Accessing'
method: Address
zip
"Return the value of the instance variable 'zip'."
^zip
%
category: 'Updating'
method: Address
zip: newValue
"Modify the value of the instance variable 'zip'."
zip := newValue
%
GemBuilder’s filing out and filing in facilities are intended for saving and restoring classes and methods without manual intervention. The Topaz fileout format, however, has further options for scripting. It is possible to create custom files that include commands to commit transactions, perform initialization, and to create and manipulate objects other than classes and methods. If you want to perform such tasks, refer to the Topaz Programming Environment for your server product and version.
The GemBuilder filein mechanism cannot execute the full set of Topaz commands.
Filein is limited to the following subset:
The GemBuilder file-in mechanism accepts the following commands, but does not execute them. In some cases, it adds a note to the System Transcript that the command is ignored:
If GemBuilder encounters any other Topaz commands it stops reading the file and displays an error notifier.
The filein mechanism does not display execution results, either. Instead, it appends information to the System Transcript about the files it reads and the classes and categories for which it compiles methods.
Filein/fileout and Characters outside the ASCII range
Fileout of server can be done conveniently from the GBS tools. The GemStone server also supports fileout directly, using topaz or by invoking the fileout methods on Behavior class.
When filing out server code using the GBS tools, VisualWorks normally will automatically encode the file as UTF-8, and interpret input files as UTF-8. Traditionally, fileout from the GemStone server is encoded in 8-bit ASCII, limited to Characters with codePoints in the range 0..255.
Code containing Characters with codepoints greater than 127, that is filed out from topaz as 8 bit ASCII, should not be filed in using GBS tools.
12.4 Connector Browser
Chapter 4 describes connectors, which allow an application developer to explicitly declare an association between a client class and a server class or between a root client object and a root server object. This section explains how to use GemBuilder’s Connector Browser to make and manage connectors interactively.
To open a Connector Browser, select Browse > Connectors from the GemStone Launcher. With this browser, you can:
- examine, create, and remove global or session parameters based connectors
- inspect the client or server object to which a connector resolves
- determine whether a specified connection is currently connected
- connect or disconnect a connector
- examine or modify the postconnect action associated with a connector
The Group Pane
The top pane is the Group pane; it allows you to select either global connectors or those associated with an individual session parameters. Global connectors are predefined to connect the GemStone server kernel classes with their client Smalltalk counterparts. When you select an item in this pane, the connectors defined for the selected item appear in the middle pane.
In the Group pane, the pop-up menu provides the following items:
update Refreshes the views and updates the browser; useful if you have made changes in other windows and need to synchronize the browser with them.
initialize (available only when Global Connectors are selected). Allows you to remove all connectors except those that connect kernel classes.
The Connector Pane
The middle pane is the Connector pane; it lists the connectors, their types, and descriptions in both the client and GemStone server Smalltalks. In the Connector pane, the popup menu offers the following items. Note options other than add... are only available when a connector is selected.
inspect Client Resolves and inspects the client Smalltalk object for the selected connector.
inspect Server Resolves and inspects the GemStone server object for the selected connector.
add... Adds a new connector, prompting for required information.
The Control Panel
The bottom pane is a control panel that allows you to change the connectVerification and removeInvalidConnectors configuration parameters and connect or disconnect objects.
The control panel has the following check boxes, radio buttons and selection lists:
Global verification Checking this sets the configuration parameter connectVerification to true. See connectVerification for details. We recommend that you turn on verification during development and turn it off for production systems.
Remove bad connectors
Checking this sets the configuration parameter removeInvalidConnectors to true. See removeInvalidConnectors for details.
Connected / Disconnected
Displays the connected status, and allows you to connect or disconnect the GemStone and client Smalltalk objects described by the connector. Applies to the current session.
Postconnect Action The postconnect action determines how GemBuilder sets the initial state of connected objects. Options are:
updateST initializes the client object using the current state of the GemStone server object.
updateGS initializes the GemStone server object using the current state of the client object.
forwarder makes the client object a forwarder to the GemStone server object.
clientForwarder makes the GemStone server object a forwarder to the client object.
none leaves the client object and the GemStone server object unchanged after their initial connection. This is the default and recommended setting for class connectors.
Connector Operations
Creating a new connector
1. Select a Global or a session parameters in the Group pane.
2. In the Connector (center) Pane, select add from the pop-up menu.
3. When prompted, specify the type of connector.
4. When prompted, specify the names of the client and server objects.
5. When prompted, specify the name of the dictionary for the server object.
Changing the postconnect action
1. Disconnect the objects by clicking on the Disconnected button.
2. Change the postconnect action as required.
3. Reconnect the objects by clicking on the Connected button.
Transfer data storage from client to server
If your application initially stores its data in the client, and you intend to store the data on the GemStone server but have not done so yet:
1. Create a connector or connectors for the root object(s) in the data set.
2. Select updateGS as the postconnect action for these connectors.
3. Log into the GemStone server so that GemBuilder can create the GemStone server replicates for the client Smalltalk data.
4. Inspect the GemStone server objects to be sure they have the intended values.
5. Commit the transaction and log out.
6. Select the connectors and change their postconnect actions to updateST so that future sessions will begin by using the stored GemStone server data.