com.odi
Class ObjectStore

java.lang.Object
  com.odi.ObjectStore

All Implemented Interfaces:

ObjectStoreConstants

public class ObjectStore

extends 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(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(Object cachedObject) Causes the specified object to no longer be cached.
static void	deepFetch(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(Object object) Destroys a persistent object.
static void	dirty(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(Object object) Evicts a persistent object.
static void	evict(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	evictAndForget(Object object) Deprecated. The evictAndForget() method first evicts an object as described in ObjectStore.evict(), and then removes the internally maintained association between this object and its persistent representation. Before invoking this method, the application must ensure that any persistent objects that contained references to this object have been evicted. After this method is invoked, the object cannot be used for any purpose. That is, its contents should not be accessed, nor should it be used for identity comparisons. Use this method with extreme caution, and only if you find that your application is consuming excessive amounts of heap space within a transaction.
static void	export(Object object) Allows an object to be referred to from another segment (this method is not available in PSE/PSE Pro)
static void	export(Object object, int exportId) Allows an object to be exported with a specified id.
static void	fetch(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 Iterator	getCachedObjects() Reports those objects that are currently in the cached state within the current session.
static int	getCachedObjectTxnAge(Object cachedObject) Returns the number of transactions for which the specified object was not accessed.
static int	getExportId(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(String host, Properties properties) Creates a session that permits the caller to use the rest of the API.
static boolean	initialize(Thread targetThread) Associates the calling thread with the session that the targetThread belongs to.
static boolean	isDestroyed(Object object) Determines whether or not the argument was destroyed.
static boolean	isExported(Object object) Determines whether or not an object is exported (this method always returns false in PSE/PSE Pro)
static boolean	isPersistent(Object object) Determines whether or not the argument is persistent.
static boolean	isStale(Object object) Determines whether or not the argument is stale.
static int	languageInterfaceMajorRelease() Returns the major release of the Java language interface for PSE/PSE Pro that is running in the current thread.
static int	languageInterfaceMinorRelease() Returns the minor release of the Java language interface for PSE/PSE Pro that is running in the current thread.
static String	languageInterfaceName() Returns the name and release of the Java language interface for PSE/PSE Pro that is running in the current thread.
static int	maintenanceRelease() Returns the maintenance release version of PSE/PSE Pro for Java running in the current thread.
static int	majorRelease() Returns the major release version of PSE/PSE Pro for Java running in the current thread.
static void	migrate(Object object, Placement placement, boolean export) Moves a persistence-capable object into a database.
static int	minorRelease() Returns the minor release version of PSE/PSE Pro for Java running in the current thread.
static String	productName() Returns the product name and release of PSE/PSE Pro that is running in the current thread.
static 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 String	storageSystemName() Returns the name and release of the storage system for PSE/PSE Pro that is running in the current thread.
static void	useFileNatives(int value) Deprecated.
static int	whichProduct() Returns a value that identifies the ObjectStore Java product that is running in the current thread.

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, Constant Field Values

PSEProEdition

public static final int PSEProEdition

Deprecated.

Use PSE_PRO in place of this deprecated field.

See Also:

ObjectStoreConstants.PSE_PRO, Constant Field Values

ObjectStoreEdition

public static final int ObjectStoreEdition

Deprecated.

Use OBJECTSTORE in place of this deprecated field.

See Also:

ObjectStoreConstants.OBJECTSTORE, Constant Field Values

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), Constant Field Values

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), Constant Field Values

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), Constant Field Values

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, Constant Field Values

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, Constant Field Values

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, Constant Field Values

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, Constant Field Values

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, Constant Field Values

Method Detail

majorRelease

public static int majorRelease()

Returns the major release version of PSE/PSE Pro for Java running in the current thread.

Returns:

The major release of PSE/PSE Pro.

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 PSE/PSE Pro for Java running in the current thread.

Returns:

The minor release of PSE/PSE Pro.

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 PSE/PSE Pro for Java running in the current thread.

Returns:

The maintenace release of PSE/PSE Pro.

Throws:

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

useFileNatives

public static void useFileNatives(int value)

Deprecated.

productName

public static String productName()

Returns the product name and release of PSE/PSE Pro that is running in the current thread.

Returns:

The product name and release of PSE/PSE Pro.

Throws:

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

releaseName

public static 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 String storageSystemName()

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

Returns:

The storage system name and release of PSE/PSE Pro.

Throws:

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

languageInterfaceName

public static String languageInterfaceName()

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

Returns:

The language interface name and release of PSE/PSE Pro.

languageInterfaceMajorRelease

public static int languageInterfaceMajorRelease()

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

Returns:

The language interface major release of PSE/PSE Pro.

languageInterfaceMinorRelease

public static int languageInterfaceMinorRelease()

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

Returns:

The language interface minor release of PSE/PSE Pro.

initialize

public static boolean initialize(String host,
                                 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 PSE/PSE Pro 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 PSE/PSE Pro API

When the three conditions listed below all exist, this method returns false to indicate that it did not start a new session.

• The calling thread is already associated with a session.
• The associated session is not a global session.
• The host parameter in this invocation of the initialize() method is exactly the same as the host value that was specified when the session was created.

Parameters:

host - This parameter can be null. If the calling thread already belongs to a session, PSE/PSE Pro compares the value you specify here with the value that was specified for the host parameter when the current session was created. If the values are not the same, PSE/PSE Pro throws IllegalArgumentException.

properties - A property list that contains additional information needed to establish the session. PSE/PSE Pro first looks for properties defined in this list and then looks at the system properties list. If PSE/PSE Pro cannot find a property in either list it uses the default. All PSE/PSE Pro 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.disableCrossTransactionCaching
• com.odi.disableWeakReferences
• com.odi.queryDebugLevel
• com.odi.stringPoolSize
• com.odi.trapUnregisteredType
• com.odi.useDatabaseLocking
• com.odi.useFsync
• com.odi.useImmediateStrings

com.odi.disableCrossTransactionCaching - A Boolean value that defaults to true. This means that PSE/PSE Pro makes retained objects hollow at the start of a new transaction. This is the same way that ObjectStore functions. When this property is set to false, at the beginning of a new transaction, PSE/PSE Pro does not hollow objects whose contents were retained after a committed transaction. This means that after you commit a transaction with ObjectStore.RETAIN_READONLY or ObjectStore.RETAIN_UPDATE, you have access to all objects that you read or updated during the previous transaction. If you then start a new transaction, the contents of objects that were retained are not hollowed out. If you always retain object contents when you commit a transaction, you have access to all objects you read or updated in the current session.

This property will be deprecated in a future release when an API that performs a similar function is available.

com.odi.disableWeakReferences - A Boolean value that defaults to false. When you specify this property, PSE/PSE Pro 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, PSE/PSE Pro 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, PSE/PSE Pro uses a strong reference to hold the reference to the object. A strong reference prevents the object from being garbage collected.

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 PSE/PSE Pro 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. In PSE Pro, the default is 100. In PSE, the default is 0, that is, string pooling is disabled by default. In PSE, there is no persistent garbage collector and so string pooling might not be safe. Before PSE/PSE Pro 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 PSE/PSE Pro does not create a new one. PSE/PSE Pro 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 PSE/PSE Pro 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, PSE/PSE Pro 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, PSE/PSE Pro throws ClassCastException.

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

com.odi.useDatabaseLocking - Allows you to turn cross-process locking off. By default, cross-process locking is turned on. This means that if a session has a database open, a session in another Java VM process cannot open that database. If a session tries to open a database that is already open in another process, PSE/PSE Pro throws com.odi.DatabaseLockedException.

com.odi.useFsync - A Boolean value that defaults to true. If it is false, disk buffers are not forced to disk from the underlying operating system buffers prior to commit. It is recommended that this be left at the default setting of true.

com.odi.useImmediateStrings - Specifies whether PSE/PSE Pro should attempt to store small Strings as immediate values. Immediate strings are enabled by default, or if the value is set to true. Set the value to false to disable immediate strings.

If immediate strings are enabled, 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.

Returns:

True if a session was created and false if not.

FatalApplicationException - If you are running PSE and there is already an active session and the current thread does not belong to the session.

IllegalArgumentException - If you try to restart PSE/PSE Proa (call the initialize() method again) and the host that was originally specified and the host specified in the current call are not both null or not equal.

ObjectStoreException - If there is already a global session.

initialize

public static boolean initialize(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 same session before the call to initialize.

Throws:

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 PSE/PSE Pro 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 PSE/PSE Pro 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).

getLazyWriteLocking

public static boolean getLazyWriteLocking()

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

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

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

export

public static void export(Object object)

Allows an object to be referred to from another segment (this method is not available in PSE/PSE Pro).

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

export

public static void export(Object object,
                          int exportId)

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

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

getExportId

public static int getExportId(Object object)

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

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

isExported

public static boolean isExported(Object object)

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

fetch

public static void fetch(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. PSE/PSE Pro does not prevent an application from modifying a fetched object. However, PSE/PSE Pro 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, PSE/PSE Pro ignores the call.

If you fetch multiple objects that refer to the same object, it appears as though PSE/PSE Pro 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(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, PSE/PSE Pro 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(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, PSE/PSE Pro 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, PSE/PSE Pro 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(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, PSE/PSE Pro invokes an implementation of IPersistentHooks.preDestroyPersistent() that calls OSHashtable.destroy().

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

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(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, PSE/PSE Pro moves it into the segment or database specified by the placement parameter. 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 not exported, 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, PSE/PSE Pro throws IllegalArgumentException.

export - Export the object if true. This must be false because exported objects are not allowed in PSE/PSE Pro. If you specify true for the export parameter, PSE/PSE Pro throws ObjectException.

DatabaseNotOpenException - If the database is not open.

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 you are using PSE/PSE Pro and the export argument is true.

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.

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(Object object)

Determines whether or not the argument is persistent.

Parameters:

object - The object to check.

Returns:

The true constant if the argument is persistent. The false constant if it is not persistent.

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(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) PSE/PSE Pro 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, PSE/PSE Pro 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, PSE/PSE Pro ignores the call and the application continues.

Equivalent to evict(object, RETAIN_HOLLOW).

Parameters:

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

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(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, PSE/PSE Pro commits the changes in the database. If the transaction aborts, PSE/PSE Pro 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 PSE/PSE Pro has already saved, but not committed, the modifications. PSE/PSE Pro 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, PSE/PSE Pro saves the new changes when you commit the transaction or evict the object again. If you specify this value outside a transaction, PSE/PSE Pro 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, PSE/PSE Pro 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.

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

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

See Also:

ObjectStore.evict(java.lang.Object)

evictAndForget

public static void evictAndForget(Object object)

Deprecated. The evictAndForget() method first evicts an object as described in ObjectStore.evict(), and then removes the internally maintained association between this object and its persistent representation. Before invoking this method, the application must ensure that any persistent objects that contained references to this object have been evicted. After this method is invoked, the object cannot be used for any purpose. That is, its contents should not be accessed, nor should it be used for identity comparisons.

Use this method with extreme caution, and only if you find that your application is consuming excessive amounts of heap space within a transaction.

Parameters:

object - The object being evicted. It must be persistent. PSE/PSE Pro ignores transient and null arguments.

See Also:

ObjectStore.evict(java.lang.Object)

getCachedObjects

public static Iterator getCachedObjects()

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

Returns:

an Iterator that reports all of the cached objects in the current session. The remove() method decaches the previous element returned by next(). The iterator remains valid until one of the following happens first:

• Session termination
• A call to the Transaction.begin()method
• A call to the Transaction.checkpoint() method At that point the iteration is considered to have terminated and:
  • Throws java.util.NoSuchElementException() from Iterator.next()
  • Throws java.lang.IllegalStateException from Iterator.remove()
  • Returns false() from Iterator.hasNext()
  Throws:
  ObjectStoreException - If the current thread is not associated with a session.

decache

public static void decache(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:

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(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(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(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(Object object,
                               int lockType,
                               int timeoutMillis)

Attempt to acquire a read or update lock on an object. (Not available in PSE and PSE Pro.)

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:

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.

Returns:

the number of simultaneous sessions that can be created.

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:

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

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