3. Changes in GemStone Smalltalk

ClassOrganizer >> newExcludingGlobals

This method allows you to perform ClassOrganizer queries that do not return results exclusive to Globals. This can be used, for example, to find application methods that reference GsHostProcess or JsonParser classes (which may need to be recompiled; see the Installation Guide upgrade instructions), without including kernel methods that do not need recompiling.

ClassOrganizer >> newExcludingGlobals replaces the private method _newExcludingGlobals, which was available in some recent releases. Note that _newExcludingGlobals did not reliably exclude methods on classes in Globals.

GsNMethod >> recompileFromSource

This method has been added for convenient recompilation of a method from source code, such as the recompile needed for GsHostProcess and JsonParser. Existing recompile methods were designed for recompiling after bytecode changes; since they relied on the existing literal references, they did not update references to the obsolete class.

Note that if the symbolList of the user that is executing the recompile resolves literal names to different objects than the original compile, this may result in unexpected changes in behavior. Depending on the complexity of your application’s use of users’ symbolLists, you may wish to examine the source code before recompiling.

Added method Behavior >> compileMethod:category:environmentId:

The following method has been added, allowing you to compile a method using the current symbol list:

Behavior >> compileMethod: sourceString category:  aCategoryString environmentId: environmentId

#logCreation and logging class creation

The option #logCreation can be included in the options: of a class creation message, which results in the class creation being logged (using GsFile gciLogServer:). The primary purpose was for tracking class creation during build/upgrade filein. This option is not persistent and not printed (reported by Class >> definition), and thus was not retained if a class was filed out and in.

Now, you may set the key #GsClass_logCreation in SessionTemps, to force logging of all class creations for the lifetime of the session, using an expression such as:

SessionTemps current at: #GsClass_logCreation put: true

In the absence of this setting, the behavior is unchanged.

Improvements to filein using GsFileIn

GemStone supports filein of topaz-format source code using the class GsFileIn. This provides a functionality similar to topaz input, but permits only a subset of the full set of topaz commands. GsFileIn allows you to filein GemStone code programmatically, entirely from within GemStone code.

GsFileIn has been extensively revised. With v3.7, GsFileIn now supports source files that include extended characters encoded as Utf8; and performance has been greatly improved.

While instances of GsFileIn are not normally persisted, on upgrade, any existing instances become instances of ObsoleteGsFileIn.

The GsFileIn Class >> from*: API has been streamlined. While fromServerPath: and fromClientPath: may be used, the preferred methods (methods whose names are more accurate) are fromGemHostPath: and fromGciHostPath:, respectively. The method GsFileIn >> fromStream: has been added, to allow filein from streams.

For more details on GsFileIn, see the class comment, and methods in the image.

SystemUser SymbolList Changes

In v3.6.x, SystemUser’s SymbolList (visible when logged in as SystemUser), included a number of additional SymbolDictionaries, including GsCompilerClasses, ObsoleteClasses, RowanKernel, and in some versions GemStone_Portable_Streams and GemStone_Legacy_Streams. This facilitated work, or were artifacts of, the transition to Rowan-based code management.

For 3.7, all these dictionaries have been removed; the classes are located in subdictionaries within Globals, as needed.

Money example

An example of using this feature is the example at:

$GEMSTONE/examples/smalltalk/Money.gs

This example demonstrates using Special56bit0 to implement a Special Money class encoding an amount and an integer currency ID, to support US and Canadian Dollars, Euro and Yen. Note that this is a trivial example class, and does not provide the necessary currency support for a real-world application.

This example must be filed in as SystemUser. It creates the Money class in the Published dictionary. Methods on the resulting Money class can be edited by a user with access to the DataCuratorObjectSecurityPolicy.

InstVarMappingArray

The existing InstVarMappingArray class has been modified and updated, and an instance can be created and customized directly for use by multi-threaded migration. An instance of InstVarMapping is defined for a single specific class, and specifies migratation of instance variables defined on that class and inherited instance variables in the same way.

Note that ordinary object based migration continues to use instances of InstVarMappingArray without specific customization.

The following methods have been added:

InstVarMappingArray >> mapInstVarNamed: oldName to: newName
The value at the instance variable named oldName in the old class should be migrated to the instance variable named newName in the new class.

InstVarMappingArray >> mapInstVarToNil: newName
The migration should not retain the value of any instance variable newName present in the instance of the old class. After migration; the object will have a nil value at this instance variable.

The origin and target classes are now in instance variables, and methods have been added to access these:

InstVarMappingArray >> oldClass

InstVarMappingArray >> newClass

Example

For example, to create a mapping from OrigClass to NewClass that moves the value of the instance variable oldName to the location of the instance variable newName in the NewClass:

| im |

im := InstVarMappingArray mappingFrom: OrigClass to: NewClass.

im mapInstVarNamed: #oldName to: #newName.

im mapInstVarToNil: #oldName.

im preserveDynamic: false.

SystemRepository migrateMt: { im }

Note that if you do not specify to set #oldName to nil, the value at oldName will be retained in the migrated instance (now a NewClass) in #oldName, as well as being set in the instance variable #newName.

Differences from GsFile

FileSystem supports a superset of the functions provided by GsFile for server files, and the API is significantly different.

Some differences:

• FileSystem is implemented using multiple classes to provide a flexible and portable API, while GsFile is implemented as a single class with fixed behaviors.
• FileSystem is implemented based on an FFI interface to the OS file system functions, while GsFile is implemented with user actions (for historic reasons) and C primitives.
• On error, FileSystem signals an appropriate error; GsFile functions return nil and require you to query for the error details.
• FileSystem does not support operations on the GCI client (for example, reading files on a Windows client), while GsFile does.

FileSystem is supported with Linux on x86 and ARM, and macOs on x86 and Apple Silicon. FileSystem is not supported on AIX; on AIX, you must continue to use GsFile.

Primary API classes

There are a few main entry points for FileSystem.

• FileReference

FileReference is the primary entry point for file and directory operations. You may create files using FileReference >> / , FileReference >> @, aString asFileReference, or by using FileSystem class protocol. FileReferences can also be created from another instance of FileReference. The following are all equivalent:

'/gshost/test/foo.txt' asFileReference

FileReference / '/gshost/test/foo.txt'

FileReference / 'gshost' / 'test' / 'foo.txt'

FileReference disk @ '/gshost/test/foo.txt'

FileSystem disk / '/gshost/test/foo.txt'

'/gshost/test/' asFileReference / 'foo.txt'

The FileReference that is created prints as:

FileReference disk @ '/gshost/test/foo.txt'

There are a great many supported operations, including both information about the file or directory, and operations on that file or directory. Note that much of the API is on the superclass, AbstractFileReference. The methods include:

• report if the receiver is a file or directory, and for directories, report details on the contained children (files or directories).
• return details of the path, filename, and extension
• return information about a file, such as size, permissions, modificationTime, etc.
• open a read or write stream on the contents, including encoded and binary streams.

Operations on the contents of a FileReference will normally use streams. Methods such as readStream and writeStream return instances of Zinc-based streams, in this case ZnCharacterReadStream or ZnCharacterWriteStream. For example:

rdStream := 'gshost/test/foo.txt' asFileReference readStream.

[rdStream atEnd] whileFalse: 

     [report add: rdStream nextLine; lf.].

rdStream close. 

Variants such as readStreamDo: and writeStreamDo: automatically close the file after performing the block operation.

By default, these streams provide automatic UTF-8 encoding, although method variants allow you to specify an encoder to support legacy 8-bit encoding.

Binary read and write streams created using binaryReadStream and binaryWriteStream create instance of FsBinaryFileStream, allowing byte-based operations with no encoding.

• FileLocator

FileLocator provides similar file operations to FileReference, but the file or directory does not need to have an explicit full path. The location for a FileLocator instance can be relative to your environment; for example, the working directory, the directory containing the extent files, or the directory containing gem logs. This allows you to move code between environments without requiring explicit management of the paths. For example the following code does not need to be changed if executed in different environment:

outFile := FileLocator home / 'output.txt'.

outFile 

writeStreamDo: [:stream | stream nextPutAll: 'test results'] 

ifPresent: [FileAlreadyExistsException signalWith: outFile]

You can see the available environment-dependent origins using FileLocator class >> supportedOrigins; class methods are available for all, including home, cache, temp, userData, tranlog, preferences, extent1Directory, extent1, documents, desktop, and workingDirectory.

To find the resolved value of the FileLocator, you can send the message absolutePath; this returns an instance of a kind of Path.

FileLocator extent1 absolutePath printString

%

Path / 'gshost' / 'GemStone3.7' / 'data' / 'extent0.dbf'

FileLocator understands most of the methods available for FileReference.

• FileSystem

While the primary entry point is FileReference, the class FileSystem can provide a way to define a FileReference. FileSystem supports ordinary disk based file systems and in-memory file systems.

FileSystem has a number of useful methods for defining FileReferences. For example:

FileSystem disk
returns a disk-based FileSystem, which can be used with @ or / to create a FileReference, e.g. FileSystem disk / '/gshost/test/foo.txt'.

FileSystem memory
returns an in memory-based FileSystem, which can be used with @ or / to create a FileReference, e.g. FileSystem memory / 'foo' / 'bar'.

FileSystem workingDirectory
creates a FileReference to the current working directory (disk-based).

FileSystem includes instance methods that allow you to perform a number of file and directory operations, but these methods are subject to change or removal in later releases. Use instances of FileReference to perform file and directory operations other than creating references and setting the working directory.

• FsFileDescriptor

FsFileDescriptor represents the file itself. FileReference open: methods return an instance of this class, which can be used to perform basic file operations.

FsFileDescriptors read and write ByteArrays rather than strings.

Supporting Classes

SSH with GsSshSocket

sshSock := GsSshSocket newClient.

sshSock connectToHost: hostnameOrIP timeoutMs: 2000.

sshSock userId: userName; password: userPassword.

sshSock disableHostAuthentication.

sshSock sshConnect.

sshSock close

result := sshSock executeRemoteCommand: 'uptime'.

nbExecuteRemoteCommand:

hasCommandInProgress

nbRemoteCommandResult

nbRemoteCommandResultReady

SFTP with GsSftpSocket

sshSftpSock := GsSftpSocket newClient.

sshSftpSock connectToHost: hostnameOrIP timeoutMs: 2000.

sshSftpSock userId: userName; password: userPassword.

sshSftpSock disableHostAuthentication.

sshSftpSock sshConnect.

sshFtpSock close

GsSftpSocket >> remoteFileExists: aFileOrDirectory 

GsSftpSocket >> currentRemoteDirectory  

GsSftpSocket >> createRemoteDirectory: dirname 

GsSftpSocket >> createRemoteDirectory: dirname mode: modeInt  

GsSftpSocket >> contentsOfRemoteDirectory: dirname 

GsSftpSocket >> contentsOfRemoteDirectory: dirname matchPattern: aString  

GsSftpSocket >> renameRemoteFile: oldName to: newName 

GsSftpSocket >> removeRemoteFile: filename 

GsSftpSocket >> removeRemoteDirectory: dirname 

sshSftpSock := GsSftpSocket newClient.

sshSftpSock connectToHost: hostnameOrIP timeoutMs: 2000.

sshSftpSock userId: userName; password: userPassword.

sshSftpSock disableHostAuthentication.

sshSftpSock sshConnect.

remoteSftpFile := GsSftpRemoteFile 

openRemoteFileReadOnly: remoteFileName 

withSftpSocket: sshSftpSock.

localFile := GsFile openWriteOnServer: localFileName.

bytes := remoteSftpFile readAllInto: localFile.

localFile close.

sftpFile close.

Support for pre-shared keys

Pre-shared keys are symmetric keys shared in advance among the communicating parties. Support has been added to GsSecureSocket for pre-shared keys. The callback protocols are dependent on the TLS version; methods have been added to define and manage the version, see TLS Version handling.

GsSecureSocket >> setPreSharedKey: aByteArray
Sets the Pre-Shared Key (psk) for the connection to be the bytes contained in aByteArray. Raises an exception if the receiver is already connected or listening for a connection. aByteArray must have a size of at least 8 bytes, not more than 64 bytes and be a multiple of 8 (16, 24, 32 etc). A key size of at least 16 bytes is recommended.

Invoking this method an additional time overwrites any previously stored PSK. To clear a the previously set PSK, invoke this method with an argument of nil. Returns true on success.

Anonymous TLS

Anonymous TLS connections are exposed to man-in-the-middle attacks and are therefore NOT recommended for most applications.

TLS Version handling

The added methods to set and get actual, maximum and minimum TLS version accept the following argument symbols for tlsVersionStringOrSymbol:

• #TLS_VERSION_DEFAULT = use any supported TLS protocol. This is the default behavior.
• #TLS1_VERSION = TLS version 1.0
• #TLS1_1_VERSION = TLS version 1.1
• #TLS1_2_VERSION = TLS version 1.2
• #TLS1_3_VERSION = TLS version 1.3

Modified SNI example code in image

To support running the SNI example on RedHat compatible Linux as well as Ubuntu, the method:

GsSecureSocket class >> httpsClientExampleForHost:certificateDirectory:withSniName:

has been removed; it is replaced by the new method:

GsSecureSocket class >> httpsClientExampleForHost:withSniName:

which invokes the added method:

GsSecureSocket class >> setCaCertLocation
Certificate verification for the example is designed to Ubuntu and RedHat-compatible Linux. Look for the trusted CA cert file on the current host. If we find it, use it. If we do not, disable cert verification so the examples work correctly.

Ubuntu: /etc/ssl/certs/ca-certificates.crt

Red Hat-compatible: /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

Returns the CA cert file used or nil if no file was found and certificate verification has been disabled.

AzureDataKeys

A key is created using code such as:

cred := AzureCredentials

newWithClientId: '1234567890'

clientSecret: 'abcdefghij'

tenantId: '1a2b3c4d5e6f7g8h'.

key := AzureDataKey

createKeyUsingAzureCredentials: cred

keyVaultUrl: 'https://keyvaultname.vault.azure.net/'

keyName: 'keyname'.

This instance of AzureDataKey should be persisted in the database for ongoing use for encryption and decryption. If the key instance is lost, any data that was encrypted with that key cannot be decrypted, and is permanently inaccessible, even if the credentials are available.

AzureCredentials can be recreated as needed. Since a persisted instance of AzureDataKey is locked in newly logged in sessions, the same or a recreated instance of AzureCredentials will be needed to unlock a persisted instance of AzureDataKey.

AzureDataKey >> lock

AzureDataKey >> unlockWithAzureCredentials: anAzureCredentials

AzureDataKey >> isLocked

AzureDataKey >> isUnlocked

Encryption/decryption

Encryption and decryption are done by sending a request to the (unlocked) AzureDataKey.

Encryption is performed using AES-OCB authenticated encryption, which ensures data that has been successfully decrypted has not been modified in any way.

AzureDataKey >> encrypt: srcByteObj into: destByteObj
Uses the receiver to encrypt srcByteObj and stores the resulting encrypted bytes into destByteObj as a Base64 string. srcByteObj must be a non-empty byte object. destByteObj must be a mutable byte object; any contents will be overwritten.

AzureDataKey >> encryptAndErase: srcByteObj into: destByteObj
Encrypt srcByteObj, erasing all data in srcByteObj, and store the resulting encrypted bytes into destByteObj as a Base64 string. srcByteObj must be a non-empty byte object. destByteObj must be a mutable byte object; any contents will be overwritten.

AzureDataKey >> decrypt: srcByteObj into: destByteObj
Uses the receiver to decrypt srcByteObj and stores the resulting decrypted bytes into destByteObj. srcByteObj must be a non-empty byte object containing Base64 encrypted text. destByteObj must be an mutable byte object.; any contents will be overwritten.

For example:

| credentials key data encryptedData decryptedData |

credentials := AzureCredentials

newWithClientId: '1234567890'

clientSecret: 'abcdefghij'

tenantId: '1a2b3c4d5e6f7g8h'.

key := AzureDataKey

createKeyUsingAzureCredentials: credentials

keyVaultUrl: 'https://keyvaultname.vault.azure.net/'

keyName: 'keyname'.

data := 'Please excuse my dear aunt Sally'.

encryptedData := String new.

decryptedData := String new.

key encrypt: data into: encryptedData.

key decrypt: encryptedData into: decryptedData.

Key rotation

Azure Key Vault provides the ability to do key rotation for improved security. You may update an instance of AzureDataKey to be associated with a new keyName, vault, and credentials, using the following method. To ensure that the change will be committed if successful, this method write locks the receiver and commits the session, so this requires that there are no uncommitted changes.

AzureDataKey >> changeKeyNameTo: newName inKeyVault: theVault usingCredentials: theCreds
Atomically update the receiver to use the key name newName, in the vault theVault, which is accessed with theCreds in a single operation, and commit. The receiver must be unlocked, the session must not have uncommitted changes, and the session must be able to write lock the receiver.

The key newName must already exist in the given vault. You may use the existing vault and credentials to rotate the key within the same vault, or use different parameters.

For example:

| key credentials data encryptedData decryptedData |

credentials := AzureCredentials

newWithClientId: '1234567890'

clientSecret: 'abcdefghij'

tenantId: '1a2b3c4d5e6f7g8h'.

key := AzureDataKey

createKeyUsingAzureCredentials: credentials

keyVaultUrl: 'https://keyvaultname.vault.azure.net/'

keyName: 'keyname'.

data := 'Please excuse my dear aunt Sally'.

encryptedData := String new.

decryptedData := String new.

key encrypt: data into: encryptedData.

key

changeKeyNameTo: 'key2' 

inKeyVault: 'https://keyvaultname.vault.azure.net/' 

usingCredentials: credentials.

key decrypt: encryptedData into: decryptedData.

data = decryptedData

Making a copy of a key

An AzureDataKey can be copied. The copy of an AzureDataKey has the same locked state as the original, and can be unlocked using the same credentials.

AzureDataKey >> copy
Answer a new object which is a deep copy of the receiver. The lock state of the receiver is preserved when copied, i.e.: if the receiver is unlocked the resulting copy will also be unlocked.

Key equality

AzureDataKey objects are considered equal (=) if they have the same vault, key name, and the same encrypted key string. Lock state does not affect equality.

Tracing Azure calls

The following environment variables can be defined in the client environment to print trace information on Azure calls. Setting these GemStone environment variables enables Azure environments variables to perform the debugging; note that the numeric values are defined by Azure, rather than conforming with GemStone’s other debugging environment variables.

GS_AZURE_LOG_DIR
A directory in which to create the azure log file

GS_AZURE_LOG_LEVEL
The level of logging. Valid values are 1, 2, 3, 4. The meanings of these values are:

1 – Verbose: Logging level for detailed troubleshooting scenarios

2 –Informational: Logging level when a function operates normally.

3 – Warning: Logging level when a function fails to perform its intended task.

4 – Error: Logging level for failures that the application is unlikely to recover from.

If both these environment variables are set to valid values, Azure creates a log file named

azure_sdk_YY-MM-DD-HH-mm-ss.log

where YY-MM-DD-HH-mm-ss are timestamp values, in the directory specified by $GS_AZURE_LOG_DIR.

Float printing improvements

GemStone now includes the library double-conversion, which allows more control over floating point display. Float and SmallDoubles such as 9.45, that previously displayed as the technically correct, but not optimal, ’9.449999999999999’, now display as ’9.45’. (#47003)

In addition, Doubles may have up to 17 significant decimal digits, but the earlier code limited this to 16 decimal places. For example, a float created from ’7.6000000000000001’ was previously printed as 7.600000000000001, and is now 7.6000000000000005. (#46855)

Converting Non-specials in special range

A special object is one in which the OOP encodes the value, and thus requires no repository space; this is a canonical form of that value. A number of magnitude classes have subclasses with the prefix ’Small’, which provide a special/canonical form of a subset of that class’s potential values. While new values are created in canonical form, it is possible to have non-canonical instances that have an exactly equivalent canonical value. For example, an upgraded application may have an instance of Fraction with the value 1/3, rather than a SmallFraction with the value 1/3.

To convert a non-canonical to the canonical equivalent, the method asCanonicalForm has been added. This either returns self, or the canonical object exactly equivalent to the receiver. Specific implementations apply to Float, Date, DateAndTime, Time, Fraction, LargeInteger, and ScaledDecimal.

Note that this cannot perform a conversion in place; you must modify the object referring to the non-canonical value to refer to the canonical value.

highBit now ANSI-compliant

The method Integer, LargeInteger, and SmallInteger>>highBit previously returned nil for a zero receiver. Now, this method returns 0 for a zero receiver, as specified by the ANSI spec.

Other added method

The following method has been added:

SmallInteger >> minimum32bitInteger
Return the minimum value representable by a 32bit signed integer

New ReadByteStream classes optimized for Strings

The class ReadByteStream, and the implementation classes ReadByteStreamPortable and ReadByteStringLegacy classes, have been added. This provides a ReadStream that is optimized for performance, and limited to holding kinds of String, MultiByteString, or ByteArray.

The API of ReadByteStream is largely the same as the existing ReadStream classes.

In Unicode mode, String auto-conversion to Unicode16

When the repository is in Unicode Comparison Mode, when an existing instance of String is modified such that it now includes a Character with any codePoint greater than 255, it is auto-converted to an instance of Unicode16. This includes when sending add:, addAll:, at:put:, and similar protocol.

Auto-conversion avoids subsequent performance impacts of comparisons using the ICU library, since strings must be converted for comparison.

Methods that operate on Bytes rather than Characters, such as String >> addAllBytes: and String class >> withBytes:, are not subject to this auto-conversion. Instance of DoubleByteString are not affected.

codePointAt:put: now performs auto-conversion if needed

Previously, sending codePointAt:put: to a String or DoubleByteString, with a codePoint that is out of range for that class, resulted in an OutOfRange error.

Now, the receiver will be transparently converted to the class that can contain the given codePoint; that is, converted from a String or DoubleByteString to a DoubleByteString or QuadByteString).

Empty Unicode7 string literals now canonicalized

In traditional String comparison mode, the string literal '' creates an instance of String, which is canonicalized (to the kernel OOP 233473). In Unicode comparison mode, in which '' creates an instance of Unicode7, these were previously not canonicalized. Now, these are canonicalized (to kernel OOP 165377).

Support for Lz4 encode/decode added to String and ByteArray classes

The following methods have been added, which allow Lz4 compression into a ByteArray, and decompression from Lz4-compressed data in a ByteArray into a byte-format object; normally but not necessarily a kind of String, MultiByteString, or ByteArray.

Compressing a multi-byte character object converts it to a little endian format before compressing, and decompression assumes the data is in little endian format.

You cannot compress, nor decompress into, a Symbol, DoubleByteSymbol or QuadByteSymbol.

Note that the compressed form does not distinguish the original class; for example, String or DoubleByteString; you must specify the correct class in the argument to the decompress method.

ByteArray, String, MultiByteString >> compressWithLz4: opCode
Compress the receiver with lz4 compression, and return an instance of ByteArray containing the compressed bytes. Compression modes include 0/frame mode and 1/blockmode; frame mode should normally be used.

ByteArray >> decompressWithLz4IntoNewInstanceOf: aClass decompressedSize: aSize
Decompress the receiver using lz4 and store the resulting bytes into a new instance of aClass. aClass must be a byte format Class. The lz4 compression mode (block or frame) used to compress the data is automatically detected by this method. aSize is a SmallInteger which indicates the size (in characters, not bytes) of the data when decompressed. If the contents were compressed using lz4 frame mode, aSize may be set to 0 indicating the decompressed size is not known. On success, returns a new instance of aClass containing the decompressed data.

ByteArray read/write of binary numbers in native format

The following methods have been added to allow you to read and write numeric values as raw bytes into a ByteArray in the current native byte order. Values are written in native format, and read as if in native format: no swizzling is done.

Note that there are existing methods in ByteArray to write and read numeric values; these methods read and write in big endian format, regardless of platforms.

ByteArray >> unsigned16AsNativeAt: startIndex

ByteArray >> unsigned32AsNativeAt: startIndex

ByteArray >> unsigned64AsNativeAt: startIndex

ByteArray >> signed16AsNativeAt: startIndex

ByteArray >> signed32AsNativeAt: startIndex

ByteArray >> signed64AsNativeAt: startIndex

ByteArray >> doubleAsNativeAt: startIndex

ByteArray >> floatAsNativeAt: startIndex

ByteArray >> signed16At: startIndex putAsNative: anInteger

ByteArray >> signed32At: startIndex putAsNative: anInteger

ByteArray >> signed64At: startIndex putAsNative: anInteger

ByteArray >> unsigned16At: startIndex putAsNative: anInteger

ByteArray >> unsigned32At: startIndex putAsNative: anInteger

ByteArray >> unsigned64At: startIndex putAsNative: anInteger

ByteArray >> doubleAt: startIndex putAsNative: aDouble

ByteArray >> floatAt: startIndex putAsNative: aFloat

The existing ByteArray methods at:put:signed:width: and at:signed:width: now accept additional width: arguments of 512, 1024, or 2048, which specify native format with 2, 4, or 8 bytes, respectively.

Added methods to return hashes as ByteArrays

The following methods have been added to CharacterCollection and ByteArray; these are similar to existing methods with the added "Bytes", and return the results in a ByteArray.

md5sumBytes
Return the 128 bit MD5 checksum of the receiver as a ByteArray. Computation is per RFC 1321 , http://www.ietf.org/rfc/rfc1321.txt, using L. Peter Deutsch's C implementation from: http://sourceforge.net/projects/libmd5-rfc/
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha1SumBytes
Return the 160 bit SHA1 checksum of the receiver as a ByteArray. Computation is per FIPS PUB 180-3: http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha256SumBytes
Return the 256 bit SHA256 checksum of the receiver as a ByteArray. Computation is per FIPS PUB 180-3: http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha3_224SumBytes
Return the SHA3 224 bit checksum of the receiver as a ByteArray. Computation is per FIPS PUB 202: https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha3_256SumBytes
Return the SHA3 256 bit checksum of the receiver as a ByteArray. Computation is per FIPS PUB 202: https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha3_384SumBytes
Return the SHA3 384 bit checksum of the receiver as a ByteArray. Computation is per FIPS PUB 202: https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha3_512SumBytes
Return the SHA3 512 bit checksum of the receiver as a ByteArray. Computation is per FIPS PUB 202: https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

sha512SumBytes
Return the 512 bit SHA512 checksum of the receiver as a ByteArray. Computation is per FIPS PUB 180-3: http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf.
For DoubleByteString and QuadByteString, the computation is based on viewing the string as a ByteArray holding big-endian characters.

Utf8 now disallows #readStream

The #readStream method, previously inherited from SequenceableCollection, has been disallowed in Utf8. Utf8 is intended to be only used in the encoded form; you should decode this prior to creating a readStream on it.

Other Changes

Upgrade impacts

Compiled methods that contain references to the JsonParser class in an earlier version, will refer to JsonPetitParser after upgrade and continue to work as before. Provided you are only using the JsonParser to parse JSON, it is optional to get the improved performance by recompiling methods that reference the JsonParser class by name.

If you are using JsonParser as part of a PetitParser customization, references to the class by name must be updated to refer to ‘JsonPetitParser’ instead of ‘JsonParser’. It is recommended to edit the source of methods that reference JsonParser class to reference JsonPetitParser, and edit the superclass of subclasses of JsonParser.

If you have subclasses of JsonParser that must be filed in, these will be compiled and refer to the new JsonParser class. If this subclass directly references inherited instance variables, compilation of those methods will fail; and depending on the specific modifications may or may not be functional. In most cases before filein, you should modify the code on disk to refer to JsonPetitParser.

See the Installation Guide for v3.7, Upgrade chapter, for recompilation details

GsTsExternalSession no longer requires cpp/gcc/g++

Previously, GsTsExternalSessions computed the FFI calls for the GciTsLibrary on demand, using cpp to parse gcits.hf. This required cpp, and the gcc/g++ compilation environment; including for production use of GsTsExternalSessions.

Now, the FFI calls are precomputed for the current version, and provided in a new file that is loaded during upgrade, $GEMSTONE/upgrade/GciTsLibrary.dat.

Note that this applies to GsTsExternalSessions that login with the same GemStone version as the current Gem. For logins to Stones running a different version of GemStone/S 64 Bit, gcits.hf still must still be parsed, and cpp/gcc/g++ continues to be required.

Added methods for GsTsExternalSession

The following methods have been added:

GsTsExternalSession >> debugGem: processId token: anInteger
Use GciTsDebugConnectToGem instead of GciTsLogin to establish a connection. Arguments should be copied from the DEBUGGEM printout in a topaz .out file or log file. All normal login arguments are ignored.

GsTsExternalSession >> newUtf8String: aUtf8 toUnicode: aBoolean
Create a new instance of Utf8 (if aBoolean is false) or a Unicode7, Unicode16 or Unicode32 (if aBoolean is true), in the external session, containing the contents of aUtf8. Returns the oop of the object that was created in the external session.

GsTsExternalSession >> releaseOop: anOop
Queue anOop (an oop in the external session) to be released from the ExportSet of the remote session; once 100 oops have been released, the oops are releaseed, allowing the objects to be garbage collected.

GsTsExternalSession >> releaseOops: anArray
Release the oops in anArray (oops in the external session) from the ExportSet of the remote session, allowing the objects to be garbage collected.

GsTsExternalSession >> send: aSelector to: rcvrOop withOops: anArray
The same as send:to:withArguments:, but the arguments are already in the form of oops.

Return value from GsTsExternalSession >> waitForReadReadyTimeOut:

Previous, the method GsTsExternalSession >> waitForReadReadyTimeOut: msToWait returned self for success, and signaled an error if the timeout expired or an error occurred.

Now, this method returns true on success, false if there was a timeout, and signals an error if there was an error.

Easier to use GEM_HALT_ON_ERROR in external sessions

The default for haltOnErrNum has been changed to -1, to allow the Gem’s configuration file setting for GEM_HALT_ON_ERROR to be in effect for external sessions.

ProfMonitor improved formatting for object creation tree report

The tree report produced when doing object creation tracing in ProfMonitor or ProfMonitorTree has improved formatting for deeper trees.

GsSecureSocket example updates

The GsSecureSocket class method

httpsClientExampleForHost:certificateDirectory:withSniName: 

has been renamed to

httpsClientExampleForHost:withSniName:. 

The following methods has been added:

GsSecureSocket class >> setCaCertLocation
On linux: try to find the trusted CA cert file on this host. If we find it, use it. If we do not, disable cert verification so the examples work correctly.

isValidIdentifier, validateIsIdentifier optimized

The following methods are now implemented in primitives:

CharacterCollection >> isValidIdentifier

Object >> validateIsIdentifier

Other Added methods

GsFile >> beforeEnd
Answer true if the receiver is not positioned at the end, false otherwise

GsFile >> print: anObject
Writes the print representation of the argument to the GsFile receiver instance.

GsHostProcess >> readOutErr
Assuming both out and err are sockets, attempt to read from both and return combined result.

GsHostProcess >> redirectStderrToStdout
This should be used rather than stderrPath: if you want both stdout and stderr redirected to the same file.

GsNetworkResourceString >> gemConfig: aString
Include a -C configuration definition for the receiver. aString should be a valid -C argument; for example, 'GEM_TEMPOBJ_CACHE_SIZE=100MB;'.

Array >> copyNotNilFrom: startIndex to: stopIndex
Return an Array containing the non-nil elements that are within the specified offsets of the receiver.

Array >> indexOfNotNil: startOffset to: endOffset
If startOffset <= endOffset, returns the first offset within in the specified range of a non-nil element of the receiver. If startOffset > endOffset, returns the last offset within the specified range of a non-nil element of the receiver. Returns zero if all are nil. Intended for use only on Arrays of size <= 2000. Performance on larger arrays will be slow.

TestAsserter >> assert: anObject identical: otherObj
Assert that two objects are identical.

TestAsserter >> fail
Cause the test to report failure unconditionally

TestAsserter >> fail: descriptionString
Cause the test to report failure unconditionally, with the given description.

AbstractCharacter removed

The abstract class AbstractCharacter has been removed; Character superclass is now Magnitude. The AbstractCharacter definition is now in ObsoleteClasses.

Newly deprecated Methods

The following methods are newly deprecated. See the deprecation message for the replacement.

GsProcess >> stepIntoFromLevel:

GsProcess >> stepOverFromLevel:

GsProcess >> stepThroughFromLevel:

GsProcess >> terminateTimeoutMs:

GsProcess >> threadRubyEnvId

System >> sessionIdHoldingGcLock 

Obsolete Classes not in new images

In a new image, Globals will not include the long-obsolete placeholder classes:

GsfClassDefinitionInfo

GsfModificationLog

In a new image, (Globals at: #ObsoleteClasses) will not include the following classes:

ObsoleteConstrainedPathEvaluator

ObsoleteConstrainedPathTerm

ObsoleteEqualityIndexQueryEvaluator

ObsoleteIdentityIndexQueryEvaluator

ObsoleteIndexedQueryEvaluator

ObsoletePathEvaluator

ObsoletePathSorter

ObsoleteSetValuedPathEvaluator

ObsoleteSetValuedPathTerm

These will continue to exist in upgraded images.

Removed Public Methods

The following methods have been removed, associated with changes mentioned elsewhere in these release notes:

CPreprocessor >> defaultSparcSolarisDefinitions

CPreprocessor >> defaultX86SolarisDefinitions

Breakpoint class >> trappable:

GsSecureSocket class >> httpsClientExampleForHost:

   certificateDirectory:withSniName:

GsTestCase >> assert:isEquivalentTo:

Object >> removeObjectFromBtrees

Removed Previously-deprecated Methods

The following methods were previously deprecated, and have been removed:

ExecBlock >> valueNowOrOnUnwindDo:

Repository >> shrinkExtents

System class >> cacheStatisticsDescription

Removed Private Methods

AbstractException >> _signalAsync

AbstractException >> _signalFromPrimitive:

AbstractException >> _signalGcFinalize

AbstractException >> _signalTerminateProcess

AbstractException >> _signalTimeout

AbstractException >> _signalWith:

Behavior >> _transientSessionMethodBehaviorsCacheName

CCallout class >> _errno:

CharacterCollection >> _validIdentifier:

ClassOrganizer class >> _newExcludingGlobals

Delay >> _activate

ExecBlock >> _valueNowOrOnUnwindDo:

ExecBlock >> _valueNowOrOnUnwindDoPrim:

GsFileIn >> compileMethodIn:

GsFileIn >> fileStream:

GsFileIn class >> fromNestedClientPath:to:

GsFileIn class >> fromNestedPath:on:to:

GsFileIn class >> fromNestedServerPath:to:

GsFileIn class >> _fromStream:

GsFileIn class >> _fromStream:to:

GsNMethod >> _breakOperation:forStepPoint:

GsNMethod >> _setBreakAtIp:operation:frame:process:

GsNMethod >> __setBreakAtIp:operation:frame:process:

GsNMethod class >> _setBreakAtIp:operation:frame:process:

GsProcess >> _activate

GsProcess >> _continue

GsProcess >> _finishTermination

GsProcess >> _isRubyThread

GsProcess >> _serviceTerminationInterrupt

GsProcess >> _stepOverFromLevel:

GsProcess >> _stepOverInFrame:mode:replace:tos:

GsSocket >> _waitingProcessesInto:

GsSocket >> _waitingProcessesInto:inGroup:

GsTsExternalSession >> _getObjInfo:buffer:

IdentityBag >> _basicAdd:

IdentityBag >> _rcIncludes:

IdentityBag >> _rcIncludesValue:

IndexingErrorPreventingCommit >> _signalWith:

Integer >> _floatParts

Object >> addObjectToBtreesWithValues:

Object >> _respondsTo:private:flags:

Object >> _errorsDuringPreventCommit:

RcIdentityBag >> _thisSessionRemovalIndex

RcKeyValueDictionary >> _keyCollisionOk

SmallInteger >> _floatParts

System class >> _deprecatedCacheStatisticsDescription

System class >> _disallowSubsequentCommits:System class >> _primitiveAbort

System class >> _sessionsReportExcluding:

System class >> _hostWaitForDebuggerIfSlow