ObjectStore Java API User Guide

Index

A

AbortException 120
aborting transactions 120
default effects on persistent objects 179
setting default object state 171
setting objects to default state 171
specifying a particular object state 171
abstract classes 307
accessing persistent objects
committing transactions 153
default effects of methods 179
dirty() 294
evicting objects 162
fetch() 294
optimizing 280
procedure 137
root, obtaining 138
saving changes by committing transaction 153
saving changes through eviction 162
active persistent objects
aborting transactions 172
committing transactions 157
default effects of methods 179
definition 12
evicting 166
adding thread to session 46
aggregations, very large 198
annotations
automatic 235
customizing 275
description 238
manual 289
superclass modifications 259
you must add 285
applicationName property 59
applications
complex, finding right class files 255
failure 4
required components 20
architecture 6
archive logging 2
-arraydims option 282
arrays
optimizations 382
passing 286
AuthenticationFailureException 61

B

bad command or file name error message 263, 373
batch
definition 239
postprocessing two 240
postprocessor requirement 244
batch schema installation
advantage 332
database, creating with 335
identifying application types 333
installing application types 336
introduction 331
procedure 332
-boolean option 388
BrokenServerException 120

C

C++ applications 2
C++ database garbage collection 84
Cache Manager description 6
cache size 59
cacheSize property 59
changing classes
schema evolution 86
checkpoint 323
Class could not be found error 246
class files
annotated
finding 254
locations 261
managing 252
applications, complex 255
compile unannotated 253
inner 251
nested 251
referring to persistent and transient versions 271
ClassCastException troubleshooting 66
-classdir option 387
ClassInfo class
-classinfosuffix option 379
create() 296
getClassDescriptor() 296
getFields() 296
subclass, defining 295
-classinfosuffix option 379
ClassNotRegisteredException 237
CLASSPATH
alternatives 256
class files, locating 253
-classpath 247
requirements 243
-classpath option 379
clearContents()
manual annotations 293
postprocessor 275
client description 6
clustering 316
collections
adding indexes 223
advantages 201
alternative, selecting best 205
bags 195
built-in types, storing 233
choosing 205
comparison 205
creating 207
hash code requirements 231
implemented interfaces 193
inserting objects during construction 265, 382
introduction 192
iterating 208
JDK1.2 hashCode() 194
lists 201
maps 206
navigating 208
OSHashBag 195
OSHashMap 195
OSHashSet 196
OSHashtable 197
OSTreeMap 198
OSTreeSet 199
OSVector 200
OSVectorList 201
postprocessing 194
postprocessor optimization 265
querying 210
relative size 205
sets 196
third-party 234
COM.odi.applicationName property 59
COM.odi.cacheSize property 59
COM.odi.disableWeakReferences property 60
COM.odi.gc.lockTimeOut property 83
COM.odi.gc.reachableObjects property 84
COM.odi.gc.reclaimedObjects property 84
COM.odi.gc.retries property 83
COM.odi.gc.retryInterval property 83
COM.odi.gc.transactionPriority property 83
COM.odi.migrateUnexportedStrings property 60
COM.odi.ObjectStore.library 61
COM.odi.product property 61
COM.odi.Session class 28
COM.odi.stringPoolSize property 65
COM.odi.trapUnregisteredType property 66
COM.odi.user 61
COM.odi.util.query.Query class 211
committing transactions
after evicting objects 169
default effects on persistent objects 179
failures 117
introduction 116
RETAIN_HOLLOW 156
RETAIN_READONLY 157
RETAIN_STALE 154
RETAIN_UPDATE 160
saving changes 153
situations to avoid 130
concurrency control
access, preventing 326
batch schema installation 331
conflicts, handling 329
locking objects 326
multiversion 318
consistent state 124
constructors, postprocessor optimization 265
cooperating threads 48
-copyclass option 248
copying
classes without annotating 248
databases 80
copying data among PSE, PSE Pro, and ObjectStore databases 61
creating database roots 131
creating databases 68
creating external references 142
creating notifications 345
creating sessions 32

D

database
open types 75
Database class
description 68
identity 70
database roots
changing referred to object 134
creating 131, 132
destroying 134
how many 135
null values 133
primitive values 133
Database.close() 77
Database.create()
batch schema installation 335
default schema installation 69
example 69
Database.createRoot() 132
Database.createSegment() 72
Database.destroy() 95
Database.destroyRoot() 134
Database.evolveSchema() 88
Database.GC() 82
Database.getOpenMode() 97
Database.getPath() 97
Database.getSizeInBytes() 97
Database.isOpen() 96
Database.open() 74
Database.setRoot() 134
databases
closing 74
consistent state 124
copying 80
copying data among PSE, PSE Pro, and ObjectStore 61
creating 69
creating roots 131
destroying 95
destroying objects 173
displaying information about 395
exporting objects 101
garbage collection 82
identity 77
information about, displaying 98
information about, obtaining 96
locking with acquireLock() 326
managing 67
moving 80
MVCC, open for 320
names 70
objects, migrating 99
objects, storing 128
open modes 79
open types 79
open? 96
opening 74
opens, automatic 79
pathname of 97
persistent garbage collection 82
platforms 68
read-only, open for? 97
references, checking 393
roots, how many 135
schema evolution 86
segments 72
size of 97
transient 73
update, open for? 97
dead objects 395
DeadlockException 120
deadlocks
aborting transactions 123
description 120
retrying aborted transactions 121
debugger 264
deepFetch() method
description 158
serialization 367
-dest option 380
destination directory
about 246
requirement 244
destroying
cleaning up ObjectNotFoundExceptions 178
database roots 134
databases 95
objects in the database 173
objects referred to by other objects 178
persistent objects, default effects 179
preDestroyPersistent() hook method 174
dirty()
background 309
manual annotations 294
disableWeakReferences property 60
disk space
copy of object in database 147
duplicates
postprocessor, file specifications for 249
strings 359

E

enums, specification 388
environment variables
OS_JAVA_VM 373
OSJCFPJAVA 373
evicting objects
all 167
persistent objects, default effects on 179
persistent objects, references to 163
RETAIN_HOLLOW 165
RETAIN_READONLY 166
RETAIN_STALE 164
threads, cooperating 168
transactions, committing 169
transactions, outside 169
evolveSchema() 88
evolving schema
introduction 86
when required 87
examples
annotations, manual 297
batch schema installation 336
before running a program 24
code for people demo 21
compiling 25
general use 19
getFields() 311
hook methods 277
identity 148
indexes on collections 224
persistence mode options, multiple 249
postprocessing batches 240
postprocessor command line 244
querying utility collections 212
running a program 26
running peer generator tool 391
running postprocessor 245
schema evolution, serialization 92
serializing 367
transient-only fields 303
exporting
peer objects 101
primary objects 101
external references
creating 142
encoding as strings 146
introduction 141
nonexported objects 143
obtaining objects 144
reusing 145
transactions 146
ExternalReference class 141

F

failover 2
FAQs xxiii
fetch()
background 309
manual annotations 294
Field class 310
fields in manual annotations 313
file name too long 379
final fields
initialization 274
postprocessor handling of 261
finalize() method
annotations 264
avoiding 182
flushContents()
background 310
manual annotations 292
postprocessor 275
-force option 380
free variables 218
-full option 388

G

garbage collection
active objects from commit() 157
active objects from evict() 166
C++ databases 84
databases 82
hollow objects from commit() 156
hollow objects from evict() 165
osgc utility 84
persistent, overview 81
properties 83
segments 82
stale objects from commit() 154
stale objects from evict() 164
strings 82
tombstones 82
weak references 152
GenericObject class
description 309
getting field values 312
setting field values 312
get.PersistentClasses() method 333
getFields()
background 310
example 311
global sessions 33

H

hash tables
references to destroyed objects 178
-hashcode postprocessor option 380
hashCode()
arrays 233
problems 260
providing 232
requirements 231
hollow object constructors
creating 279
transient nonstatic fields 287
hollow persistent objects
aborting transactions 172
default effects of methods 179
definition 11
evict() 165
transactions, committing 156
hook methods 275

I

identity
databases 77
Java wrapper classes 359
persistent objects 148
-includesummary option
description 380
how to use 333
incremental schema installation 331
-indexablefield option
description 381
IndexDescriptor class 228
IndexDescriptorSet class 228
IndexedCollection interface 223
indexes
adding to collections 223
background 222
dropping 224
example 224
introduction 222
managing 227
modifying 225
optimizing queries 228
updating 226
info segment 56
initializeContents()
background 309
manual annotations 292
postprocessor 275
initializing API
creating nonglobal session 35
specifying properties 57
initializing objects, definition 11
initializing transient fields 274
inner classes 251
-inplace postprocessor option 381
input file for postprocessor 284
input file option 388
installing application types 336
installing schema information 331
interfaces
annotations 290
interoperability between PSE, PSE Pro, and ObjectStore 61
interoperability, specifying enums 388
iterators 208

J

jar files 250
Java executables 263
Java Remote Method Interface 158
Java-supplied classes 358
JDK 1.2
compatibility 203
hashCode() 194
unsupported operation 203

L

large aggregations 198
Lea, Doug, collections library 234
-leaf option 388
-libdir option 387
libraries
application types, identifying in 333
ObjectStore 61
postprocessing existing 240
providing type summaries 403
third-party collections 234
type summaries, providing 334
ListIterator class 208
locking
databases 326
objects 326
peer objects 328
segments 326
and transaction length 316
wait time, reducing 316
locks
acquiring 326
converting read to write 56
MVCC, obtaining 318
releasing 328
timeouts 317
types 327
long file names 379

M

manual annotations
abstract classes 307
application types, identifying 338
background for accessing fields 308
background for creating fields 308
ClassInfo subclass definition 295
example 297
fields, accessing 313
fields, creating 313
fields, transient-only 302
initializeContents() 292
methods, required 292
persistence-aware classes 306
postprocessor conventions 306
procedure 290
mapping schema database
-schema option 387
maps
description 206
OSHashMap 195
OSTreeMap 198
querying 202
media failure 4
migrating
objects 99
PSE to ObjectStore 61
unexported strings 60
-modifyjava option 382
moving
databases 80
objects into a database 129
objects to another segment 103
multiversion concurrency control
databases, multiple 319
databases, opening 320
locks, obtaining 318
serializability 319
snapshots 318
MVCC
See multiversion concurrency control

N

native methods
capability for persistence 361
postprocessing 286
-native_interface option 388
nested classes 251
nested transactions 114
-noarrayopt option 382
-nodefaulthashcode postprocessor option 382
-noinitializeropt option 382
noncooperating threads 49
nonexported objects 161
nonglobal sessions 34
nonpersistent methods 285
-noopt option 383
notation conventions xxii
-nothisopt option 383
notification facility
background 340
introduction 339
managing 353
performance 354
process flow 341
queue 353
security 344
Notification() 345
Notification.getData() 352
Notification.getKind() 352
Notification.getMessage() 352
Notification.getObject() 352
Notification.getPendingNotifications() 353
Notification.getQueueOverflows() 353
Notification.getQueueSize() 353
Notification.notifyImmediate() 350
Notification.notifyOnCommit() 350
Notification.receive() 351
Notification.subscribe() 348
Notification.unsubscribe() 349
notifications
creating 345
definition 340
reading 352
retrieving 351
sending 350
subscribing 348
threads 342
transactions 343
-nowrite option 283, 383
null values
maps 206
queries 220

O

object table 152
objects
destroying 173
evicting, See evicting objects
external references 141
identity 148
is it persistent? 138
listing in a segment 139
retrieving 137
storing 128
updating 147
ObjectStore
code example of use with PSE 64
copying data to PSE 61
general description 2
process architecture 6
what it does 4
ObjectStore library property 61, 65, 66
ObjectStore utility collections
hash code method requirements 231
ObjectStore.deepFetch() 367
ObjectStore.destroy() 173
ObjectStore.dirty() 294
ObjectStore.evict() 162
ObjectStore.evict(RETAIN_HOLLOW) 165
ObjectStore.evict(RETAIN_READONLY) 166
ObjectStore.evict(RETAIN_STALE) 164
ObjectStore.evictAll() 167
ObjectStore.export() 100
ObjectStore.fetch() 294
ObjectStore.getAutoOpenMode() 79
ObjectStore.INSTALL_SCHEMA_BATCH 335
ObjectStore.INSTALL_SCHEMA_INCREMENTAL 335
ObjectStore.migrate() 99
ObjectStore.MVCC 75
ObjectStore.READONLY 75, 110
ObjectStore.RETAIN_HOLLOW
aborting transactions 172
committing transactions 156
evicting objects 165
ObjectStore.RETAIN_READONLY
aborting transactions 172
committing transactions 157
evicting objects 166
ObjectStore.RETAIN_STALE
aborting transactions 171
committing transactions 154
evicting objects 164
ObjectStore.RETAIN_UPDATE
aborting transactions 172
committing transactions 160
ObjectStore.setAutoOpenMode() 79
ObjectStore.UPDATE 75
starting transaction 110
ObjectStoreConstants.MVCC 75
ObjectStoreConstants.READONLY 75
ObjectStoreConstants.UPDATE 75
ODMG binding 3
-oldtemplates option 390
online backup 2
optimizations, postprocessor
descriptions 265
disabling 265
-optimizeclassinfo option to osjcfp 251, 383
OS_JAVA_VM environment variable 373
oscopy utility 80
osgc utility
C++ databases 84
Java databases 84
OSHashBag collection 195
OSHashMap collections 195
OSHashSet collections 196
OSHashtable collections
description 197
JDK 1.2 compatibility 204
lazy allocation 197
osjcfp 235
See postprocessor
OSJCFPJAVA environment variable 263, 373
osjcgen utility 387
osjcheckdb utility 393
osjgcdb utility 84
osji.zip file 24
osjshowdb utility 98, 395
osjversion utility 401
osmv utility 80
OSTreeMap collections 198
OSTreeSet collections 199
OSVector collections
description 200
JDK 1.2 compatibility 204
OSVectorList collections 201

P

package names
postprocessed classes 268
renaming 288
-package option 387
password property 61
patch updates xxiii
PATH requirements 243
peer generator tool
class list 388
example of running 391
input files 388
options 387
running 387
peer objects
definition 15
exporting 101
performance
cross-segment references 99
Java-supplied classes 362
lazy hash table allocation 197
lazy vector allocation 200
notification facility 354
-persistaware option 248
-persistcapable option 248
persistence
how objects become persistent 129
Java-supplied classes 358
manual annotations 302
postprocessor 235
transitive 129
persistence mode options 248
persistence-aware classes
creating 257
definition 14
manual annotations 306
persistence-capable classes
abstract 307
annotations 238
definition 10
generating, automatically 235
generating, manually 289
Java-supplied 358
subclasses 286
superclasses 259
transient fields 273
transient versions 246
using as transient 369
persistent objects
active after evict() 166
associated session 43
definition 10
destroying 173
evicting all 167
exporting 101
external references 141
garbage collection 81
hollow after abort() 172
hollow after commit() 156
hollow after evict() 165
identity 148
is this object persistent? 138
migrating 99
multiple representations 53
nonexported 161
object state, specifying 147
readable after abort() 172
readable after commit() 157
retrieving 137
serializing 367
stale after abort() 171
stale after commit() 154
stale after evict() 164
transient fields 180
updatable after abort() 172
updatable after commit() 160
UPDATE transaction 111
Persistent.preDestroyPersistent() 174
PersistentTypeSummary class 333
postInitializeContents() 276
postprocessor
annotated class files, location 261
annotated class files, managing 252
annotated classes, previously 250
annotated classes, subclasses 286
applications, complex 255
array dimensions 282
batches 239
Class could not be found error 246
CLASSPATH requirements 243
command line, sample 244
consistency 259
conventions 306
customizing 275
debugger 264
destination directory background 246
destination directory requirement 244
duplicate file specifications 249
errors and warnings 261
example of multiple persistence modes 249
example of running 245
file name interpretation 247
file not found 249
final fields 261
hollow object constructor 279
hook methods, sample 277
how it works 258
input file 284
introduction 237
Java classes, modifying 382
limitations 288
new packages 268
nonpersistent classes 266
nonpersistent methods 285
objects, optimizing retrieval of 280
optimizations 265
optimizations can cause problems 183
PATH requirements 243
persistence mode options 248
persistence-aware classes 257
preparations 243
preventing generation of ClassInfo 383
processing order 247
running 242, 379
static fields 262
superclasses, modifications 259
testing 283
transient classes 271
transient fields 273
-translatepackage option 269
zip files 250
preClearContents() 276
preFlushContents() 276
primary keys 205
primary objects 14
product property 61
propagation, transaction log 322
properties
COM.odi.applicationName 59
COM.odi.cacheSize 59
COM.odi.disableWeakReferences 60
COM.odi.migrateUnexportedStrings 60
COM.odi.ObjectStoreLibrary 61, 65, 66
COM.odi.password 61
COM.odi.product 61
COM.odi.user 61
garbage collection 83
parameter 58
system 57
trapUnregisteredType 66
PSE
code example of use with OSJI 64
copying data to ObjectStore 61
using with OSJI 61

Q

queries
creating 211
example 212
executing 219
expressions 211
free variables 218
indexes 222
introduction 210
limitations 221
literals 211
maps 202
names 211
null values 220
operators 213
optimizing for indexes 228
String literals 214
syntax 213
unsupported 213
-quiet option 384
-quietclass option 384
-quietfield option 384

R

reachability 130
read locks 56
reading notifications 352
read-only
database open type 75
receiving notifications 348
recovery 4
reducing size of application 251
references
checking 393
cross-segment 99
destroying sources 174
destroying targets 178
external 141
from evicted objects 163
to transient instances 272
registering classes
manual annotation 290
postprocessor 237
remote machines 2
Remote Method Invocation. see RMI
RestartableAbortException 120
restarting aborted transactions 121
RETAIN constants. see ObjectStore.RETAIN
retaining objects
abort transaction 170
commit hollow 156
commit read-only 157
commit update 160
default abort retain state 171
evict active 166
evict hollow 165
eviction 162
nonexported 161
retain argument 153
retrieving notifications 351
RMI
preparing to serialize 158
serializing for 367
using persistence-capable classes 369

S

saving modifications
committing transactions 153
evicting objects 162
schema evolution
needed when 87
preparation 88
procedure 86
serialization sample code 92
superclasses 89
schema information 331
-schema option 387
schema segment 56
security, notifications 344
Segment.GC() 82
segments
cross references 99
description 72
garbage collection 82
listing 73
locking 326
objects, iterating through 139
objects, wrong placement of 103
situations to avoid 130
storing objects in particular ones 129
transient 73
sending notifications 350
serializability 319
serialization
persistent objects 367
sample code for schema evolution 92
Server description 6
ServerRefusedConnectionException 120
ServerRestartedException 120
Session.createGlobal() 33
Session.getGlobal() 33
Session.getName() method 34
Session.join() 46
Session.leave() 50
Session.terminate() 39
sessions
associated objects 43
calls that imply 44
creating 32
definition 28
global session 33
is one active? 40
join rules 43
joining threads automatically 42
metaobjects 55
names 34
nonglobal 34
nonimplying calls 45
objects, copies of 29
obtaining 40
properties, specifying 57
shutting down 39
threads 41
threads not associated 51
threads, explicitly adding 46
threads, relationship to 41
threads, removing 50
transactions 37
setting transient fields 276
sharing data among PSE, PSE Pro, and ObjectStore 61
shutting down sessions 39
smaller footprint 251
stale persistent objects
aborting transactions 171
attempts to access 179
committing transactions 154
definition 13
evict() 164
static fields
postprocessor handling 262
session ownership 54
storing external references 142
storing objects
has this object been stored? 138
how objects become persistent 129
in particular segments 129
procedure 128
string pool size 65
strings
destroying 366
garbage collection 82
making them persistent 364
pool size 65
queries 214
reusing 65
unexported, migrating 60
stublib.zip 369
subscribing to receive notifications 348
-summary option
description 385
how to use 333
superclasses
abstract 307
modifications for persistence 259
persistence-aware classes 257
schema evolution 89
support xxiii
-suppress option 390
suppressing generation of methods 390
synchronization 154
system crash 4
system properties 57

T

technical support xxiii
terminating sessions 39
testing postprocessor 283
third-party collections 234
threads
already initialized? 52
committing a transaction, effect of 55
cooperating 48
joined to session? 52
joining session explicitly 46
joining session, automatically 42
noncooperating 49, 51
not joined to session 51
notifications 342
objects, evicting 168
persistent objects, access to 53
removing from session 50
sessions 41
synchronizing 50
transaction boundaries 126
tombstones
destroyed objects 173
persistent garbage collection 82
tools.zip file 24
Training xxiv
Transaction class description 110
Transaction.abort()
example 171
general discussion 118
retain 119
Transaction.abort(RETAIN_HOLLOW) 172
Transaction.abort(RETAIN_READONLY) 172
Transaction.abort(RETAIN_STALE) 171
Transaction.abort(RETAIN_UPDATE) 172
Transaction.begin() 110
Transaction.commit()
general discussion 116
saving modifications 153
Transaction.commit(retain)
general discussion 116
specifying object state 153
Transaction.current() 114
Transaction.setDefaultAbortRetain() 171
transactions
aborted, retrying 121
aborting 118, 120
aborting to cancel changes 170
boundaries, determining 124
checkpoint 323
committing
description 116
setting object state 153
situations to avoid 130
deadlocks 120
ending 115
evicting objects outside 169
external references 146
length 316
multiversion concurrency control 318
nested 114
notifications 343
priority 330
RETAIN_HOLLOW 156
RETAIN_READONLY 157
RETAIN_STALE 154
RETAIN_UPDATE 160
sessions 37
starting 110
Transaction object, obtaining 114
update and read-only 111
transient and persistence-capable versions of same class 271
transient database 73
transient fields
annotations, manual 302
annotations, preventing 281
initialization 274
persistence-capable classes, behavior 180
postprocessor 273
read-only transactions 276
transient instance of persistence-capable class 272
transient objects 15
transient segment 73
transient version of class file 246
transient views of collections 202
transitive persistence
becoming persistent 129
definition 15
trapping unregistered types 66
trapUnregisteredType property 66
troubleshooting
access not allowed 265
authentication required 61
bad command or file name 263, 373
class could not be found 246
ClassCastException 66, 184
destroyed objects, references to 178
OutOfMemoryError
postprocessor 250
storing large objects 136
retaining for read or update 158
trapping unregistered types 66
UnregisteredTypeException 184
two sessions
static variables 54
two object copies 29

U

unexported strings property 60
Unicode strings 360
unknown types 184
unregistered type property 66
UnregisteredType class 184
UnregisteredTypeException 184
update
database open type 75
updating objects 147
upgrading PSE to ObjectStore 61
user property 61
UTF8 encoding 360
utilities
garbage collection 84
osjcfp 235
osjcheckdb 98, 393
osjshowdb 98, 395
osjversion 401

V

variable initializers 303
-verbose option 385
version information 401
very large aggregations 198
views of maps 202

W

weak references 60, 152
weak references property 60
wrapper classes
identity 359
persistence-capable 358
queries 214
write locks 56


[previous]

Copyright © 1998 Object Design, Inc. All rights reserved.

Updated: 10/07/98 05:11:13