GemStone/S 64 Bit Programmer's Guide

1.1 GemStone Overview

• Multi-User

• Programmable

• Scalable

• Object Database

• Partition Between Client and Server

• Connect to Outside Data Sources

1.2 GemStone Services

• Transactions and Concurrency Control

• Login Security and Account Management

• Services To Manage the GemStone Repository

1.3 GemStone Smalltalk

• GemStone Sessions

• Monitoring your application

• Interapplication Communications

1.4 Process Architecture

• Gem Process

• Stone Process

• NetLDI

• Shared Page Cache

• Extents and Repositories

• Transaction Log

2.1 Subclass Creation

• Implementation Formats

• Class Variables and Other Types of Variables

• Dynamic Instance Variables

• Additional Class Creation Protocol

2.2 Creating Classes With Invariant Instances

• Per-Object Invariance

• Invariance for All Instances of a Class

2.3 Creating Classes with Special Cases of Persistence

• Non-Persistent Classes

• DbTransient

2.4 Customer-defined Special classes

• Money example

3.1 Sharing Objects

3.2 The UserProfile’s Symbol List

• What’s In Your Symbol List?

• Examining Your Symbol List

• Inserting and Removing Dictionaries from Your Symbol List

• Finding Out Which Dictionary Names an Object

• The Transient Symbol List

• Updating Symbol Lists

3.3 Using Your Symbol Dictionaries

• Publishers, Subscribers and the Published Dictionary

4.1 Introduction to Collections

• Protocol Common to All Collections

  • Creating Instances

  • Enumerating

• Collections in multi session environment

  • Conflicting updates

  • Visibility and ordering

• Collection classes

• Dictionary classes

  • Internal Dictionary Structure

  • Dictionary and KeyValueDictionary

  • KeySoftValueDictionary

• SequenceableCollection classes

  • Copying

  • Array

  • SortedCollection

• Stream Classes

  • PositionableStream and Position

  • AppendStream

  • ReadByteStream

• UnorderedCollection classes

  • Union, Intersection, and Difference

4.2 Reduced-Conflict Collection Classes

• RcArray

• NSC/UnorderedCollection classes

  • RcIdentityBag

  • RcLowMaintenanceIdentityBag

  • RcIdentitySet

• RcKeyValueDictionary

• Queue classes

  • GsPipe

  • RcPipe

  • RcQueue

4.3 GsBitmap

• GsBitmaps and C Heap memory

• GsBitmaps and their objects

• GsBitmaps methods for repository analysis

• Bitmap files

• Page order Bitmap files

4.4 Sorting the objects in a collection

• Default Sort

• Sorting Application objects

  • Sorting in multiple orders

• SortBlocks

• Sorting Large Collections

5.1 Characters and Unicode

• Empty string canonicalization

• Unicode and the Unicode Database

5.2 String classes

• Traditional Strings

• Unicode Strings

• String equality, ordering, and interoperation

• Other String-like classes

  • Symbol

  • ByteArray

  • Utf8

  • Utf16

• String protocol

  • Creating Strings

  • Concatenating Strings

  • Converting between String classes and encodings

  • String Transformations

  • Equality and Identity

  • Searching and Pattern matching

5.3 String Sorting and Collation

• Comparison Mode

  • StringConfiguration

  • Auto-conversion

• Legacy String Comparison Mode for Traditional Strings

• Unicode Comparison Mode and ICU Collation

  • IcuLocale

  • IcuCollator

  • Customizing Sort

  • IcuSortedCollection

• ICU libraries and versioning

  • ICU and Unicode versioning

  • IcuLibraryVersion

5.4 Encrypting Strings

6.1 Integers

• SmallInteger

• LargeInteger

• Printing Integers

6.2 Binary Floating Point

• SmallDouble

• Float

  • Signalling Exception rather than returning Exceptional Float

• Literal Floats

• Printing Binary Floating Points

6.3 Other Rational Numbers

• Fractions

  • SmallFraction

  • Fraction

• ScaledDecimals

  • SmallScaledDecimal

  • ScaledDecimal

• FixedPoints

• DecimalFloat

• Summary of literal syntax

• Custom numeric literals

6.4 Result classes, Conversion, and Rounding

• Conversion

• Truncation and Rounding

6.5 Dates and Times

• Date

  • SmallDate

  • Instance Creation

  • Formatting for Instance Creation and Printing

• Time

  • SmallTime

  • Instance Creation

  • Formatting for Instance Creation and Printing

  • Time offset

• DateTime

  • Instance Creation

  • Formatting for Instance Creation and Printing

• DateAndTime

  • SmallDateAndTime

  • Instance Creation

  • Formatting for Instance Creation and Printing

• TimeZone

6.6 Internationalizing

• Dates in GemStone log files

• Internationalizing Decimal Points using Locale

  • Smalltalk code requires the period separator

6.7 Random Numbers

• Universally unique identifiers (UUIDs)

• Random Number Generator

7.1 Accessing Files using GsFile

• Client vs. Server files

• Specifying Files

• Creating a File

• Opening a File

• Closing a File or Files

• Writing to a File

• Reading from a File

  • Positioning

• Testing Files

• Renaming Files

• Removing Files

• Examining a Directory

• GsFile Errors

• Logging to stdout

  • On the server (Gem)

  • On the client (GCI client)

7.2 FileSystem

• FileReference

  • FileLocator

• FileSystem

• Specifying a FileReference

  • Working Directory and other environment-independent paths

• Reading from and Writing to a File

  • Closing file streams

  • File encodings

  • Binary Streams

• Operations on Files and Directories

  • Create

  • Delete

  • Move

  • Copy

  • Rename

• Information queries

  • Status of a file or directory

  • Information about a file

  • File permissions

  • Decomposition of filename and path

  • Listing Directories and Files

• Supporting Classes

  • FsFileDescriptor

  • Zinc Stream Classes

  • Error Classes

  • Path classes

  • Opening options

  • Store classes

  • Resolver classes

  • FFI support classes

8.1 Overview

• GemStone Indexes and Queries

  • Indexes

  • GsQueries

  • Deciding what to optimize

  • Overview of the steps in creating and using indexed queries

  • Managing Indexes

• Special Syntax for Indexing

  • Historic indexing syntax

• Last Element Class

  • Optimized classes

  • Using other classes

  • Comparing data types

  • Strings in indexes

  • Redefining Comparison Messages

8.2 Defining Queries

• Query Predicate Syntax

  • Predicate Terms

  • Combining Predicates using Boolean Logic

  • Combining Range Predicates

• Creating a GsQuery

  • Query Variables

8.3 Creating Indexes

• Equality and Identity Indexes

• Btree and Legacy Indexes

• Creating the Index

• Equality Indexes on strings

  • Repositories in Legacy String Comparison mode

  • Repositories in Unicode Comparison Mode

• Implicit Indexes

• GsIndexOptions

  • Combining options

  • Default options

  • The Options in GsIndexOptions

  • Reduced-Conflict

  • Optional pathTerms

8.4 Results of Executing a GsQuery

• GsQuery’s Collection protocol

• GsQuery enumeration methods accepting blocks

• Query results as Streams

  • Limitations on streamable queries

8.5 Enumerated and Set-valued Indexes

• Enumerated path terms in indexes and queries

  • Restrictions on predicates with enumerated pathTerms

• Indexes and Queries with collections on the path

  • Set-valued query results

  • Restrictions on predicates in set-valued queries

8.6 Managing Indexes

• While Indexes are Being Created

  • Queries during index creation

  • Auto-commit

• Indexes on temporary collections

• Inquiring About Indexes

• Removing Indexes

  • To remove indexes based on a GsIndexSpec

  • To remove indexes using IndexManager

  • Rebuilding Indexes

• Indexing Errors

• Auditing Indexes

8.7 Indexing and Performance

• Type of index

• Data updates

• Formulating queries and performance

  • Auto-optimize

8.8 Historic Indexing API differences

• Index creation using UnorderedCollection protocol

  • Internal legacy vs. btreePlus indexing structures

  • String and Unicode Equality Indexes

  • Reduced-conflict Equality Indexes

• Queries using Selection Blocks

  • Executing Selection Block Queries

• Managing indexes

  • Information about indexes

  • Removing Indexes

9.1 GemStone’s Conflict Management

• Note on Terminology

• Snapshot Views and Transactions

• Transaction State and Transaction Modes

• Reading and Writing in Transactions

• Reading and Writing Outside of Transactions

• When Should You Commit a Transaction?

• Nested In-memory Transactions

9.2 How GemStone Detects and Manages Conflict

• Concurrency Management

• Committing Transactions

• Handling Commit Failure in a Transaction

• Transaction Conflicts

• More details about transaction conflicts

• Indexes and Concurrency Control

• Aborting Transactions

  • Updating the View Without Committing or Aborting

  • Being Signaled To Abort

  • Being Signaled to continueTransaction

• Handlers for abort or continueTransaction notifications

9.3 Controlling Concurrent Access with Locks

• Lock Types

  • Read Locks

  • Write Locks

• Acquiring Locks

  • Lock Denial

  • Deadlocks

  • Dirty Locks

  • Locking Collections of Objects Efficiently

  • Upgrading Locks

• Locking and Indexed Collections

• Removing or Releasing Locks

  • Releasing Locks Upon Aborting or Committing

• Inquiring About Locks

• Application Write Locks

9.4 Classes That Reduce the Chance of Conflict

• RcCounter

• Reduced-Conflict Collection Classes

  • RcArray

  • RcIdentityBag

  • RcLowMaintenanceIdentityBag and RcIdentitySet

  • RcKeyValueDictionary

  • GsPipe

  • RcPipe

  • RcQueue

10.1 How GemStone Security Works

• Login Authorization

  • The UserProfile

• System Privileges

• Object-level Security

  • GsObjectSecurityPolicy

10.2 Assigning Objects to Security Policies

• Default Security Policy and Current Security Policy

• Objects and Security Policies

• Configuring Authorization for an Object Security Policy

  • How GemStone Responds to Unauthorized Access

  • Owner, Group, and World Authorization

• Predefined GsObjectSecurityPolicies

  • GsObjectSecurityPolicy names

  • Changing the Security Policy for an Object

  • Revoking Your Own Authorization: a Side Effect

  • Finding Out Which Objects Are Protected by a Security Policy

10.3 Application Example

10.4 Development Example

10.5 Planning Security Policies for User Access

• Protecting the Application Classes

• CodeModification privilege

• Planning Authorization for Data Objects

• Planning Groups

• Planning Security Policies

• Developing the Application

  • Setting Up Security Policies for Joint Development

  • Making the Application Accessible for Testing

  • Moving the Application into a Production Environment

• Security Policy Assignment for User-created Objects

10.6 Privileged Protocol for Class GsObjectSecurityPolicy

11.1 Versions of Classes

• Defining a New Version

• New Versions and Subclasses

• New Versions and References in Methods

• Class Variables and Class Instance Variables

• Class versioning and Class options

11.2 ClassHistory

• Defining a Class as a new version of an existing Class

• Accessing a Class History

• Assigning to a Class History

11.3 Migrating Objects

• Migration Destinations

  • Bypassing the Migration Destination

• Migrating Instances that Participate in an Index

• Default Instance Variable Mappings

• Customized Instance Variable Mappings

• Transforming Variable Values

• Finding Instances

• Tuning migration and managing memory

  • Using GsBitmaps to manage memory for large result sets

  • Tuning system resource use when finding instances

  • Committing the migration in chunks

  • Migrating instances in Page Order

11.4 Multi-threaded instance migration

• InstVarMappingArray

• Example

12.1 Overview for SSL keys and certificates

• GsTlsCredential

• Creating a GsTlsCredential

• Verifying public/private key pairs

• Encryption and signing algorithms

12.2 Checksums and HMAC

• Checksums

• HMAC (Hash-based message authentication codes)

12.3 Symmetric-Key Encryption

• Encryption

• Example

12.4 Digital Signatures

12.5 Digital Envelopes

• Creating the GsDigitalEnvelope

• Using the GsDigitalEnvelope

13.1 Executing Operating System Commands

• Privileges and limiting OS access

• performOnServer: for simple commands

  • Using other shells

• GsHostProcess for more complex interactions

  • Using execute:input: to pass data to stdin

  • Using fork: for interactive commands

  • Connecting stdin, stdout, and stderr

13.2 Setting environment variables

13.3 Creating and Using Sockets

• GsSocket and GsSignallingSocket

  • Establishing the connection

  • Communication on the socket

  • Closing the socket

  • Socket Configuration

• GsSecureSocket

  • Certificates, keys, and passphrases

  • Enable or disable verifying CA Certificate

  • Set certificate, private key, and passphrase

  • Setup the Cipher list

  • Establishing the connection

  • Communication on the socket

  • Closing the socket

  • HTTPS connection

• Error handling

  • GsSocket

  • GsSecureSocket

• GsSecureSocket pre-shared keys

  • TLS version handling

  • Example in image

13.4 ssh and sftp using OpenSSL

• SSH with GsSshSocket

  • Creating the SSH connection

  • SSH operations

• SFTP with GsSftpSocket

  • Creating Sftp connection

  • Sftp operations

• GsSftpRemoteFile for operations on remote files

13.5 Serializing Data

• PassiveObject

• JSON

14.1 Communicating Between Sessions

14.2 Object Change Notification

• Setting Up a Notify Set

  • Adding an Object to a Notify Set

  • Adding a Collection to a Notify Set

  • Listing Your Notify Set

  • Removing Objects From Your Notify Set

• Notification of New Objects

  • Receiving Object Change Notification

  • Reading the Set of Signaled Objects

• Polling for Changes to Objects

• Troubleshooting

  • Frequently Changing Objects

  • Special Classes

• Methods for Object Notification

14.3 Gem-to-Gem Signaling

• Sending a Signal

  • Legacy protocol to send signals

• Receiving a Signal

  • Polling

  • Receiving a Notification

14.4 Other Signal-Related Issues

• Inactive Gem

• Dealing With Signal Overflow

  • Sending Large Amounts of Data

• Maintaining Signals and Notification When Users Log Out

15.1 The Exception Class Hierarchy

15.2 Signaling Exceptions

15.3 Handling Exceptions

• Dynamic (Stack-Based) Handlers

• Selecting a Handler

• Flow of Control

• Default Handlers

• Default Actions

15.4 The Legacy Exception Handling Framework

• Dynamic (Stack-Based) Exception Handler

  • Installing a Dynamic (Stack-Based) Exception Handler

• Default (Static) Exception Handlers

  • Installing a Default (Static) Exception Handler

  • GemStone Event Exceptions

• Flow of Control

  • Signaling Other Exception Handlers

  • Removing Exception Handlers

  • Recursive Errors

• Raising Exceptions

• ANSI Integration

16.1 Profiling Smalltalk Execution

• Time to execute a block

  • CPU Time

  • Elapsed Time

• ProfMonitor

  • Sample intervals

  • Reporting limits

  • Reports

  • Temporary results file

  • Real vs. CPU time

• Profiling Code

  • Convenience Profiling of a Block of Code

  • Background Profiling

  • Manual Profiling

  • Saving a ProfMonitor for later analysis

• The Profile Report

• Profiling Beyond Performance

  • Object Creation Tracking

  • Memory Use Profiling

16.2 Clustering Objects for Faster Retrieval

• Will Clustering Solve the Problem?

• Cluster Buckets

  • Using Existing Cluster Buckets

  • Creating New Cluster Buckets

  • Cluster Buckets and Concurrency

  • Cluster Buckets and Indexing

• Clustering Objects

  • The Basic Clustering Message

  • Depth-First Clustering

  • Assigning Cluster Buckets

  • Clustering and Memory Use

  • Using Several Cluster Buckets

  • Clustering Class Objects

• Maintaining Clusters

  • Determining an Object’s Location

  • Why Do Objects Move?

16.3 Modifying Cache Sizes for Better Performance

• GemStone Caches

  • Temporary Object Space

  • Shared Page Cache

• Getting Rid of Non-Persistent Objects

16.4 Managing VM Memory

• Large Working Set

• Class Hierarchy

• UserAction Considerations

• Exported Set

• Debugging out of memory errors

• Signal on low memory condition

• Methods for Computing Temporary Object Space

• Statistics for monitoring memory use

16.5 NotTranloggedGlobals

16.6 Other Optimization Hints

17.1 Creating and Removing Methods

• Defining Simple Accessing and Updating Methods

• Compiling Methods

• Removing Methods

• Pragmas

  • Pragma class

17.2 Information about Class and Methods

• Information about the Class

• Information about Instance, Class, and Shared Pool variables

• Information about Method Selectors

• Accessing and Managing Method Categories

• Specific Methods

17.3 Transient Methods

17.4 ClassOrganizer

• Examples

17.5 Handling Deprecated Methods

• Deprecated handling

• Deprecation log

• Listing deprecated methods

• Determining senders of deprecated methods

17.6 File In and File Out of GemStone code

• Fileout

• Filein

• GsFileIn

18.1 Hidden Sets

• Sets still accessed via System methods

  • NotifySet

  • ExportedDirtyObjs and TrackedDirtyObjs

  • PureExportSet and GciTrackedObjs

18.2 SessionTemps and access to Session State

• SessionState

18.3 Shared Counters

• AppStat Shared Counters

• Persistent Shared Counters

18.4 GsEventLog

• Adding events

• Querying and reporting

• Deleting events

19.1 Overview of the Foreign Function Interface

19.2 Using the FFI

• CLibrary: defining the compiled C or C++ library

• CCallout: function definitions in GemStone

• CHeader: Parsing the C header file

• CDeclaration: Finding details on a C function

• Creating a Class and Methods from the CHeader

• CByteArray: Allocating memory for data

  • Complex data types

• Making FFI calls

  • Executing a CCallout created by hand

  • Execute CHeader-generated definition

• Arguments and Return Values

  • String type arguments

  • Variable Arguments

• CCalloutStructs: Using C Structures passed by value

• CPointer

• Errno Handling

• CCallin: Creating and invoking callbacks

• C type symbols

• Limitations with native code disabled

19.3 Example using Zlib

• Parsing the header file

• Using CHeader wrapper methods to create a class

19.4 Example using CCalloutStructs and variable arguments with RabbitMQ®

• Hand creation of CCalloutStructs

• Using CHeader wrapper methods to create CCalloutStructs

  • Further refinement: creating a convenience method

20.1 Overview

20.2 External Sessions

• Setup the External Session

  • Creating the External Session

  • Avoiding passwords in code

• Log in the External Session

• Executing Code

• Important caution on Export Set of remote session

• Exceptions

20.3 NRS and Login Parameter Support

• For a Stone

• For a Gem

• Convenience methods for common arguments

20.4 Special Cases of External Sessions

• Solo external sessions

• Primitive-based external sessions on AIX

• X509 external sessions

21.1 Application Testing

• The value of testing

• Writing good tests

• Why SUnit?

• Portable SUnit classes and GemStone’s SUnit classes

• Terminology: test errors vs. failures

21.2 SUnit example: ExampleSetTest

• Define the new testing Class

• Define setUp and tearDown methods

• Define the actual testing methods

• Execute the tests

• Assertions and other claims in test methods

  • Checking result value with assert: and deny:

  • Checking for exceptions with should:raise:

21.3 The SUnit Framework and Implementation

• SUnit Core Classes

• Running a Single Test

• Running a TestSuite

A.1 GemStone and ANSI Smalltalk

• GemStone and ANSI limits

A.2 GemStone Smalltalk

• How to Create a New Class

• Statements

• Comments

• Expressions

  • Literals

  • Numeric Literals

  • Character Literals

  • String Literals

  • Symbol Literals

  • Array Literals

• Variables and Variable Names

• Assignment

• Message Expressions

• Reserved and Optimized Selectors

  • Conditionally Optimized Selectors

• Messages as Expressions

• Combining Message Expressions

• Cascaded Messages

• Array Constructors

• Path Expressions

• Returning Values

A.3 Blocks

• Blocks with Arguments

• Blocks and Conditional Execution

• Formatting Code

A.4 GemStone Smalltalk BNF