Class COM.odi.ObjectStore

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

public class ObjectStore

extends Object

implements ObjectStoreConstants

fileNativesIfAvailable

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 (this variable is not available in PSE or ObjectStore). Deprecated.

fileNativesNone

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

fileNativesRequired

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 (this variable is not available in PSE or ObjectStore). Deprecated.

majorRelease

Use majorRelease() in place of this deprecated field. Deprecated.

minorRelease

Use minorRelease() in place of this deprecated field. Deprecated.

ObjectStoreEdition

Use OBJECTSTORE in place of this deprecated field. Deprecated.

OPEN_MVCC

Open mode for multiversion concurrency control (MVCC).

OPEN_READONLY

Database open mode for read only.

OPEN_READONLY_NON_BLOCKING

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

OPEN_UPDATE

Database open mode for update.

OPEN_UPDATE_NON_BLOCKING

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

PSEEdition

Use PSE in place of this deprecated field. Deprecated.

PSEProEdition

Use PSE_PRO in place of this deprecated field. Deprecated.

acquireLock(Object, int, int)

Attempt to acquire a read or update lock on an object.

deepFetch(Object)

Obtains the contents of the specified object, all objects that object refers to, all objects those objects refer to, and so on.

destroy(Object)

Destroys a persistent object.

dirty(Object)

Obtains the contents of a persistent object and allows the contents to be modified and saved in the database.

edition()

Use whichProduct() in place of this deprecated method. Deprecated.

evict(Object)

Evicts a persistent object.

evict(Object, int)

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

evictAll(int)

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

evictAndForget(Object)

Deprecated.

export(Object)

Allows a primary persistent object or an ObjectStore collection object to be referred to from another segment (this method is not available in PSE/PSE Pro).

fetch(Object)

Obtains the contents of a persistent object and makes them available for read access by the application.

getAutoOpenMode()

Determines the current default open mode for automatically opening a database to traverse a cross-database reference (this method has no effect in PSE/PSE Pro).

getLazyWriteLocking()

Determines the current state of lazy write locking (this method has no effect in PSE/PSE Pro).

initialize(String, Properties)

Creates a session, which permits the caller to use the rest of the API.

initialize(Thread)

Associates the calling thread with the session that the targetThread belongs to.

isDestroyed(Object)

Determines whether or not the argument was destroyed.

isExported(Object)

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

isPersistent(Object)

Determines whether or not the argument is persistent.

isStale(Object)

Determines whether or not the argument is stale.

languageInterfaceMajorRelease()

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

languageInterfaceMinorRelease()

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

languageInterfaceName()

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

majorRelease()

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

migrate(Object, Placement, boolean)

Moves a persistence-capable object into a database.

minorRelease()

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

productName()

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

releaseName()

Use productName() in place of this deprecated method. Deprecated.

setAutoOpenMode(int)

Specifies the default open mode when ObjectStore automatically opens a database to traverse a cross-database reference (this method has no effect in PSE/PSE Pro).

setLazyWriteLocking(boolean)

This is the interface for turning lazy write locking on and off (this method has no effect in PSE/PSE Pro).

shutdown(boolean)

Terminates the session that the calling thread belongs to.

storageSystemName()

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

useFileNatives(int)

Deprecated.

whichProduct()

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

  public static int majorRelease

Note: majorRelease is deprecated.

Use majorRelease() in place of this deprecated field.

See Also:

majorRelease

  public static int minorRelease

Note: minorRelease is deprecated.

Use minorRelease() in place of this deprecated field.

See Also:

minorRelease

  public final static int PSEEdition

Note: PSEEdition is deprecated.

Use PSE in place of this deprecated field.

See Also:

PSE

  public final static int PSEProEdition

Note: PSEProEdition is deprecated.

Use PSE_PRO in place of this deprecated field.

See Also:

PSE_PRO

  public final static int ObjectStoreEdition

Note: ObjectStoreEdition is deprecated.

Use OBJECTSTORE in place of this deprecated field.

See Also:

OBJECTSTORE

  public final static int fileNativesNone

Note: fileNativesNone is deprecated.

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

See Also:

useFileNatives

  public final static int fileNativesIfAvailable

Note: fileNativesIfAvailable is 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 (this variable is not available in PSE or ObjectStore).

See Also:

useFileNatives

  public final static int fileNativesRequired

Note: fileNativesRequired is 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 (this variable is not available in PSE or ObjectStore).

See Also:

useFileNatives

  public final static int OPEN_UPDATE

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:

open, UPDATE

  public final static int OPEN_READONLY

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:

open, READONLY

  public final static int OPEN_MVCC

Open mode for multiversion concurrency control (MVCC).

See Also:

open, MVCC

  public final static int OPEN_UPDATE_NON_BLOCKING

Note: OPEN_UPDATE_NON_BLOCKING is deprecated.

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

See Also:

UPDATE_NON_BLOCKING

  public final static int OPEN_READONLY_NON_BLOCKING

Note: OPEN_READONLY_NON_BLOCKING is deprecated.

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

See Also:

READONLY_NON_BLOCKING

  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.

  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.

  public static void useFileNatives(int value)

Note: useFileNatives() is deprecated. The PSE Pro File Natives have been eliminated from PSE Pro 1.1.

  public static 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.

  public static String releaseName()

Note: releaseName() is deprecated.

Use productName() in place of this deprecated method.

See Also:

productName

  public static int whichProduct()

Returns a value that identifies the Object Design 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.

  public static int edition()

Note: edition() is deprecated.

Use whichProduct() in place of this deprecated method.

See Also:

whichProduct

  public static 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.

  public static 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.

  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.

  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.

  public static boolean initialize(String host,
                                   Properties properties)

Creates a session, which 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.

You can specify the following properties:

• COM.odi.applicationName
• COM.odi.cacheSize
• COM.odi.disableWeakReferences
• COM.odi.migrateUnexportedStrings
• COM.odi.ObjectStoreLibrary
• COM.odi.password
• COM.odi.product
• COM.odi.stringPoolSize
• COM.odi.trapUnregisteredType
• COM.odi.user

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.

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.disableWeakReferences is a Boolean value that defaults to "false". (Remember that all property values are strings, so you must enclose true and false in quotation marks.) 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.

The COM.odi.migrateUnexportedStrings property 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 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 Object Design 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, Object Design 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.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. 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.

The COM.odi.trapUnregisteredType property is useful for troubleshooting 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.

Returns:

True if a session was created and false if not.

Throws: FatalApplicationException

If you already initialized ObjectStore in a thread that is still active and you try to initialize ObjectStore in a thread that does not cooperate with the active thread. ObjectStore allows only one session and all threads must cooperate in that session.

Throws: ObjectStoreException

If there is already a global session.

  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 session before the call to initialize.

Throws: IllegalArgumentException

If the targetThread argument is null.

Throws: ObjectStoreException

If the target thread is not associated with a session.

  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.

  public static void setLazyWriteLocking(boolean onOff)

This is the interface for turning lazy write locking on and off (this method has no effect 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.

  public static boolean getLazyWriteLocking()

Determines the current state of lazy write locking (this method has no effect 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.

  public static int getAutoOpenMode()

Determines the current default open mode for automatically opening a database to traverse a cross-database reference (this method has no effect in PSE/PSE Pro). The default open mode can be 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 or ObjectStore.READONLY or ObjectStore.MVCC or ObjectStore.DISABLE_AUTO_OPEN.

Throws: ObjectStoreException

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

  public static void setAutoOpenMode(int openMode)

Specifies the default open mode when ObjectStore automatically opens a database to traverse a cross-database reference (this method has no effect 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: IllegalArgumentException

If the openMode is invalid. The initial (default) setting is ObjectStore.UPDATE.

Throws: ObjectStoreException

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

  public static void export(Object object)

Allows a primary persistent object or an ObjectStore collection 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.

It is more efficient to make an object exported when it first becomes persistent than after it is stored. To export an object when it is stored, call the ObjectStore.migrate() method and specify true for the export argument. Calling ObjectStore.export() to export an object that is already in a database takes time proportional to the total number of nonprimitive fields in objects in the segment that contains the object being exported.

While you can export ObjectStore collection objects, you cannot export any other kind of Java peer object.

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.

Throws: IllegalArgumentException

If the object to be exported is null.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectException

If the application is using PSE or PSE Pro. In ObjectStore, if the object is a C++ peer object.

Throws: ObjectNotFoundException

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

Throws: ObjectNotPersistentException

If the object is not already persistent.

Throws: 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.

Throws: UpdateReadOnlyException

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

  public static boolean isExported(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.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectNotFoundException

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

Throws: ObjectNotPersistentException

If the object is not already persistent.

Throws: 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.

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

Throws: DatabaseNotOpenException

If the database containing the object is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: NullPointerException

If the object argument is null.

Throws: ObjectException

If the object being fetched is a stale object.

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable.

Throws: 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.

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

Throws: 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.

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectException

If the object is stale.

  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 it does not, it might be accessing 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 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.

Throws: DatabaseNotOpenException

If the database containing the object is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: NullPointerException

If the object argument is null.

Throws: ObjectException

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

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable.

Throws: 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.

Throws: UpdateReadOnlyException

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

  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 IPersistent.preDestroyPersistent() before it actually destroys the specified object.

When you invoke ObjectStore.destroy() on an instance of OSHashtable, ObjectStore invokes an implementation of IPersistent.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.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectException

If the object being destroyed is a stale object.

Throws: ObjectNotFoundException

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

Throws: 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.

Throws: UpdateReadOnlyException

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

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

Throws: DatabaseNotOpenException

If the database is not open.

Throws: 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.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectException

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

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable.

Throws: 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.

Throws: SegmentException

If the placement argument is the transient segment.

Throws: SegmentNotFoundException

If the segment is not found.

Throws: UpdateReadOnlyException

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

  public static boolean isPersistent(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.

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

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectNotPersistenceCapableException

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

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

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectNotPersistenceCapableException

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

  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.

Throws: ObjectNotPersistenceCapableException

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

See Also:

evict

  public static void evictAndForget(Object object)

Note: evictAndForget() is deprecated. The evictAndForget() method was a temporary device to deal with a limitation in version 1.0.2 of the JDK.

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. ObjectStore ignores transient and null arguments.

See Also:

evict

  public final static 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.

  public final static 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.

  public static void acquireLock(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. One of 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.

Throws: 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.

Throws: LockTimeoutException

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

Throws: ObjectException

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

Throws: ObjectNotFoundException

If the object, or the segment containing the object, is destroyed.

Throws: ObjectNotPersistentException

If the object is not persistent.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: 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.

Throws: UpdateReadOnlyException

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