5. Upgrading GsDevKit Applications

Previous chapter

Next chapter

This chapter describes the additional upgrade step that applies when upgrading an application that is using the Open-source Development Kit for GemStone/S 64 Bit (GsDevKit, previously referred to as Seaside or GLASS) to GemStone/S 64 Bit version 3.3.1.

If you are using the most recent version, from github.com/GsDevKit/GsDevKit_home, then you may use the upgrade scripts provided there to perform the entire upgrade, rather than using the instructions in this Installation Guide.

The complete process for upgrading GemStone is described in the relevant chapter of this Installation Guide; Chapter 4 for version 2.4.x and Chapter 2 for upgrade from 3.x. You will need to follow the steps in that chapter, which will note the point at which the GsDevKit upgrade takes place.

Due to the differences when GsDevKit is added to the GemStone/S 64 Bit environment, not all steps of the upgrade process apply. The upgrade instructions note the differences.

While the upgrade process below should work in most cases, some upgrade scenarios may require individual attention. If you encounter issues or have questions about the GsDevKit upgrade, send email to beta@seaside.gemstone.com.

Upgrade Procedure

After you have completed the GemStone/S 64 Bit image upgrade, as described in Chapter 2 or Chapter 4, you can upgrade your GsDevKit application.

After the GsDevKit upgrade is complete, you should return and complete the remaining upgrade steps as described in Chapter 2 or Chapter 4.

Configure the GsDevKit Upgrade

Do not perform this upgrade if you have not already completed the upgrade process through the upgradeImage step.

You should also have confirmed that your application code has been updated as required. This is particularly important when upgrading from version 2.4.x. The GemStone/S 64 Bit v2.x to v3.0 changes were extensive, and impacted most application code.

Before upgrading your GsDevKit application, you will need to configure your environment. The following variables in the UserGlobals of DataCurator should be reviewed and set as necessary:

#BootstrapSymbolDictionary
The symbolDictionary in which the root of your application-specific Seaside classes are located. By default, UserGlobals.

#BootstrapSymbolDictionaryName
The name of the symbolDictionary in which the root of your application-specific Seaside classes are located. By default, the name of what is set for #BootstrapSymbolDictionary

#BootstrapRepositoryDirectory
The directory in which your base GemStone classes exist. By default, GsPackageLibrary getMonticelloRepositoryDirectory. This normally resolves to $GEMSTONE/seaside/monticello/repository.

#BootstrapApplicationLoadSpecs
A collection of 4-element arrays. Each array includes:

  • the name of a configuration
  • the version of the configuration
  • an array of names of what to load from the configuration
  • the monticello directory.

The minimum required, and the default, is:
{ {'ConfigurationOfGLASS' . '1.0-beta.9.1' . #('default') . BootstrapRepositoryDirectory } }

#BootstrapExistingConfigurationList
A collection of configurations in your repository, which will be deleted and reloaded from the repository. By default, everything in the #BootstrapSymbolDictionary whose key begins with 'ConfigurationOf'. If you name your configurations differently, you will need to customize this list.

#BootstrapApplicationPostloadClassList
The set of classes that should be initialized after the reload. If the class is on this list, it will be sent #initialize after load, which may cause data loss. By default, an empty collection.

Example upgrade configuration script

The following script is an example of an GsDevKit upgrade customization.

Example 5.1 Example GsDevKit upgrade setup script
set user DataCurator pass swordfish
login
run
UserGlobals 
	at: #BootstrapRepositoryDirectory 
	put: GsPackageLibrary getMonticelloRepositoryDirectory.
true
%
run
UserGlobals
	at: #BootstrapApplicationLoadSpecs
	ifAbsent: [
		UserGlobals
			at: #BootstrapApplicationLoadSpecs
			put: {
				{ 'ConfigurationOfGLASS' . '1.0-beta.9.1' .
				#('default') . BootstrapRepositoryDirectory } .
			}.
		].
true
%
commit
logout
 

Perform the Upgrade

The GsDevKit upgrade is performed by the script upgradeSeasideImage, which is located in the $GEMSTONE/seaside/bin subdirectory.

Prior to executing upgradeSeasideImage, you should have up Global variables to customize the upgrade, as described above.

upgradeSeasideImage [-c <tempObjCacheSize>] [-s <stoneName>] [-u <gemstoneUser>] [-p <password> ]
-c <tempObjCacheSize> sets the size of the GEM_TEMPOBJ_CACHE_SIZE; if this is not used, the script will default to use a value of 100000.
-s <stoneName> sets the name of the running stone to upgrade; if this option is not used, the script will default to gs64stone.
-u <gemstoneUser> specifies the GemStone user name, if seaside was installed as a user other than DataCurator. If not used, defaults to DataCurator.
-p <password> the password of the GemStone user that installed seaside. If not used, defaults to swordfish.

For example,

% $GEMSTONE/seaside/bin/upgradeSeasideImage -s stoneName331

The script will prompt you to press the return key to begin.

The script should complete with the message:

Seaside Upgrade completed. No errors detected.

Load your Application Code

After upgrade has successfully completed, load your application code.

Complete the Upgrade Process

Return to the appropriate chapter describing the upgrade process and follow the remaining steps.

Previous chapter

Next chapter