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

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

• 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

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

• 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

• 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

• 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 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.5 Internationalizing

• Dates in GemStone log files

• Internationalizing Decimal Points using Locale

6.6 Random Numbers

• Universally unique identifiers (UUIDs)

• Random Number Generator

7.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

7.2 Defining Queries

• Query Predicate Syntax

  • Predicate Terms

  • Combining Predicates using Boolean Logic

  • Combining Range Predicates

• Creating a GsQuery

  • Query Variables

7.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

7.4 Results of Executing a GsQuery

• GsQuery’s Collection protocol

• GsQuery enumeration methods accepting blocks

• Query results as Streams

  • Limitations on streamable queries

7.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

7.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

7.7 Indexing and Performance

• Type of index

• Data updates

• Formulating queries and performance

  • Auto-optimize

7.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

8.1 GemStone’s Conflict Management

• 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

8.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

8.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

8.4 Classes That Reduce the Chance of Conflict

• RcCounter

• Reduced-Conflict Collection Classes

  • RcArray

  • RcIdentityBag

  • RcLowMaintenanceIdentityBag and RcIdentitySet

  • RcKeyValueDictionary

  • GsPipe

  • RcPipe

  • RcQueue

9.1 How GemStone Security Works

• Login Authorization

  • The UserProfile

• System Privileges

• Object-level Security

  • GsObjectSecurityPolicy

9.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

9.3 Application Example

9.4 Development Example

9.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

9.6 Privileged Protocol for Class GsObjectSecurityPolicy

10.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

10.2 ClassHistory

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

• Accessing a Class History

• Assigning to a Class History

10.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.1 Overview for SSL keys and certificates

• GsTlsCredential

• Creating a GsTlsCredential

• Verifying public/private key pairs

• Encryption and signing algorithms

11.2 Checksums and HMAC

• Checksums

• HMAC (Hash-based message authentication codes)

11.3 Symmetric-Key Encryption

• Encryption

• Example

11.4 Digital Signatures

11.5 Digital Envelopes

• Creating the GsDigitalEnvelope

• Using the GsDigitalEnvelope

12.1 Accessing 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

12.2 Executing Operating System Commands

• Simple Commands

  • Using other shells

• More complex interactions

• Restictions on OS access

12.3 Setting environment variables

12.4 File In and File Out

• Fileout

• Filein

12.5 PassiveObject

12.6 Creating and Using Sockets

• GsSocket

  • 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

13.1 Communicating Between Sessions

13.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

13.3 Gem-to-Gem Signaling

• Sending a Signal

  • Receiving a Signal

13.4 Other Signal-Related Issues

• Inactive Gem

• Dealing With Signal Overflow

  • Sending Large Amounts of Data

• Maintaining Signals and Notification When Users Log Out

14.1 The Exception Class Hierarchy

14.2 Signaling Exceptions

14.3 Handling Exceptions

• Dynamic (Stack-Based) Handlers

• Selecting a Handler

• Flow of Control

• Default Handlers

• Default Actions

14.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

15.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

15.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?

15.3 Modifying Cache Sizes for Better Performance

• GemStone Caches

  • Temporary Object Space

  • Shared Page Cache

• Getting Rid of Non-Persistent Objects

15.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

15.5 NotTranloggedGlobals

15.6 Other Optimization Hints

16.1 Creating and Removing Methods

• Defining Simple Accessing and Updating Methods

• Compiling Methods

• Removing Methods

• Pragmas

  • Pragma class

16.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

16.3 Transient Methods

16.4 ClassOrganizer

16.5 Handling Deprecated Methods

• Deprecated handling

• Deprecation log

• Listing deprecated methods

• Determining senders of deprecated methods

17.1 Hidden Sets

• Sets still accessed via System methods

  • NotifySet

  • ExportedDirtyObjs and TrackedDirtyObjs

  • PureExportSet and GciTrackedObjs

17.2 SessionTemps and access to Session State

• SessionState

17.3 Shared Counters

• AppStat Shared Counters

• Persistent Shared Counters

17.4 GsEventLog

• Adding events

• Querying and reporting

• Deleting events

18.1 Overview of the Foreign Function Interface

18.2 FFI Core Classes

• CLibrary

• CCallout

• C type symbols

• Limitations with native code disabled

• CCallin

• CByteArray

• CFunction

• CPointer

18.3 FFI Wrapper Utilities

• CHeader

• Creating a Smalltalk class

19.1 Overview

19.2 External Sessions

• Setup the External Session

  • Creating the External Session

• Log in the External Session

• Executing Code

• Important caution on Export Set of remote session

• Exceptions

19.3 NRS and Login Parameter Support

• For a Stone

• For a Gem

• Convenience methods for common arguments

19.4 Special Cases of External Sessions

• Solo external sessions

• Primitive-based external sessions on AIX

• X509 external sessions

20.1 Why SUnit?

20.2 Testing and Tests

20.3 SUnit by Example

• Examining the Value of a Tested Expression

• Finding Out If an Exception Was Raised

20.4 The SUnit Framework

20.5 Understanding the SUnit Implementation

• Running a Single Test

• Running a TestSuite

20.6 For More Information

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

• 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