IT consulting GORISEK d.o.o.

Página 1 de 10

Slovenska verzija
Home | Company | Products | Services

OmniBase OmniBase API Reference

z Features
z Tutorial OmniBase API reference
z API Reference
z Download
OmniBase API consists of methods in new classes added by OmniBase
z Purchase
and of extensions to base Smalltalk classes (loose methods). The following
z Links
document is a reference of all methods available to the application
z FAQ
developer using OmniBase. The API described is the same in all Smalltalk
dialects for which OmniBase is available (Dolphin Smalltalk, VisualWorks
and VisualAge Smalltalk).

Index of classes
Block (aka BlockClosure) loose methods
Object loose methods
Object class loose methods
Class loose methods
OmniBase class methods
OmniBase database connection methods - instance methods of class
OmniBase
OmniBase transaction methods - instance methods of class
ODBTransaction and subclasses
BTreeDictionary methods - instance methods of class
ODBBTreeDictionary

Block loose methods (aka BlockClosure)

z evaluateAndCommitIn: anODBTransaction

Evaluates the receiver block in the context of anODBTransaction.

Inside a block the active process current transaction will be
anODBTransaction. Sending OmniBase currentTransaction will
answer anODBTransaction. Using OmniBase class methods the
developer can access the database without referencing transaction
explicitly. After the block is evaluated the transaction is committed
i.e. all changes are writtten into the database. If the receiver block is
curtailed during its evaluation the transaction is automatically
aborted and all locks are freed. Answer the result of evaluating the
receiver block.

z evaluateIn: anODBTransaction

Evaluates the receiver block in the context of anODBTransaction.

Inside a block the active process current transaction will be
anODBTransaction. Sending OmniBase currentTransaction will
answer anODBTransaction. Using OmniBase class methods (e.g.

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 2 de 10

OmniBase root, OmniBase commit, ...) the developer can access the
database without referencing transaction explicitly. After the block
is evaluated the transaction is still active and has to be aborted or
committed. If the receiver block is curtailed during its evaluation the
transaction is automatically aborted and all locks are freed. Answer
the result of evaluating the receiver block.

Object loose methods

z asBtreeKeyOfSize: keySize

Subclass and implement this method for objects which can be used
as a b-tree dictionary keys. Method should answer a ByteArray of
size keySize. See also Object>>newBTreeDictionary: and class
ODBBTreeDictionary.

z isIdenticalTo: anObject

Use this method to check for object identify of persistent objects.

Referenced persistent objects are replaced by proxy objects upon
load (instances of class ODBReference). Since the usual identity
operator #== is implemented by a primitive comparing a proxy and
a real object will answer <false> even if they are indeed one and the
same object.

z isODBReference

Answer true if the receiver object is a proxy object (a proxy object

only forwards messages to the real object, it also fetches the real
object from the database upon first message send.

z makePersistent

Make the receiver object persistent in the current transaction. The

object will be stored into the default container. Do nothing if the
receiver object is already persistent.

z markDirty

Mark the receiver object as dirty. A new version of the object will be
stored into the database upon transaction commit. Signal an error if
the object is not already persistent.

z odbLoadedIn: anODBTransaction

This method is sent to every persistent object when it is fetched from

the database in anODBTransaction.

z odbMadePersistentIn: anODBTransaction

This method is sent to the object when it has been made persistent in

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 3 de 10

a transaction.

z odbSerialize: serializer

Implement this method if application specific object serialization is

needed. The basic serialization mechanism in OmniBase covers all
the usual needs. Implementing a special serialization method is
usefull only for space and performance reasons (data compression,
etc.).

Object class loose methods

z newPersistent

Answer a new instance of the receiver class and make it persistent at

the same time.

Class loose methods

z odbTransientInstanceVariables

Answer a collection of instance variable names which are transient.

Transient instance variables i.e. their contents will not be stored into
the database upon commit. During the object serialization their
contents will be ignored, upon load transient instance variable will
have a value of nil. Define transient instance variables for file
handles, view resources and similar objects that can not live outside
a Smalltalk image. Application specific initialization of transient
instance variables can be done at load time by implementing a
method #odbLoadedIn:.

OmniBase class methods

z allSessions

Answer all opened database sessions i.e. instance of OmniBase.

z checkpoint

Checkpoint current transaction. Current transaction must exist, if

there is none an error will be thrown. Checkpointing transaction
writes all changes to the database but does not abort the transaction,
the transaction can still be used and all locks are left in place.

z closeAll

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 4 de 10

Closes all opened database sessions in the image.

z commit

Commits current transaction. Current transaction must exist, if there

is none an error will be thrown. Committing transaction writes all
changes to the database and aborts the transaction releasing all
object locks and dictionary key locks. The transaction object can not
be used anymore.

z createOn: aString

Creates a new database on a directory aString e.g. 'c:\temp\MyDB'.

It will create directory MyDB if it does not exist. If will throw an
error if a database already exists in the given directory. Answer an
instance of class OmniBase which is the opened database session.

z current

Answer the database session of the current transaction. Thows an

error if there is no current transaction.

z currentTransaction

Answer database transaction in the current process or global context.

A transaction can be associated either with the active Smalltalk
process or there is one global OmniBase transaction set. If the active
process has a transaction associated it will answer the transaction of
the active process even if there is a global transaction set. The use of
a global transaction is discouraged and should be used only for
testing purposes e.g. evaluating code in a workspace. See also Block
loose methods for better understanding of the current transaction
idea.

z newBTreeDictionary: keySize

Answer an instance of ODBBTreeDictionary initialized to the key

size of the given argument (meaning maximum key size). A b-tree
dictionary is a persistent object which can be used to store large
amounts of key-value pairs and can be simultaneuosly updated by
multiple users each having impression as he is the only one working
with the database. A key of the b-tree dictionary can be any object
implementing a method #asBtreeKeyOfSize:. A value inside a b-tree
dictionary can be any other persistent object or nil. Keys are sorted.
Key size can be set only at creation time. If the value put into the
dictionary has not been stored before - is not a persistent object -
then it will be stored in the container in which the dictionary itself is
stored.

z newBTreeIndexDictionary: keySize

Answer an instance of ODBBTreeIndexDictionary initialized to the

key size of the given argument. A b-tree index dictionary is a

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 5 de 10

persistent object which can be used to index large amounts of key-

value pairs and can be simultaneuosly updated by multiple users
each having impression as he is the only one working with the
database. A key of the b-tree index dictionary can be any object
implementing a method #asBtreeKeyOfSize:. The difference
between a b-tree dictionary and a b-tree index dictionary is that an
index dictionary is used for secondary indices and its keys need not
be unique. In an index dictionary key-value pairs are unique, but
there can be many values sharing the same key.

z newPersistentDictionary

Answer an instance of ODBPersistentDictionary which is a special

kind of dictionary which automatically detects changes to itself
(adding or removing association). It is a Smalltalk Dictionary in
which all values are automatically made persistent and stored after
they are put into a dictionary. Dictionary itself is not automatically
stored in the database but has to be stored in some way before (either
by putting it in another persistent dictionary or by explicitly storing
it using the makePersistent: or store: method). The database root
object is also a persistent dictionary (created by default). A
persistent dictionary can not be updated by multiple users at the
same time as a new version of the object is always stored into the
database on each change.

z objectAt: anODBObjectID

Answer a persistent object with id anODBObjectID. The object is

loaded in the current transaction. Throws an error if there is no
current transaction. Answer nil if there is no object with the given
object ID.

z openOn: aString

Open an existing database on a directory aString. Answer an

instance of OmniBase. Throws an error if a database does not exist
in the given directory.

z rollback

Aborts the current transaction. No changes are written to the disk

and all object locks and key locks are released.

z root

Answer the database root object. All objects in the database should
be accessible from the root object, otherwise they are automatically
garbage collected the next time a database GC is run. The root object
is an instance of ODBPersistentObject by default, but it can be
changed to any other object.

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 6 de 10

OmniBase methods

z close

Closes open database. All transactions are aborted and locks are
released. Do nothing if the database is already closed.

z existsContainerNamed: aString

Answer true if container named aString exists in the database, false

if not. A container is a special file where serialized objects are stored
to. There can be up to 65535 containers in a database. Using
containers one can speed up object access by storing objects which
are usualy sequentialy accessed into the same file. Also by clustering
objects sensibly into multiple containers the database will need less
additional space when doing database garbage collection.

z globalLock

Globally locks the database so that no other user can change objects
while it is locked. Global lock will fail if any user (including
yourself) holds a lock on at least one object. Answers true if
successful, false otherwise.

z globalUnlock

Releases global lock. Afterwards all other users will be able to lock
objects for writing and change their contents. Answers true if
successfull, false otherwise.

z isGlobalLocked

Answer true if the database is globally locked, false otherwise.

z newContainer: aString

Creates new object container in the database. A new subdirectory

will be created in the database subdirectory Objects/ where the
object storage file and b-tree files of objects in this container will be
stored.

z newReadOnlyTransaction

Answer new read-only transaction. The difference between a normal

transaction and the read-only transaction is that every object lock or
store attempt will be ignored. Sending #markDirty of
#makePersistent will be ignored and no #abort is necessary. This
way persistence enabled objects can be changed without setting a
lock in the database.

z newTransaction

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 7 de 10

Answer new database transaction. The transaction always starts in a

read only mode needs no finalization. Only when you set a lock,
change or store an object the transaction has to be released by
sending abort.

z numberOfClients

Answer total number of database connections currently open in the

database.

z setUserDescription: aString

Set user description string for this database connection. Other

database users i.e. other database connections can see this string
which is sometimes usefull to see who is using the database at the
same time.

z garbageCollect

Garbage collects entire database. All unreferenced objects are

removed. All containers are compacted. This method is available in
the registered version only.

z reorganize

Same as garbage collection plus all b-tree dictionaries are

reorganized to consume the minimum amount of disk space. This
method is available in the registered version only.

OmniBase transaction methods

Objects in the database can be accessed only through transaction. First you
access the root object from which you can navigate to whatever object in
the database. While a transaction is active it can hold locks on objects.
While an object is locked in one transaction it can not be locked and
changed in any other transaction. See instance methods of class
ODBLocalTransaction for further details.

z abort

Aborts active transaction. All locks on objects in transaction are

released. Sending #abort is not needed, if no locks were obtained in
the transaction and no objects were stored.

z commit
commits transaction i.e. writes all changes made in transaction to
database. Two-phase commit process is used to write changes to the
databases. If commit succeds all changes made during the
transaction will be written to the database. Otherwise nothing will be
changed (e.g. if network or some other HW error occurs). Locks are
not released. After commit transaction is still active until it receives

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 8 de 10

the #abort message.

z isChanged
answer <true> if any object in transaction has been changed.
z becomeInconsistent
mark transaction as inconsistent. After receiving this message
transaction can not be committed anymore.
z isInconsistent
answer <true> if transaction is inconsistent.
z rootObject
answer the root object of the database.
z rootObject: anObject
set the root object of the database to anObject.
z lock: anObject
lock anObject for writing. Answer <true> if successfull, <false> if
failed. Method will fail if an object is locked in some other
transaction or if it has been changed in a transaction that has already
committed. Locking will also fail if database is globally locked by
another user.
z unlock: anObject
unlock anObject. Lock can not be released if object has been
changed i.e. stored.
z store: anObject
inform receiver that anObject has been changed. When transaction
commits this object will be written to database. All transactions
started after transaction commit will get new version of this object.
Transaction started before commit will still access the old version.
Exception will be signaled if anObject can not be locked. This
method has to be called everytime anObject is changed, otherwise it
will not be written when transaction commits.
z store: anObject in: aStringOrOmniBaseContainer
store anObject to a given container. Container name (or container) is
relevant only when object is stored for the first time. Afterwards its
location (the container it is stored in) can not be changed. Exception
will be signaled if anObject can not be locked.

ODBBTreeDictionary instance methods

A b-tree dictionary provides a way to store and access large number of

objects in the database. Dictionary keys can be only objects of class String
or ByteArray (maximum length of a key has to be set at creation time, see
method OmniBase class>>#newBTreeDictionary:). Multiple users can
access and change dictionary at the same time. BTreeDictionary also
includes a cursor that points to a specific key and provides a way to iterate
through objects in the dictionary. See instance methods of class
ODBBTreeDictionary for further details.

z at: aString

Answer value stored at aString.

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 9 de 10

z at: aString put: anObject

Associate anObject with aString. If anObject is not already persistent

it will be stored in the same container the BTreeDictionary is in.
Else anObject will not be stored i.e. it wont be marked as changed.
Method will fail if key aString is locked or has been already changed
in some other transaction.

z lockKey: aString

Locks key in a dictionary. No other transaction will be able to

change the association while a key is locked. Unexisting keys can
also be locked. Answer true if successfull, false if failed. Method
will fail if association has already been locked or changed in some
other transaction.

z unlockKey: aString

Unlocks key aString.

z size

Answer number of (key, value) pairs contained in the dictionary.

Method always answers the exact number of items in the dictionary
regardless of simultaneus changes (adding, removing) of other users.

z goTo: aString

positiones iterator cursor to key aString.

z getCurrent

answers association at current cursor position or nil if none.

z getNext

Answers next association from current cursor position or nil if at

end.

z getPrevious

Answers previous association from current cursor position or nil if at

beginning. Positiones cursor to previous key.

z getFirst

Answers first association and positiones cursor to the first key in the
dictionary. Answer nil if dictionary is empty.

z getLast

Answers the last association and positiones cursor to the last key in

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004
IT consulting GORISEK d.o.o. Página 10 de 10

the dictionary. Answer nil if dictionary is empty.

Powered by Smalltalk & OmniBase
© 1998-2002 IT consulting GORIŠEK Ltd. All rights reserved.

http://www.gorisek.com/homepage/WOB-BWWnMttdy9Xm1VzR1eW0u5Fp-1-10.ht... 18/06/2004