com.odi
Class ObjectStore

java.lang.Object
  |
  +--com.odi.ObjectStore

All Implemented Interfaces:

ObjectStoreConstants

public class ObjectStore

extends java.lang.Object

implements ObjectStoreConstants

The ObjectStore class defines system-level operations that are not specific to any database.

Field Summary

static int	fileNativesIfAvailable Deprecated.
static int	fileNativesNone Deprecated.
static int	fileNativesRequired Deprecated.
static int	majorRelease Deprecated.
static int	minorRelease Deprecated.
static int	ObjectStoreEdition Deprecated.
static int	OPEN_MVCC Deprecated.
static int	OPEN_READONLY Deprecated.
static int	OPEN_READONLY_NON_BLOCKING Deprecated.
static int	OPEN_UPDATE Deprecated.
static int	OPEN_UPDATE_NON_BLOCKING Deprecated.
static int	PSEEdition Deprecated.
static int	PSEProEdition Deprecated.

Fields inherited from interface com.odi.ObjectStoreConstants

ALL_EXECUTE, ALL_READ, ALL_WRITE, DEFAULT, DISABLE_AUTO_OPEN, GROUP_EXECUTE, GROUP_READ, GROUP_WRITE, INSTALL_SCHEMA_BATCH, INSTALL_SCHEMA_INCREMENTAL, MULTI_DB_MVCC, MVCC, OBJECTSTORE, OTHER_EXECUTE, OTHER_READ, OTHER_WRITE, OWNER_EXECUTE, OWNER_READ, OWNER_WRITE, PSE, PSE_PRO, READONLY, READONLY_NON_BLOCKING, RETAIN_HOLLOW, RETAIN_READONLY, RETAIN_STALE, RETAIN_TRANSIENT, RETAIN_UPDATE, UPDATE, UPDATE_NON_BLOCKING, WAIT_FOREVER, XA_TRANSACTION

Method Summary

static void	acquireLock(java.lang.Object object, int lockType, int timeoutMillis) Attempt to acquire a read or update lock on an object.
static void	clearCache() Clears the contents of all objects that are currently in the cached state.
static void	clearCache(int nTransactions) Clears the contents of objects that are currently in the cached state and which have not been accessed in nTransactions.
static void	decache(java.lang.Object cachedObject) Causes the specified object to no longer be cached.
static void	deepFetch(java.lang.Object object) Obtains the contents of the specified object, all objects that object refers to, all objects those objects refer to, and so on.
static void	destroy(java.lang.Object object) Destroys a persistent object.
static void	dirty(java.lang.Object object) Obtains the contents of a persistent object and allows the contents to be modified and saved in the database.
static int	edition() Deprecated.
static void	evict(java.lang.Object object) Evicts a persistent object.
static void	evict(java.lang.Object object, int retain) Saves, but does not commit, any changes to a persistent object and specifies the state of the evicted object after the eviction.
static void	evictAll(int retain) Evicts all persistent objects by running the evict(object, retain) method on all persistent objects known to the session.
static void	export(java.lang.Object object) Allows an object to be referred to from another segment (this method is not available in PSE/PSE Pro).
static void	export(java.lang.Object object, int exportId) Allows an object to be exported with a specified id.
static void	fetch(java.lang.Object object) Obtains the contents of a persistent object and makes them available for read access by the application.
static int	getAutoOpenMode() Determines the current default open mode for opening a database automatically to traverse a cross-database reference (not available in PSE/PSE Pro).
static java.util.Iterator	getCachedObjects() Reports those objects that are currently in the cached state within the current session.
static int	getCachedObjectTxnAge(java.lang.Object cachedObject) Returns the number of transactions for which the specified object was not accessed.
static int	getExportId(java.lang.Object object) Obtain the export id of an exported object.
static boolean	getLazyWriteLocking() Determines the current state of lazy write locking (not available in PSE/PSE Pro).
static int	getLockTimeout() Gets the time in milliseconds for which the current session waits when attempting to to acquire a lock.
static int	getNumExpectedSessions() Returns the number of simultaneous sessions that the application can create.
static Placement	getPlacementForSerialization() Gets the com.odi.Placement where certain objects are migrated upon being de-serialized if they cannot be created transiently.
static boolean	initialize(java.lang.String host, java.util.Properties properties) Creates a session that permits the caller to use the rest of the API.
static boolean	initialize(java.lang.Thread targetThread) Associates the calling thread with the session that the targetThread belongs to.
static boolean	isDestroyed(java.lang.Object object) Determines whether or not the argument was destroyed.
static boolean	isExported(java.lang.Object object) Determines whether or not an object is exported (this method always returns false in PSE/PSE Pro).
static boolean	isPersistent(java.lang.Object object) Determines whether or not the argument is persistent.
static boolean	isStale(java.lang.Object object) Determines whether or not the argument is stale.
static int	languageInterfaceMajorRelease() Returns the major release of the Java language interface for ObjectStore that is running in the current thread.
static int	languageInterfaceMinorRelease() Returns the minor release of the Java language interface for ObjectStore that is running in the current thread.
static java.lang.String	languageInterfaceName() Returns the name and release of the Java language interface for ObjectStore that is running in the current thread.
static int	maintenanceRelease() Returns the maintenance release version of ObjectStore for Java running in the current thread.
static int	majorRelease() Returns the major release version of ObjectStore for Java running in the current thread.
static void	migrate(java.lang.Object object, Placement placement, boolean export) Moves a persistence-capable object into a database.
static int	minorRelease() Returns the minor release version of ObjectStore for Java running in the current thread.
static java.lang.String	productName() Returns the product name and release of ObjectStore that is running in the current thread.
static java.lang.String	releaseName() Deprecated.
static void	setAutoOpenMode(int openMode) Specifies the default open mode when ObjectStore opens a database automatically to traverse a cross-database reference (not available in PSE/PSE Pro).
static void	setLazyWriteLocking(boolean onOff) This is the interface for turning lazy write locking on and off (not available in PSE/PSE Pro).
static void	setLockTimeout(int milliseconds) Set the time in milliseconds for which the current session waits when attempting to to acquire a lock.
static void	setNumExpectedSessions(int numExpectedSessions) Specifies the number of simultaneous sessions that application expects to create (not available in PSE or PSE Pro).
static void	setPlacementForSerialization(Placement placement) Sets the com.odi.Placement where certain objects are migrated upon being de-serialized if they cannot be created transiently.
static void	shutdown(boolean force) Terminates the session that the calling thread belongs to.
static java.lang.String	storageSystemName() Returns the name and release of the storage system for ObjectStore that is running in the current thread.
static int	whichProduct() Returns a value that identifies the ObjectStore Java product that is running in the current thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

majorRelease

public static int majorRelease

Deprecated.

Use majorRelease() in place of this deprecated field.

See Also:

ObjectStore.majorRelease()

minorRelease

public static int minorRelease

Deprecated.

Use minorRelease() in place of this deprecated field.

See Also:

ObjectStore.minorRelease()

PSEEdition

public static final int PSEEdition

Deprecated.

Use PSE in place of this deprecated field.

See Also:

ObjectStoreConstants.PSE

PSEProEdition

public static final int PSEProEdition

Deprecated.

Use PSE_PRO in place of this deprecated field.

See Also:

ObjectStoreConstants.PSE_PRO

ObjectStoreEdition

public static final int ObjectStoreEdition

Deprecated.

Use OBJECTSTORE in place of this deprecated field.

See Also:

ObjectStoreConstants.OBJECTSTORE

fileNativesNone

public static final int fileNativesNone

Deprecated.

The argument to specify in a call to useFileNatives() when you do not want to use the native library (not available in PSE or ObjectStore).

See Also:

ObjectStore.useFileNatives(int)

fileNativesIfAvailable

public static final int fileNativesIfAvailable

Deprecated.

The argument to specify in a call to useFileNatives() when you want to use the file natives if it is possible to load the library containing them without error (not available in PSE or ObjectStore).

See Also:

ObjectStore.useFileNatives(int)

fileNativesRequired

public static final int fileNativesRequired

Deprecated.

The argument to specify in a call to useFileNatives() when you want to use file natives and throw FatalApplicationException if the library containing them cannot be loaded (not available in PSE or ObjectStore).

See Also:

ObjectStore.useFileNatives(int)

OPEN_UPDATE

public static final int OPEN_UPDATE

Deprecated.

Database open mode for update. When you open a database with this mode, you can read and modify the contents of the database.

See Also:

Database.open(java.lang.String, int), ObjectStoreConstants.UPDATE

OPEN_READONLY

public static final int OPEN_READONLY

Deprecated.

Database open mode for read-only. When you open a database with this mode, you can read but not modify the contents of the database.

See Also:

Database.open(java.lang.String, int), ObjectStoreConstants.READONLY

OPEN_MVCC

public static final int OPEN_MVCC

Deprecated.

Open mode for multiversion concurrency control (MVCC).

See Also:

Database.open(java.lang.String, int), ObjectStoreConstants.MVCC

OPEN_UPDATE_NON_BLOCKING

public static final int OPEN_UPDATE_NON_BLOCKING

Deprecated.

Open mode for update that does not block processing to wait for the database lock (not valid for ObjectStore).

See Also:

ObjectStoreConstants.UPDATE_NON_BLOCKING

OPEN_READONLY_NON_BLOCKING

public static final int OPEN_READONLY_NON_BLOCKING

Deprecated.

Open mode for read-only that does not block processing to wait for the database lock (not valid in ObjectStore).

See Also:

ObjectStoreConstants.READONLY_NON_BLOCKING

Method Detail

majorRelease

public static int majorRelease()

Returns the major release version of ObjectStore for Java running in the current thread.

Returns:

The major release of ObjectStore.

Throws:

ObjectStoreException - If the current thread is not associated with a session amd there is no global session.

minorRelease

public static int minorRelease()

Returns the minor release version of ObjectStore for Java running in the current thread.

Returns:

The minor release of ObjectStore.

Throws:

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

maintenanceRelease

public static int maintenanceRelease()

Returns the maintenance release version of ObjectStore for Java running in the current thread.

Returns:

The maintenace release of ObjectStore.

Throws:

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

productName

public static java.lang.String productName()

Returns the product name and release of ObjectStore that is running in the current thread.

Returns:

The product name and release of ObjectStore.

Throws:

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

releaseName

public static java.lang.String releaseName()

Deprecated.

Use productName() in place of this deprecated method.

See Also:

ObjectStore.productName()

whichProduct

public static int whichProduct()

Returns a value that identifies the ObjectStore Java product that is running in the current thread.

Returns:

PSE if you are running PSE, PSE_PRO if you are running PSE Pro, OBJECTSTORE if you are running the Java interface to ObjectStore.

Throws:

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

edition

public static int edition()

Deprecated.

Use whichProduct() in place of this deprecated method.

See Also:

ObjectStore.whichProduct()

storageSystemName

public static java.lang.String storageSystemName()

Returns the name and release of the storage system for ObjectStore that is running in the current thread.

Returns:

The storage system name and release of ObjectStore.

Throws:

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

languageInterfaceName

public static java.lang.String languageInterfaceName()

Returns the name and release of the Java language interface for ObjectStore that is running in the current thread.

Returns:

The language interface name and release of ObjectStore.

languageInterfaceMajorRelease

public static int languageInterfaceMajorRelease()

Returns the major release of the Java language interface for ObjectStore that is running in the current thread.

Returns:

The language interface major release of ObjectStore.

languageInterfaceMinorRelease

public static int languageInterfaceMinorRelease()

Returns the minor release of the Java language interface for ObjectStore that is running in the current thread.

Returns:

The language interface minor release of ObjectStore.

initialize

public static boolean initialize(java.lang.String host,
                                 java.util.Properties properties)

Creates a session that permits the caller to use the rest of the API. This API is maintained for compatibility with previous releases. It might be deprecated in a future release.

The recommended API for creating a session is Session.create() or Session.createGlobal().

Note that when you use a Session create method in place of the ObjectStore.initialize(host, properties) method, you must also call the Session.join() method. While the ObjectStore.initialize(host, properties) method starts a session and joins the calling thread to the session, the Session create methods only start the session. They do not join the calling thread to the session.

If this thread does not already belong to a session and if there is not an active global session, this method

• Initializes ObjectStore for the calling thread by establishing a session
• Returns true to indicate that a session was created
• Joins the calling thread to the new session. This allows the calling thread to use the rest of the ObjectStore API

If this thread already belongs to the session, this method returns false to indicate that it did not start a new session. This is useful when you want to confirm that there is an active session without performing any action.

Parameters:

host - ObjectStore ignores this argument. Specify null.

properties - A property list that contains additional information needed to establish the session. ObjectStore first looks for properties defined in this list and then looks at the system properties list. If ObjectStore cannot find a property in either list it uses the default. All ObjectStore properties start with com.odi. You can pass in property information by making it a system property.

All property values are strings, so if a property value is a Boolean, you must put true and false in double quotation marks.

You can specify the following properties:

• com.odi.addressSpaceSize
• com.odi.applicationName
• com.odi.cacheSize
• com.odi.disableObjectCaching
• com.odi.disableWeakReferences
• com.odi.migrateUnexportedStrings
• com.odi.ObjectStoreLibrary
• com.odi.password
• com.odi.product
• com.odi.queryDebugLevel
• com.odi.stringPoolSize
• com.odi.trapUnregisteredType
• com.odi.useImmediateStrings
• com.odi.user

com.odi.addressSpaceSize - Specifies in bytes, the amount of C++ client address space available for the current session. The actual value used is the amount specified rounded up to the nearest 64 KB.

If the amount of address space requested is not available, an exception is signaled. If the addressSpaceSize property is not specified, the default amount of address space is determined by calls to ObjectStore.setNumExpectedSessions(), as well as the values of the OS_AS_SIZE and OS_DEFAULT_AS_PARTITION_ SIZE environment variables.

com.odi.applicationName - Indicates the name of the application for the current client. This allows users of the LockTimeoutBlocker class or the ossvrstat utility to retrieve information about clients involved in concurrency conflicts. When you set this property, it can provide information about your application to other clients. This property can only be set once - the first time a session is created. Any changes to this property after a session has been created are ignored.

com.odi.cachedObjectCount - Determines the maximum number of objects that are cached if caching is enabled. This value should be greater than 0. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.

com.odi.cachedObjectTransactionAge - Specifies the maximum number of transactions an object is retained in the cache. This value should lie between 1 and 255 (inclusive). A negative value for this property will result in an IllegalArgumentException being thrown and values greater than 255 will be converted to 255. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.

com.odi.cacheSize - Specifies the size of the C++ client cache in bytes. The default is 8388608 bytes, or 0x800000 bytes in hexadecimal. If the value is a String that starts with 0x or 0X, ObjectStore treats the value as a hexadecimal number. ObjectStore rounds the cache size down to the nearest whole number of pages.

com.odi.disableObjectCaching - Allows ObjectStore to decide whether to cache the contents of objects across transactions. When this property is set to false (the default), ObjectStore might choose to cache the contents of active objects when they are made hollow. When this property is set to true, ObjectStore does not cache the contents of objects across transactions.

When an active object is made hollow, ObjectStore might choose to cache the object by not calling the clearContents() method on it. Objects that are in hollow states, but still have their contents from a prior transaction are considered to be cached. When a cached, hollow object is subsequently accessed, ObjectStore checks whether the object's contents are still valid. If the contents are valid, ObjectStore makes the object active without re-reading its contents from the database.

Using the false setting for this property has the advantage of improving the performance of your application by reducing the time needed to fetch objects. However, the disadvantage is that garbage collection is less effective. You might find that the performance of your application degrades over time as unaccessed objects are being cached across many transactions.

To determine whether your application is running slowly because too many objects are being cached, try setting the com.odi.disableObjectCaching property to true. If you see an improvement in performance, then you might want to reduce the number of cached objects either by specifying appropriate values for the com.odi.cachedObjectTransactionAge or com.odi.cachedObjectCount properties, or by decaching some cached objects using the following ObjectStore API methods that manipulate cached objects:

• clearCache()
• decache(Object cachedObject)
• getCachedObjects()

• getCachedObjectTxnAge()

com.odi.disableWeakReferences - A Boolean value that defaults to false. When you specify this property, ObjectStore does not use the weak reference facility.

When you start the first session in a Java process, the setting of the com.odi.disableWeakReferences property is in effect for the duration of the Java process. If you terminate the session and start another session with a different value for the com.odi.disableWeakReferences property, the new value is ignored.

A weak reference to an object is a reference that does not prevent the object from being garbage collected by the Java VM's garbage collector. In its internal Object Table, ObjectStore uses weak references to hold references to unmodified persistent objects. If your program does not have any references to a persistent object and the reference in the object table is the only reference, the object can be garbage collected. If the persistent object has been modified and the changes have not yet been saved, ObjectStore uses a strong reference to hold the reference to the object. A strong reference prevents the object from being garbage collected.

com.odi.migrateUnexportedStrings - Controls what happens when ObjectStore encounters a cross-segment reference to an unexported String object. If this property is not set or if it is set to true, ObjectStore creates a new String object that has the same value as the referenced object. ObjectStore places this new string in the same segment and cluster as the referring object and substitutes this new string for the referenced string. If this property is set to false, ObjectStore throws ObjectNotExportedException if it encounters a reference to a string in another segment and that string is not exported.

com.odi.ObjectStoreLibrary - Specifies the name of the native library that contains the ObjectStore schema and native methods for the application. The name should follow platform conventions for library names. If you do not specify this property, ObjectStore uses the standard library, which provides for primary Java objects but not Java peer objects.

com.odi.user and com.odi.password - Allow you to supply a user name and a password when the ObjectStore Server has Name Password set for the Authentication Required Server parameter.

com.odi.product - Allows you to specify which ObjectStore Java product you want to use. The advantage of com.odi.product is that it allows you to write an application that copies data among PSE, PSE Pro, and ObjectStore databases. You can set this property to one of the following three values: PSE, PSEPro, or ObjectStore. To use any of these products, you must have the software in your CLASSPATH environment variable. When this property is not set, ObjectStore software looks for PSE Pro, then PSE, then ObjectStore, and uses the first product it finds.

The setting of com.odi.product applies only to the session for which it is specified. After you start a session, you cannot change the value of com.odi.product. An example of how to use this property is in the user guide.

com.odi.queryDebugLevel - Allows you to control debugging output when you are using the query facility defined in the com.odi.util.query.Query class. In PSE, this property does nothing.

The default level is 0, which does not output any information. Set the property to a value greater than 0 to print debugging output to System.err. As the value of this property increases, the query facility outputs more information as follows:

• 0 - No debugging information.
• 1 - Indexes that are required and that would be useful; statistics about indexed and nonindexed lookups.
• 5 - Query parser tree and query evaluation tree.
• 10 - Information about generated classes.

com.odi.stringPoolSize - Specifies the maximum size of the persistent string pool. The value of this property specifies the maximum number of newly created strings that ObjectStore can maintain in the string pool. If the number of newly created strings exceeds this number, only the ones that were most recently created and used are tracked by the pool. The default value is 100. Before ObjectStore migrates a string into a segment, it checks the pool to see if a string with the same value is already available in the segment. If it is, the string is reused and ObjectStore does not create a new one. ObjectStore clears the pool at the start of each transaction. You can turn off the pooling mechanism by setting the value of this property to 0.

com.odi.trapUnregisteredType - Used to troubleshoot for ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When ObjectStore encounters a type for which it does not have information, it checks the setting of the com.odi.trapUnregisteredType property.

If the property is not set, ObjectStore creates an instance of the UnregisteredType class to represent the unknown type. Your application continues to run as long as it does not try to use the UnregisteredType object. Often, this can be fine because your application has no need for that particular field. However, if you do try to use the unregistered type, ObjectStore throws ClassCastException.

If com.odi.trapUnregisteredType is set, ObjectStore throws FatalApplicationException and provides a message that indicates the name of the unregistered class. See the user guide for additional information.

com.odi.useImmediateStrings - Specifies whether ObjectStore should attempt to store small Strings as immediates values. Immediate strings are disabled by default, or if the value is set to false. Set the value to true to enable immediate strings.

If you enable immediate strings, Strings of eight characters or less might not be stored as independent objects in the database, unless they are explicitly migrated. The result is smaller databases and the elimination of the run-time overhead of tracking the Strings in the object table.

When immediate strings are in use, applications should not assume that Strings stored as the values of fields in persistent objects will themselves be persistent, unless the application explicitly calls ObjectStore.migrate() on the String.

Note that if you enable immediate strings, immediate string values are not understood by queries on com.odi.coll collections. Queries on com.odi.util collections are not affected by this limitation.

If a query on a com.odi.coll collection accesses a String stored as an immediate value, the query interprets the String as a null object. If a class contains indexable fields, ObjectStore does not store immediate string values in any of the fields for that class. If there are classes with no indexable fields that you reference in queries on com.odi.coll collections and you enable immediate strings, you should call ClassInfo.setAllowsPeerQueries() on the class info for the class in question.

Returns:

True if a session was created and false if not.

Throws:

java.lang.IllegalArgumentException - If the values for any of the specified properties are not valid values.

ObjectStoreException - If there is already a global session.

initialize

public static boolean initialize(java.lang.Thread targetThread)

Associates the calling thread with the session that the targetThread belongs to. This API is maintained for compatibility with previous releases. It might be deprecated in a future release. The recommended API for associating a thread with a session is Session.join().

This call makes the calling thread and the target thread cooperating threads and permits the calling thread to use the rest of the API.

Parameters:

targetThread - Specifies a thread that is associated with an active session.

Returns:

The true constant if the thread is joined to the target thread's session by this operation. This implies that the calling thread did not belong to a session before the call to initialize(). The false constant if the calling thread and target thread were already joined to the session before the call to initialize.

Throws:

java.lang.IllegalArgumentException - If the targetThread argument is null.

NoSessionException - If the target thread is not associated with a session.

WrongSessionException - If the current thread is associated with a session and the current thread's session is not the same as the target thread's session. If you are using PSE, there can be only one session.

shutdown

public static void shutdown(boolean force)

Terminates the session that the calling thread belongs to. This method is maintained for compatibility with previous releases. This method might be deprecated in a future release.

The recommended method to use is Session.terminate(). If ObjectStore has already been shut down for this thread, no further action is taken.

Parameters:

force - If true, shut down no matter how many other threads are cooperating with this thread. If false, disassociate this thread from the session, but only shut down ObjectStore if there are no other cooperating threads.

setLazyWriteLocking

public static void setLazyWriteLocking(boolean onOff)

This is the interface for turning lazy write locking on and off (not available in PSE/PSE Pro). Lazy write locking helps minimize server communications by delaying acquisition of write locks until some future point in time when the client needs to communicate with the server about the object needing the write lock.

This setting persists across ObjectStore.initialize() and ObjectStore.shutdown() calls.

Parameters:

onOff - The new state of the lazy write locking strategy. The initial (default) setting at startup is true.

getLazyWriteLocking

public static boolean getLazyWriteLocking()

Determines the current state of lazy write locking (not available in PSE/PSE Pro).

Returns:

The true constant if lazy write locking is turned on. The false constant if lazy write locking is turned off.

getAutoOpenMode

public static int getAutoOpenMode()

Determines the current default open mode for opening a database automatically to traverse a cross-database reference (not available in PSE/PSE Pro). The default open mode can be set so that automatic opening of databases is not allowed. When this is the default and ObjectStore tries to open a database, ObjectStore throws DatabaseNotOpenException.

Returns:

The current auto-open mode, which is one of the following:

• ObjectStore.UPDATE
• ObjectStore.READONLY
• ObjectStore.MVCC
• ObjectStore.DISABLE_AUTO_OPEN.

Throws:

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

setAutoOpenMode

public static void setAutoOpenMode(int openMode)

Specifies the default open mode when ObjectStore opens a database automatically to traverse a cross-database reference (not available in PSE/PSE Pro). You can also use this method to prevent automatic opening of databases. Specify ObjectStore.DISABLE_AUTO_OPEN for the openMode parameter. Note that this value is not a valid value for the openMode parameter to the Database.open() method. ObjectStore throws DatabaseNotOpenException if it tries to open a closed database.

This setting persists across calls that create and shut down sessions.

If you specify ObjectStore.MVCC as the auto-open mode, you must exercise caution if you have several databases open for MVCC at the same time. Such databases are not necessarily consistent with each other. Unless you are very careful, this can lead to unexpected results.

Parameters:

openMode - Must be one of

• ObjectStore.UPDATE allows opened databases to be modified.
• ObjectStore.READONLY allows opened databases to only be read.
• ObjectStore.MVCC allows opened databases to be read without blocking another session from updating that database.
• ObjectStore.DISABLE_AUTO_OPEN does not allow databases to be automatically opened.

Throws:

java.lang.IllegalArgumentException - If the openMode is invalid. The initial (default) setting is ObjectStore.UPDATE.

ObjectStoreException - If the current thread is not associated with a session and there is no global session.

export

public static void export(java.lang.Object object)

Allows an object to be referred to from another segment (this method is not available in PSE/PSE Pro). If the specified object has already been exported, no action is taken.

Parameters:

object - The object to be exported. It must already be persistent, and it cannot be an instance of a Java primitive wrapper class or null.

Throws:

DatabaseNotOpenException - If the database that contains the object is not open.

java.lang.IllegalArgumentException - If the object to be exported is null.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the application is using PSE or PSE Pro.

ObjectNotFoundException - If the object was not found, either because the object itself, its cluster, its segment, or its database was destroyed, or because the object was local and was fetched in a previous transaction.

ObjectNotPersistentException - If the object is not already persistent.

ObjectStoreException - If the session implied by the object to be exported has been terminated or if the current thread is associated with a session other than the session implied by the object to be exported.

UpdateReadOnlyException - If there is a read-only transaction in progress or if the database is open read only.

export

public static void export(java.lang.Object object,
                          int exportId)

Allows an object to be exported with a specified id. (this method is not available in PSE/PSE Pro).

Parameters:

object - The object to be exported. It must already be persistent, and it cannot be an instance of a Java primitive wrapper class or null.

exportId - The id to be assigned to the specified object when it is exported.

Throws:

DatabaseNotOpenException - If the database that contains the object is not open.

java.lang.IllegalArgumentException - If the object to be exported is null or the export id passed in is not positive.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the application is using PSE or PSE Pro.

ObjectNotFoundException - If the object was not found, either because the object itself, its cluster, its segment, or its database was destroyed, or because the object was local and was fetched in a previous transaction.

ObjectNotPersistentException - If the object is not already persistent.

ObjectStoreException - If the session implied by the object to be exported has been terminated or if the current thread is associated with a session other than the session implied by the object to be exported.

ObjectAlreadyExportedException - If trying to assign an export id to an exported object.

InvalidExportIdException - If trying to assign an object with an export id in use.

UpdateReadOnlyException - If there is a read-only transaction in progress or if the database is open read only.

getExportId

public static int getExportId(java.lang.Object object)

Obtain the export id of an exported object. (this method is not available in PSE/PSE Pro).

Parameters:

object - The object, which must be exported.

Throws:

DatabaseNotOpenException - If the database that contains the object is not open.

java.lang.IllegalArgumentException - If the object to be exported is null.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the application is using PSE or PSE Pro.

ObjectNotFoundException - If the object was not found, either because the object itself, its cluster, its segment, or its database was destroyed, or because the object was local and was fetched in a previous transaction.

ObjectNotPersistentException - If the object is not already persistent.

ObjectNotExportedException - If the object is not exported.

isExported

public static boolean isExported(java.lang.Object object)

Determines whether or not an object is exported (this method always returns false in PSE/PSE Pro).

Parameters:

object - The object, which must already be persistent.

Returns:

The true constant if the object is exported. The false constant if it is not.

Throws:

DatabaseNotOpenException - If the database containing the object is not open.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectNotFoundException - If the object was not found, either because the object itself, its cluster, its segment, or its database was destroyed, or because the object was local and was fetched in a previous transaction.

ObjectNotPersistentException - If the object is not already persistent.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object.

fetch

public static void fetch(java.lang.Object object)

Obtains the contents of a persistent object and makes them available for read access by the application. A program must call this method before it tries to read any fields in the persistent object.

If it does not call this method first, the application might be reading uninitialized data. Normally, the class file postprocessor inserts these calls. After running your program, you might decide to try to improve performance by inserting some fetch() calls yourself. See Optimizing Operations That Retrieve Persistent Objects in Chapter 8 of the API User Guide.

After an object has been fetched in a transaction, it need not have the fetch() method invoked on it again, unless the object has been explicitly evicted by the ObjectStore.evict() method or the transaction has been committed.

An application must be careful not to modify the contents of an object if it called the fetch() method on that object. ObjectStore does not prevent an application from modifying a fetched object. However, ObjectStore does not allow the application to save the modifications in the database. To modify an object, an application must call the dirty() method on that object and have the changes saved by committing the transaction. If an application calls fetch() on a transient object, ObjectStore ignores the call.

If you fetch multiple objects that refer to the same object, it appears as though ObjectStore creates a copy of the referenced object for each reference. In fact, each reference refers to the same object and there are not multiple copies. For example, suppose object A and object B both refer to object C. When you use the == operator on A.C and B.C, the return value is true.

Parameters:

object - The object whose contents must be be fetched. The object must be persistence-capable.

Throws:

DatabaseNotFoundException - If the object was accessed through a cross-database reference to a database that is not found.

DatabaseNotOpenException - If the database containing the object is not open.

NoTransactionInProgressException - If a transaction is not in progress.

NullPointerException - If the object argument is null.

ObjectException - If the object being fetched is a stale object.

ObjectNotFoundException - If the object was destroyed, or its cluster or its segment was destroyed.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object.

deepFetch

public static void deepFetch(java.lang.Object object)

Obtains the contents of the specified object, all objects that object refers to, all objects those objects refer to, and so on. This method is similar to fetch() in that it obtains the contents of a persistent object and makes them available for read access by the application. In addition to obtaining the contents of the specified object, this method also fetches all objects that are reachable from object.

The specified object and all objects that are reachable from the specified object form a set of objects that deepFetch() operates on. If an object in the set is already an active persistent object (in other words, it has been read or modified in the current transaction and its contents are still available), deepFetch() does not actually fetch data for that object. Instead, deepFetch() calls IPersistent.flushContents() on each object that is active and so does not need to have its contents fetched. While this does not write any data in the database, it does provide information about the database format, which deepFetch() requires to provide the contents for objects in the set.

If deepFetch() calls flushContents() on an active persistent object that is in the dirty state, ObjectStore does not change the internal state of the object to clean.

If deepFetch() calls the flushContents() method on an object in the set, it also calls the preFlushContents() method on that object. It is important to note that deepFetch() might call preFlushContents() and flushContents() on an object whether or not the contents of that object have changed. In fact, if there are multiple deepFetch() operations, preFlushContents() and flushContents() might be called multiple times on the same object even though there have been no changes to the contents of that object. Other hook methods are not called between calls to preFlushContents().

You might define the preFlushContents() method to modify transient fields. If you do, and if you access these transient fields after a deepFetch(), you might be accessing invalid data. If you define a preFlushContents() method, and if you call deepFetch(), you must make sure that you define preFlushContents() so that it does not invalidate data that you need to access. The default implementation of preFlushContents() does nothing.

When you call deepFetch(), the object you specify must be persistent. If this method encounters any transient objects, it migrates them to the segment and cluster that contains object. This automatic migration is a temporary restriction. In a future release, it will be possible to pass a transient object as an argument and objects will not be migrated as a side-effect of a deepFetch operation. This automatic migration also means that the preFlushContents method might be called on the migrated object during deepFetch().

Suppose both A and B refer to c. If you invoke deepFetch() on both A and B in the same transaction, there is only one copy of c in your program memory. If you fetch multiple objects that refer to the same object, the references to the target return true when you use the == operator on them. For example, A.c == B.c returns true.

Note that if you serialize A and also serialize B, each has its own copy of c. This is how object serialization works.

Parameters:

object - The object at which the deep fetch begins. This object must be persistent. If you specify null, this method does nothing.

Throws:

NoTransactionInProgressException - If at least one reachable object is not active and there is no transaction in progress.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object, or if the specified object is transient.

ObjectNotFoundException - If the object was destroyed, or its cluster or segment was destroyed.

ObjectException - If the object is stale.

dirty

public static void dirty(java.lang.Object object)

Obtains the contents of a persistent object and allows the contents to be modified and saved in the database. An application must call this method on each persistent object that it wants to update in the database. Also, the application must call this method before it tries to access the contents of the object. If the application does not, it might be accessing uninitialized data. Normally, the Class File Postprocessor inserts these calls. After running your application, you might decide to try to improve performance by inserting some dirty() calls yourself. See Optimizing Operations That Retrieve Persistent Objects in Chapter 8 of the API User Guide.

If an application calls dirty() on a transient object, ObjectStore ignores the call.

Parameters:

object - The object being accessed for modifications. The object must be persistence-capable and modifiable. That is, it cannot be an instance of a String or an instance of a Java primitive wrapper class. If it is, ObjectStore throws ObjectException.

Throws:

DatabaseNotFoundException - If the object was accessed through a cross-database reference to a database that is not found.

DatabaseNotOpenException - If the database containing the object is not open.

NoTransactionInProgressException - If a transaction is not in progress.

NullPointerException - If the object argument is null.

ObjectException - If the object being fetched is a stale object or a String or an instance of a Java primitive wrapper class.

ObjectNotFoundException - If the object was destroyed, or its cluster or segment was destroyed.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object.

UpdateReadOnlyException - If the database is open read only or there is a read-only transaction in progress.

destroy

public static void destroy(java.lang.Object object)

Destroys a persistent object. It is permissable to destroy an object that is referred to by other objects. If you do, there are some issues to consider. See the User Guide, Destroying Objects That Are Referred to By Other Objects.

This method invokes IPersistentHooks.preDestroyPersistent() before it actually destroys the specified object if the object implements the IPersistentHooks interface.

When you invoke ObjectStore.destroy() on an instance of OSHashtable, ObjectStore invokes an implementation of IPersistentHooks.preDestroyPersistent() that calls OSHashtable.destroy().

When you invoke ObjectStore.destroy() on a primary Java object, ObjectStore leaves a tombstone. If any objects try to access the destroyed object, the tombstone causes ObjectStore to throw ObjectNotFoundException. You can garbage collect tombstones with the persistent garbage collector.

There is a bug that prevents ObjectStore from leaving a tombstone when you destroy a Java peer object. This will be fixed in a future release. For now, you must be careful that you do not destroy a Java peer object that is still referred to by another object and then try to use that reference. While doing so is always a mistake, in the current product there is no tombstone to flag the mistake for Java peer objects.

If you invoke destroy() on a Java peer pointer object, the method returns without destroying the object.

Parameters:

object - The object to be destroyed. If it is not persistent, this method has no effect.

Throws:

DatabaseNotOpenException - If the database containing the object to be destroyed is not open.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the object being destroyed is a stale object.

ObjectNotFoundException - If the object was not found, either because the object itself, its cluster, its segment, or its database were destroyed, or because the object was local and was fetched in a previous transaction.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object.

UpdateReadOnlyException - If there is a read-only transaction in progress or if the database is open read only.

migrate

public static void migrate(java.lang.Object object,
                           Placement placement,
                           boolean export)

Moves a persistence-capable object into a database. If you are using PSE/PSE Pro, this method is not particularly useful because each database has only one segment and only one database at a time can be open. This API is provided for compatibility with the Java interface to ObjectStore.

If the object you are migrating is not already persistent, ObjectStore moves it into the segment specified by the placement parameter and makes it exported if requested. The object is made persistent regardless of whether or not it is reachable by transitive persistence. After this method has been invoked on the object, the object is effectively persistent and calling the Segment.of() method on the object returns the segment specified by the placement argument.

If the object is already persistent, is in the segment specified by the placement parameter, and is either exported or not exported as specified, this method does nothing. Otherwise, if the object is persistent, this method throws an exception.

Transitive persistence is the process of automatically migrating into a database those persistence-capable objects that are reachable from already persistent objects.

Parameters:

object - The object to migrate. It must be persistence capable.

placement - The segment or database to migrate the object into. If this argument is a database, then the object is migrated into the default segment of that database. If this argument is null, ObjectStore throws IllegalArgumentException.

export - Export the object if true.

Throws:

DatabaseException - If the placement argument is the transient database.

DatabaseNotOpenException - If the database is not open.

java.lang.IllegalArgumentException - If either the object or placement argument is null, or if the object is already persistent and the segment specified by the placement argument or the export argument disagree with the existing values for the object.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the object argument is a C++ peer object.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object.

SegmentException - If the placement argument is the transient segment or the transient cluster.

SegmentNotFoundException - If the segment is not found.

ClusterNotFoundException - If the cluster is not found.

UpdateReadOnlyException - If there is a read-only transaction in progress or if the database is open read only.

isPersistent

public static boolean isPersistent(java.lang.Object object)

Determines whether or not the argument is persistent.

If the specified object is a peer object that identifies a transient C++ object, this method returns true. This is because the transient C++ object is allocated in the transient database.

Parameters:

object - The object to check.

Returns:

The true constant if the argument is persistent or if the argument is a Java peer object that identifies a transient C++ object. The false constant if it is not persistent or not a peer object that identifies a transient C++ object.

Throws:

ObjectException - If the argument is a stale version of a persistent object. Applications should discard references to persistent objects at the end of a transaction.

evict

public static void evict(java.lang.Object object)

Evicts a persistent object. If the object has been modified and the dirty() method was previously called on the object, (the postprocessor inserts this call) ObjectStore saves the changes in the database. If the transaction aborts, these changes will be removed from the database.

Whether or not the object was modified, ObjectStore clears the contents of the object and it becomes a hollow persistent object. An application must call the fetch() or dirty() method on this object to access its contents again. Typically, you run the postprocessor to insert this call.

The application is responsible for ensuring that no other thread is relying on the contents of the object's being accessible at the time of the eviction. If an application calls evict() on a transient or null object, ObjectStore ignores the call and the application continues.

Equivalent to evict(object, RETAIN_HOLLOW).

Parameters:

object - The object being evicted. It must be persistent.

Throws:

ObjectNotExportedException - If ObjectStore detects a reference from the evicted object to an unexported object in another segment.

ObjectNotFoundException - If the object was destroyed, or its cluster or segment was destroyed.

ObjectNotPersistenceCapableException - If the object being evicted refers to an object that is not persistence capable.

evict

public static void evict(java.lang.Object object,
                         int retain)

Saves, but does not commit, any changes to a persistent object and specifies the state of the evicted object after the eviction.

If you invoke this method outside a transaction, it has meaning only if you specified a retain argument when you committed the previous transaction, and, the retain argument must not have been ObjectStore.RETAIN_STALE.

When you invoke this method inside a transaction, it saves any changes to the specified object. If the transaction commits, ObjectStore commits the changes in the database. If the transaction aborts, ObjectStore makes sure the changes are not in the database.

This method is useful for periodically saving changes before committing a transaction. The state of the evicted object after the eviction varies according to the value specified for the retain argument. The possible values are described below:

• RETAIN_READONLY -- maintains the object as an active persistent object that has been only read and not modified, since ObjectStore has already saved, but not committed, the modifications. ObjectStore retains the modified contents of the object. The contents of the object are available to be read or updated in the usual way. If you modify an object after you evict it, ObjectStore saves the new changes when you commit the transaction or evict the object again. If you specify this value outside a transaction, ObjectStore ignores the call to the evict() method.

• RETAIN_HOLLOW -- makes the object hollow. That is, it resets the contents of the object to default values. This is equivalent to calling evict(object). Specify this value when you want to retain references to the evicted object but you do not expect to read the fields of the object. This value allows the garbage collector to reclaim the space occupied by objects that the evicted object refers to. Since this value makes the specified object hollow, your application can subsequently read or update the object during the same transaction in the usual way. If you modify an object, evict that object, and then reaccess the object's contents in the same transaction, the contents contain the earlier modifications. You can specify this value when you call evict() outside a transaction.

• RETAIN_STALE -- makes the object stale. You can no longer access this object. You can specify this value when you call evict() outside a transaction.

In all cases, the application is responsible for ensuring that no other thread is relying on the contents of the object being accessible at the time of the eviction. If an application calls evict() on a transient or null object, ObjectStore ignores the call and the application continues.

Parameters:

object - The object being evicted. It must be persistent.

retain - The state of the object after eviction. One of RETAIN_READONLY, RETAIN_HOLLOW, or RETAIN_STALE.

Throws:

ObjectNotExportedException - If ObjectStore detects a reference from the evicted object to an unexported object in another segment.

DatabaseNotAffiliatedException - If ObjectStore detects a reference from an evicted object to an object in another database, which is not affiliated with the database containing the evicted object.

ObjectNotFoundException - If the object was destroyed, or its cluster or segment was destroyed.

ObjectNotPersistenceCapableException - If the object being evicted refers to an object that is not persistence capable.

evictAll

public static void evictAll(int retain)

Evicts all persistent objects by running the evict(object, retain) method on all persistent objects known to the session.

Parameters:

retain - Specifies the state of the persistent objects after the eviction. This value must be RETAIN_READONLY, RETAIN_HOLLOW, or RETAIN_STALE. The effect of each value is described in the documentation for evict(object, retain).

Throws:

ObjectNotExportedException - If ObjectStore detects a reference from an evicted object in one segment to an unexported object in another segment.

DatabaseNotAffiliatedException - If ObjectStore detects a reference from an evicted object to an object in another database, which is not affiliated with the database containing the evicted object.

ObjectNotPersistenceCapableException - If one of the objects being evicted refers to an object that is not persistence-capable.

See Also:

ObjectStore.evict(java.lang.Object)

getCachedObjects

public static java.util.Iterator getCachedObjects()

Reports those objects that are currently in the cached state within the current session.

Throws:

ObjectStoreException - If the current thread is not associated with a session.

decache

public static void decache(java.lang.Object cachedObject)

Causes the specified object to no longer be cached.

Parameters:

cachedObject - If the object is in the cached state, the object is transitioned to a hollow state. If the object is in a hollow or active state, no action is taken.

Throws:

ObjectStoreException - If the current thread is not associated with a session or the cached object belongs to a session other than the one to which the current thread is associated.

ObjectException - If the cachedObject is stale.

ObjectNotFoundException - If the cached Object is destroyed.

clearCache

public static void clearCache()

Clears the contents of all objects that are currently in the cached state. Each object that is cleared reverts to the hollow object state. This is equivalent to iterating over all cached objects and calling the decache() method on each one.

Throws:

ObjectStoreException - If the current thread is not attached to a Session.

clearCache

public static void clearCache(int nTransactions)

Clears the contents of objects that are currently in the cached state and which have not been accessed in nTransactions. Each object that is cleared reverts to the hollow object state. Calling this method from outside a transaction is equivalent to calling it from the most recent transaction.

Parameters:

nTransactions - The transaction age of the cached objects to be cleared. This number cannot be greater than 255.

Throws:

java.lang.IllegalArgumentException - If the value specifed is less than or equal to 0.

NoSessionException - If the current thread is not attached to a Session.

getCachedObjectTxnAge

public static int getCachedObjectTxnAge(java.lang.Object cachedObject)

Returns the number of transactions for which the specified object was not accessed. Calling this method from outside a transaction is equivalent to calling it from the most recent transaction.

Parameters:

cachedObject - A persistent object that is cached.

Returns:

The number of transactions for which the object was not accessed. -1 if the cachedObject is not cached or if it is transient.

Throws:

NoSessionException - If the current thread is not joined to a session.

WrongSessionException - If the specified object does not belong to the session the current thread is joined to.

ObjectException - If the specified object is stale.

ObjectNotFoundException - If the specifed object has been destroyed.

isStale

public static final boolean isStale(java.lang.Object object)

Determines whether or not the argument is stale. This method returns meaningful results only for objects whose class or superclass implements com.odi.IPersistent.

Returns:

true if the specified object is stale or was destroyed. Returns false if it is not stale, was not destroyed, or is a transient instance of a persistence-capable object.

isDestroyed

public static final boolean isDestroyed(java.lang.Object object)

Determines whether or not the argument was destroyed. This method returns meaningful results for objects whether or not their class or superclass implements com.odi.IPersistent.

Returns:

true if the specified object was destroyed; false if it was not destroyed or if it is a transient instance of a persistence-capable object.

acquireLock

public static void acquireLock(java.lang.Object object,
                               int lockType,
                               int timeoutMillis)

Attempt to acquire a read or update lock on an object. For ObjectStore, if the object is a persistent C++ peer object, then the entire object is locked. Subobjects that are logically part of the peer object (like the contents of com.odi.coll collections) are not locked. Transient C++ peer objects cannot be locked.

Parameters:

object - - The object to acquire a lock on.

lockType - - The type of lock. Either ObjectStore.READONLY or ObjectStore.UPDATE.

timeoutMillis - > - The number of milliseconds to wait when attempting to acquire the lock. Specifying 0 means only acquire the lock if no waiting is needed. Other positive values are rounded up to the nearest number of seconds and specify the number of milliseconds to wait for the lock to become available. Specifying the constant ObjectStore.WAIT_FOREVER means to wait until the lock becomes available.

However, even when you specify WAIT_FOREVER, ObjectStore might not wait forever. If the attempt to acquire the lock throws DeadlockException in the current session, the transaction is aborted, regardless of the value of the timeoutMillis parameter. ObjectStore throws DeadlockException when two separate sessions try to acquire a lock on the same object at the same time. ObjectStore does not throw DeadlockException when multiple threads that are part of the same session try to acquire a lock on the same object.

Throws:

DeadlockException - If two separate sessions try to acquire a lock on the same object at the same time.

java.lang.IllegalArgumentException - If the object argument is null, if the lockType is not one of ObjectStore.READONLY or ObjectStore.UPDATE, or if the timeoutMillis argument is a negative number other than ObjectStore.WAIT_FOREVER.

LockTimeoutException - If it is not possible to acquire the lock within the specified timeout.

ObjectException - If the object is stale, or if it is a transient C++ peer object.

ObjectNotFoundException - If the object, or the cluster or segment containing the object, is destroyed.

ObjectNotPersistentException - If the object is not persistent.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectStoreException - If the session implied by the specified object has been terminated or if the current thread is associated with a session other than the session implied by the specified object.

UpdateReadOnlyException - If the lockType argument is ObjectStore.UPDATE and either there is a readonly transaction in progress or the database is open readonly.

setNumExpectedSessions

public static void setNumExpectedSessions(int numExpectedSessions)

Specifies the number of simultaneous sessions that application expects to create (not available in PSE or PSE Pro). The value is used to determine the default amount of C++ client address space and C++ client cache space to assign to newly created sessions. The value must be a positive number greater than zero.

This routine must be called before the first session is created.

If not called and the OS_DEFAULT_AS_PARTITION_SIZE environment variable is set, then its value specifies the amount of address space to assign to newly created sessions. Otherwise, all the available address space will, by default, be assigned to newly created sessions.

When using OSC++ 5.1, the value of this property must be 1 if specified.

Parameters:

numExpectedSessions - The number of expected sessions. Must be 1 or greater.

Throws:

java.lang.IllegalArgumentException - If numExpectedSessions is less than 1.

ObjectStoreException - If called after a session has been created.

getNumExpectedSessions

public static int getNumExpectedSessions()

Returns the number of simultaneous sessions that the application can create. Note that this number does not specify a hard limit on the number of simultaneous sessions. The value returned specifies the total number of simultaneous sessions that can be created if the com.odi.addressSpaceSize property is not specified.

The return value does not limit the number of session that can be created with PSE Pro.

setPlacementForSerialization

public static void setPlacementForSerialization(Placement placement)

Sets the com.odi.Placement where certain objects are migrated upon being de-serialized if they cannot be created transiently.

Such object types are com.odi.util.OSTreeSet and com.odi.util.OSTreeMap.

Parameters:

placement - The com.odi.Placement where certain objects will be directly migrated upon de-serialization.

Throws:

java.lang.IllegalArgumentException - If the placement argument is null.

ObjectStoreException - If there is no current session in progress.

getPlacementForSerialization

public static Placement getPlacementForSerialization()

Gets the com.odi.Placement where certain objects are migrated upon being de-serialized if they cannot be created transiently.

Such object types are com.odi.util.OSTreeSet and com.odi.util.OSTreeMap.

Throws:

ObjectStoreException - If there is no current session in progress.

setLockTimeout

public static void setLockTimeout(int milliseconds)

Set the time in milliseconds for which the current session waits when attempting to to acquire a lock. (Not available in PSE and PSE Pro.)

Parameters:

milliseconds - the number of milliseconds to wait when attempting to acquire a lock. Specifying 0 means to acquire the lock only if no waiting is needed. Other positive values are rounded up to the nearest number of seconds and specify the number of milliseconds to wait for the lock to become available. Specifying the constant ObjectStore.WAIT_FOREVER means to wait until the lock becomes available.

Throws:

java.lang.IllegalArgumentException - if milliseconds is a negative number other than ObjectStore.WAIT_FOREVER.

getLockTimeout

public static int getLockTimeout()

Gets the time in milliseconds for which the current session waits when attempting to to acquire a lock. (Not available in PSE and PSE Pro.)

Returns:

the time in milliseconds for which the current session waits when attempting to acquire a lock. A value of ObjectStore.WAIT_FOREVER indicates that the session waits forever if necessary.