GemStone/S Programming Guide - GemStone Systems

438 Pages·1992·2.74 MB·English

®
GemStone
GemStone/S
Programming
Guide
December 2001
GemStone/S
Version 6.0
GemStone Programming Guide
IMPORTANT NOTICE
This manual and the information contained in it are furnished for informational use only
andaresubjecttochangewithoutnotice.GemStoneSystems,Inc.assumesnoresponsibility
or liability for any errors or inaccuracies that may appear in this manual or in the
information contained in it. The manual, or any part of it, may not be reproduced,
displayed,photocopied,transmittedorotherwisecopiedinanyformorbyanymeansnow
knownorlaterdeveloped,suchaselectronic,opticalormechanicalmeans,withoutwritten
authorizationfromGemStoneSystems,Inc.Anyunauthorizedcopyingmaybeaviolation
of law.
The software installed in accordance with this manual is copyrighted and licensed by
GemStoneSystems,Inc.underseparatelicenseagreement.Thissoftwaremayonlybeused
pursuant to the terms and conditions of such license agreement. Any other use may be a
violation of law.
Limitations
The software described in this manual is a customer-supported product. Due to the
customer’sabilitytochangeanypartofaSmalltalkimage,GemStoneSystems,Inc.cannot
guarantee that the GemStone programming environment will function with all Smalltalk
images.
ª 1988–2001 by GemStone Systems, Inc. All rights reserved.
Use, duplication, or disclosure by the Government is subject to restrictions set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013.
Trademarks
GemStone,GemBuilder,GemConnect,GemEnterprise, andGemORB are registered
trademark of GemStone Systems, Inc. The GemStone logo is a registered trademark of
GemStone Systems, Inc.
VisualWorksis a trademark of Cincom, Inc.
VisualAge is a trademark of International Business Machines Corporation.
Sun,Sun Microsystems,Solaris andSunOS are trademarks or registered trademarks of
Sun Microsystems, Inc. AllSPARC trademarks, includingSPARCstation, are trademarks
orregisteredtrademarksofSPARCInternational,Inc.SPARCstationislicensedexclusively
to Sun Microsystems, Inc.
UNIX is a registered trademark in the United States and other countries, licensed
exclusively through X/Open Company Limited.
All other trademarks are the property of their respective owners.
ii GemStone Systems, Inc. December 2001
Preface
About This Manual
This manual describes the GemStone Smalltalk language and programming
environment—abridgebetweenyourapplication’sSmalltalkcoderunningona
UNIX workstation and the GemStone database running on the host computer.
Alongwithoneoftheinterfacesfortheprogrammingenvironment,youcanbuild
comprehensive applications.
Intended Audience
This manual is intended for users familiar with the basic concepts of computer
programming. It explains GemStone Smalltalk in terms of traditional
programmingconcepts.Therefore,you’llbenefitmostfromthematerialpresented
here if you have a solid understanding of a conventional language such as C.
It would also be helpful to be familiar with a Smalltalk language and its
programming environment. In addition to your Smalltalk product manuals, we
recommendSmalltalk-80:TheLanguageanditsImplementationandSmalltalk-80:The
Interactive Programming Environment (both published by Addison-Wesley).
This manual assumes that the GemStone system has been correctly installed on
yourhostcomputerasdescribedintheGemStoneSystemAdministrationGuide,and
December 2001 GemStone Systems, Inc. iii
Preface GemStone Programming Guide
that your system meets the requirements listed in theInstallation section of the
Release Notes.
Documentation Conventions
GemStoneSmalltalkcodeisprintedinamonospacefontthroughoutthismanual.
It looks like this:
numericArray add: (myVariable + 1)
When the result of executing an example is shown, it is underlined:
numericArray at: 1
12486
Executing the Examples
This manual includes a many examples. Because we cannot be certain which
interfaceyouareusing,andbecausetheinterfaceaffectsthewayyouexecutethe
examples,hereareafewwordsaboutthemechanicsofthesituationmaybeuseful
here.
There are two simple ways to write and compile a method:
• IfyouareusingGemBuilderforSmalltalk,youcanusethestructuredediting
and execution facilities provided by a GemStone Browser or workspace. A
browsermakesiteasiertodefineclassesandmethodsbypresentingtemplates
fortheseoperations.Onceyou’vefilledoutthetemplates,abrowserinternally
builds and executes GemStone Smalltalk expressions to compile the classes
andmethods.Abrowserorganizesyourworkandpresentsitinapleasingand
easily understood format.
A workspace makes it easier to compile and execute fragments of GemStone
Smalltalk code interactively, and see the results immediately using the
GemStoneprint it command.
• YoucanalsoenteryourGemStoneSmalltalkmethodcodethroughtheTopaz
version of the programming environment. Topaz requires a few extra
commands to begin and end an example. To identify code as constituting a
method, for instance, you’ll add a couple of simple non-GemStone Smalltalk
directivessuchas“METHOD:.”ThesetellTopaztotreattheindicatedtextas
a method to be compiled and installed in a class.
iv GemStone Systems, Inc. December 2001
GemStone Programming Guide Preface
This is in some ways less convenient than using the GemStone Browser to
createmethods,butithasoneimportantadvantage: methoddefinitionsinthis
format are easily represented and inspected on the printed page.
ThismanualpresentsexamplesinTopazformat,withTopazcommandspresented
inboldfacetype. Thosecommandsprobablyneedlittleexplanationwhenyousee
them in context; however, you may need to turn to the Topaz user manual for
instructions about entering and executing the text of the upcoming examples.
If you are using GemBuilder for Smalltalk, you may instead choose to read the
introductionstothebrowserandworkspace,andthenusethosetoolstoenterthe
examples in this manual. The text of the examples themselves (excluding the
boldface Topaz commands) is the same whichever way you choose to enter it.
Other Useful Documents
Youwillfinditusefultolookatdocumentsthatdescribeothercomponentsofthe
GemStone data management system:
• A complete description of the behavior of each GemStone Smalltalk kernel
class is available online in the GemStone image class and method comments.
• The Topaz interface allows you to process data and move it between the
GemStone system and a terminal or workstation, when your GemStone
Smalltalkprogramneedstoreadterminalinputorsenddatatoaworkstation
for local processing and display. The GemBuilder for Smalltalk and
GemBuilderforCinterfacesprovidefunctionlibrariestoaccesstherepository.
Each interface is described in its own user manual.
• In addition, if you will be acting as a system administrator, or developing
software for someone else who must play those roles, read theGemStone
System Administration Guide.
December 2001 GemStone Systems, Inc. v
Preface GemStone Programming Guide
Technical Support
GemStone/S provides several sources for product information and support.
GemStone/S product manuals provide extensive documentation, and should
always be your first source of information. GemStone/S Technical Support
engineerswillreferyoutothesedocumentswhenapplicable. However, youmay
need to contact Technical Support for the following reasons:
• Your technical question is not answered in the documentation.
• You receive an error message that directs you to contact GemStone/S
Technical Support.
• You want to report a bug.
• You want to submit a feature request.
Questions concerning product availability, pricing, keyfiles, or future features
should be directed to your GemStone/S account manager.
When contacting GemStone/S Technical Support, please be prepared to provide
the following information:
• Your name, company name, and GemStone/S license number,
• the GemStone/S product and version you are using,
• the hardware platform and operating system you are using,
• a description of the problem or request,
• exact error message(s) received, if any.
Your GemStone/S support agreement may identify specific individuals who are
responsibleforsubmittingallsupportrequeststoGemStone. Ifso,pleasesubmit
your information through those individuals. All responses will be sent to
authorized contacts only.
Fornon-emergencyrequests,youshouldcontactTechnicalSupportbywebform,
email, or facsimile. You will receive confirmation of your request, and a request
assignmentnumberfortracking. Replieswillbesentbyemailwheneverpossible,
regardless of how they were received.
World Wide Web: http://support.gemstone.com
The preferred method of contact. The Help Request link is at the top right
corner of the home page—please use this to submit help requests. This form
requires a password, which is free of charge but must be requested by
completing the Registration Form, found in the same location. You’ll be able
to access the site as soon as you submit the web form.
vi GemStone Systems, Inc. December 2001
GemStone Programming Guide Preface
Email: [email protected]
Please do not send files larger than 100K (for example, core dumps) to this
address. A special address for large files will be provided on request.
Facsimile: [phone]
WhenyousendafaxtoTechnicalSupport,youshouldalsoleaveavoicemail
message to make sure your fax will be picked up as soon as possible.
Werecommendyouusetelephonecontactonlyformoreseriousrequeststhat
require immediate evaluation, such as a production database that is non-
operational.
Telephone: [phone] or [phone]
Emergencyrequestswillbehandledbythefirstavailableengineer. Ifyouare
reporting an emergency and you receive a recorded message, do not use the
voicemailoption. Transferyourcalltotheoperator,whowilltakeamessage
and immediately contact an engineer.
Non-emergency requests received by telephone will be placed in the normal
support queue for evaluation and response.
24x7 Emergency Technical Support
GemStone/S offers, at an additional charge, 24x7 emergency technical support.
This support entitles customers to contact us 24 hours a day, 7 days a week, 365
daysayear,iftheyencounterproblemsthatcausetheirproductionapplicationto
go down, or that have the potential to bring their production application down.
Contact your GemStone/S account manager for more details.
December 2001 GemStone Systems, Inc. vii
Preface GemStone Programming Guide
viii GemStone Systems, Inc. December 2001
Contents
Chapter 1. Introduction to GemStone
1.1 Overview of the GemStone System. . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2 Multi-user Object Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.3 Programmable Server Object System. . . . . . . . . . . . . . . . . . . . . . 1-2
1.4 Partitioning of Applications Between Client and Server . . . . . . . . . . . 1-3
1.5 Large-scale Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.6 Queries and Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.7 Transactions and Concurrency Control . . . . . . . . . . . . . . . . . . . . 1-5
1.8 Connections to Outside Data Sources . . . . . . . . . . . . . . . . . . . . . 1-6
1.9 Object Security and Account Management . . . . . . . . . . . . . . . . . . 1-7
1.10 Services to Manage the GemStone Repository . . . . . . . . . . . . . . . . 1-8
Chapter 2. Programming With GemStone
2.1 The GemStone Programming Model . . . . . . . . . . . . . . . . . . . . . . 2-2
Server-based Classes, Methods, and Objects. . . . . . . . . . . . . . . 2-2
Client and Server Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Gemstone Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
December 2001 GemStone Systems, Inc. ix
Contents GemStone Programming Guide
2.2 GemStone Smalltalk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Language Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Constraining Variables . . . . . . . . . . . . . . . . . . . . . . 2-5
Query Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Auto-Growing Collections . . . . . . . . . . . . . . . . . . . . 2-8
Class Library Differences . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
No User Interface . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Different File Access . . . . . . . . . . . . . . . . . . . . . . . 2-8
Different C Callouts. . . . . . . . . . . . . . . . . . . . . . . . 2-8
Class Library Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
More Collection Classes . . . . . . . . . . . . . . . . . . . . . 2-9
Reduced-conflict Classes . . . . . . . . . . . . . . . . . . . . . 2-9
User Account and Security Classes . . . . . . . . . . . . . . . 2-9
System Management Classes. . . . . . . . . . . . . . . . . . . 2-9
File In and File Out . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Interapplication Communications . . . . . . . . . . . . . . . . . . . . 2-10
2.3 Process Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Gem Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Stone Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Shared Object Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Scavenger Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Extents and Repositories. . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Transaction Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
NetLDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Login Dynamics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Chapter 3. Resolving Names and Sharing Objects
3.1 Sharing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
3.2 UserProfile and Session-based Symbol Lists . . . . . . . . . . . . . . . . . 3-2
What’s In Your Symbol List? . . . . . . . . . . . . . . . . . . . . . . . 3-3
Examining Your Symbol List . . . . . . . . . . . . . . . . . . . . . . . 3-4
Inserting and Removing Dictionaries From Your Symbol List . . . . 3-6
Updating Symbol Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Finding Out Which Dictionary Names an Object . . . . . . . . . . . . 3-10
3.3 Using Your Symbol Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Publishers, Subscribers and the Published Dictionary . . . . . . . . . 3-12
x GemStone Systems, Inc. December 2001