Class COM.odi.ObjectStore

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

public class ObjectStore
extends Object

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

ALL_EXECUTE: File mode for all execute permission.
ALL_READ: File mode for all read permission.
ALL_WRITE: File mode for all write permission.
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. Deprecated.
fileNativesNone: The argument to specify in a call to useFileNatives() when you do not want to use the native library. 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. Deprecated.
GROUP_EXECUTE: File mode for group execute permission.
GROUP_READ: File mode for group read permission.
GROUP_WRITE: File mode for group write permission.
majorRelease: Use majorRelease() in place of this deprecated field. Deprecated.
minorRelease: Use minorRelease() in place of this deprecated field. Deprecated.
OBJECTSTORE: The whichProduct() method returns this value if you are running the Java interface to ObjectStore.
ObjectStoreEdition: Use OBJECTSTORE in place of this deprecated field. Deprecated.
OPEN_READONLY: Open mode for read-only.
OPEN_READONLY_NON_BLOCKING: Open mode for read-only, but don't block waiting for the database lock.
OPEN_UPDATE: Open mode for update.
OPEN_UPDATE_NON_BLOCKING: Open mode for update, but don't block waiting for the database lock.
OTHER_EXECUTE: File mode for other execute permission.
OTHER_READ: File mode for other read permission.
OTHER_WRITE: File mode for other write permission.
OWNER_EXECUTE: File mode for owner execute permission.
OWNER_READ: File mode for owner read permission.
OWNER_WRITE: File mode for owner write permission.
PSE: The whichProduct() method returns this value if you are running ObjectStore PSE/PSE Pro.
PSE_PRO: The whichProduct() method returns this value if you are running ObjectStore PSE Pro.
PSEEdition: Use PSE in place of thie deprecated field. Deprecated.
PSEProEdition: Use PSE_PRO in place of this deprecated field. Deprecated.
READONLY: The type value for a read-only transaction.
RETAIN_HOLLOW: The retain value when calling commit(int) or evict(Object, int) to maintain all persistent objects but evict their contents.
RETAIN_READONLY: The retain value when calling commit(int) or evict(Object, int) to maintain all persistent objects and retain their contents as well.
RETAIN_STALE: The retain value when calling commit(int) or evict(Object, int) to forget all persistent objects after the commit.
RETAIN_UPDATE: The retain value when calling commit(int) to maintain all persistent objects, retain their contents, and permit persistent objects to be modified between transactions.
UPDATE: The type value for an update transaction.

destroy(Object): Destroys a persistent object.
edition(): Use whichProduct() in place of this deprecated method. Deprecated.
evict(Object): Evicts a persistent object.
evict(Object, int): Evicts a persistent object.
evictAll(int): Evicts all persistent objects by running the evict(Object, int) method on all persistent objects known to the session.
evictAndForget(Object): The method evictAndForget() is a temporary device to deal with a limitation in version 1.0.2 of the JDK. Deprecated.
initialize(String, Properties): Initializes PSE/PSE Pro, permitting the caller to use the rest of the API.
initialize(Thread): Initializes PSE/PSE Pro and associates the calling thread with the targetThread.
isDestroyed(Object): Determines whether the argument is destroyed.
isPersistent(Object): Determines whether the argument is persistent.
isStale(Object): Determines whether the argument is stale.
languageInterfaceMajorRelease(): Returns the major release of the Java language interface for PSE/PSE Pro that is running in the current thread.
languageInterfaceMinorRelease(): Returns the minor release of the Java language interface for PSE/PSE Pro that is running in the current thread.
languageInterfaceName(): Returns the name and release of the Java language interface for PSE/PSE Pro that is running in the current thread.
majorRelease(): Returns the major release version of PSE/PSE Pro for Java running in the current thread.
migrate(Object, Segment, boolean): Moves a persistence-capable object into a database.
minorRelease(): Returns the minor release version of PSE/PSE Pro for Java running in the current thread.
productName(): Returns the product name and release of PSE/PSE Pro that is running in the current thread.
releaseName(): Use productName() in place of this deprecated method. Deprecated.
shutdown(boolean): Shuts down PSE/PSE Pro for this thread.
storageSystemName(): Returns the name and release of the storage system for PSE/PSE Pro 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.

majorRelease

  public static int majorRelease

Note: majorRelease is deprecated.

Use majorRelease() in place of this deprecated field.

See Also:: majorRelease

minorRelease

  public static int minorRelease

Note: minorRelease is deprecated.

Use minorRelease() in place of this deprecated field.

See Also:: minorRelease

PSE

  public final static int PSE

The whichProduct() method returns this value if you are running ObjectStore PSE/PSE Pro.

PSEEdition

  public final static int PSEEdition

Note: PSEEdition is deprecated.

Use PSE in place of thie deprecated field.

See Also:: PSE

PSE_PRO

  public final static int PSE_PRO

The whichProduct() method returns this value if you are running ObjectStore PSE Pro.

PSEProEdition

  public final static int PSEProEdition

Note: PSEProEdition is deprecated.

Use PSE_PRO in place of this deprecated field.

See Also:: PSE_PRO

OBJECTSTORE

  public final static int OBJECTSTORE

The whichProduct() method returns this value if you are running the Java interface to ObjectStore.

ObjectStoreEdition

  public final static int ObjectStoreEdition

Note: ObjectStoreEdition is deprecated.

Use OBJECTSTORE in place of this deprecated field.

See Also:: OBJECTSTORE

fileNativesNone

  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.

See Also:: useFileNatives

fileNativesIfAvailable

  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.

See Also:: useFileNatives

fileNativesRequired

  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.

See Also:: useFileNatives

RETAIN_STALE

  public final static int RETAIN_STALE

The retain value when calling commit(int) or evict(Object, int) to forget all persistent objects after the commit.

RETAIN_HOLLOW

  public final static int RETAIN_HOLLOW

The retain value when calling commit(int) or evict(Object, int) to maintain all persistent objects but evict their contents.

RETAIN_READONLY

  public final static int RETAIN_READONLY

The retain value when calling commit(int) or evict(Object, int) to maintain all persistent objects and retain their contents as well.

RETAIN_UPDATE

  public final static int RETAIN_UPDATE

The retain value when calling commit(int) to maintain all persistent objects, retain their contents, and permit persistent objects to be modified between transactions.

OWNER_READ

  public final static int OWNER_READ

File mode for owner read permission.

See Also:: create

OWNER_WRITE

  public final static int OWNER_WRITE

File mode for owner write permission.

See Also:: create

OWNER_EXECUTE

  public final static int OWNER_EXECUTE

File mode for owner execute permission.

See Also:: create

GROUP_READ

  public final static int GROUP_READ

File mode for group read permission.

See Also:: create

GROUP_WRITE

  public final static int GROUP_WRITE

File mode for group write permission.

See Also:: create

GROUP_EXECUTE

  public final static int GROUP_EXECUTE

File mode for group execute permission.

See Also:: create

OTHER_READ

  public final static int OTHER_READ

File mode for other read permission.

See Also:: create

OTHER_WRITE

  public final static int OTHER_WRITE

File mode for other write permission.

See Also:: create

OTHER_EXECUTE

  public final static int OTHER_EXECUTE

File mode for other execute permission.

See Also:: create

ALL_READ

  public final static int ALL_READ

File mode for all read permission.

See Also:: create

ALL_WRITE

  public final static int ALL_WRITE

File mode for all write permission.

See Also:: create

ALL_EXECUTE

  public final static int ALL_EXECUTE

File mode for all execute permission.

See Also:: create

OPEN_UPDATE

  public final static int OPEN_UPDATE

Open mode for update.

See Also:: open

OPEN_READONLY

  public final static int OPEN_READONLY

Open mode for read-only.

See Also:: open

OPEN_UPDATE_NON_BLOCKING

  public final static int OPEN_UPDATE_NON_BLOCKING

Open mode for update, but don't block waiting for the database lock.

See Also:: open

OPEN_READONLY_NON_BLOCKING

  public final static int OPEN_READONLY_NON_BLOCKING

Open mode for read-only, but don't block waiting for the database lock.

See Also:: open

READONLY

  public final static byte READONLY

The type value for a read-only transaction.

UPDATE

  public final static byte UPDATE

The type value for an update transaction.

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.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread.

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 PSE/PSE Pro is not initialized for the current thread.

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 PSE/PSE Pro is not initialized for the current thread.

releaseName

  public static String releaseName()

Note: releaseName() is deprecated.

Use productName() in place of this deprecated method.

See Also:: productName

whichProduct

  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 PSE/PSE Pro is not initialized for the current thread.

edition

  public static int edition()

Note: edition() is deprecated.

Use whichProduct() in place of this deprecated method.

See Also:: 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 PSE/PSE Pro is not initialized for the current thread.

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)

Initializes PSE/PSE Pro, permitting the caller to use the rest of the API.

If initialize() has not already been called for this thread, then this method

Initializes PSE/PSE Pro for the calling thread
Returns true to indicate that initialization was performed
Allows the calling thread to use the rest of the PSE/PSE Pro for Java API

If initialize() has already been called for this thread then this method checks whether or not the host specified here is the same as the host that was specified in the original call to the initialize() method. If the hosts are equal or both null then this method returns false to indicate that it did not initialize PSE/PSE Pro. This is useful when you want to confirm that PSE/PSE Pro is initialized without performing any action. If the hosts are not equal, PSE/PSE Pro throws IllegalArgumentException.

The original call to initialize() and subsequent calls can specify a null argument for the host.

If you call this method on a thread that is cooperating with other threads, PSE/PSE Pro returns false to indicate that it has not done the initialization. PSE/PSE Pro does not make the calling thread an independent thread.

Parameters:

host - This parameter is ignored.

properties - A property list containing additional information needed to establish the connection with the server. Legal values are:

COM.odi.disableWeakLinks: This is a boolean value which defaults to false. If it is true the weak link functions in ObjectStore are disabled, even if they are available in the underlying virtual machine. Setting this to false causes weak link support to be used if it's available in the virtual machine. Currently, only Sun's JDK 1.1 has weak link support.
COM.odi.useDatabaseLocking: This is a boolean value which defaults to false. If it is true, then database locking is performed. This property is only recognized by PSE and PSE Pro.
COM.odi.useFsync: This is a boolean value which 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. This property is only recognized by PSE and PSE Pro.

Returns:

The true constant if an initialization was performed. The false constant if not.

Throws: FatalApplicationException

If you are running PSE and you already initialized PSE/PSE Pro in a thread that is still active and you try to initialize PSE/PSE Pro in an independent thread.

Throws: IllegalArgumentException

If you try to restart PSE/PSE Pro (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.

initialize

  public static boolean initialize(Thread targetThread)

Initializes PSE/PSE Pro and associates the calling thread with the targetThread. This makes the calling thread and the target thread cooperative threads and permits the caller to use the rest of the API.

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: ObjectStoreException: If PSE/PSE Pro is already initialized for the calling thread and the calling thread's session is not the same as the target thread's session. If you are using PSE, you would not see this exception because there can be only one session.
Throws: IllegalArgumentException: If the targetThread argument is null.

shutdown

  public static void shutdown(boolean force)

Shuts down PSE/PSE Pro for this thread. If PSE/PSE Pro has already been shut down for this thread, no further action is taken.

Parameters:: force - If true, perform the shutdown no matter how many other threads are cooperating with this thread. If false, disassociate this thread from any cooperating threads, but only shut down PSE/PSE Pro if there are no other cooperating threads.

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 so, there are some issues to consider.

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 PSE/PSE Pro is not initialized for the current thread or if the object is not associated with this thread.
Throws: 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,
                             Segment segment,
                             boolean export)

Moves a persistence-capable object into a database. If the object is not already persistent, it is moved into the specified segment and exported if requested (if you are using ObjectStore DBMS). 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 denoted by the segment argument.

If the object is already persistent, is in the segment specified, and is either exported or not exported as specified, the method does nothing. Otherwise, if the object is persistent, 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.; segment - The segment to migrate the object into. If this argument is null, PSE/PSE Pro throws IllegalArgumentException.; export - Export the object if true. This applies only if you are using the Java interface to ObjectStore Development Client.
Throws: DatabaseNotOpenException: If the database is not open.
Throws: IllegalArgumentException: If the object argument is null.
Throws: NoTransactionInProgressException: If there is no transaction in progress.
Throws: ObjectException: If export was specified in ObjectStore PSE or PSE Pro.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the object is not associated with this thread.
Throws: SegmentNotFoundException: If the segment is not found.
Throws: IllegalArgumentException: If either the object or segment arguments are null.
Throws: UpdateReadOnlyException: If there is a read-only transaction in progress or if the database is open read-only.

useFileNatives

  public static void useFileNatives(int value)

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

isPersistent

  public static boolean isPersistent(Object object)

Determines whether 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: is thrown 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 dirty() method was previously called on the object and a transaction is in progress, ObjectStore saves the changes in the database when the transaction is committed. 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. 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 call. 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: ObjectNotFoundException: If the object was destroyed, or its segment was destroyed.

evict

  public static void evict(Object object,
                           int retain)

Evicts a persistent object. What gets evicted is controlled by the value of the retain argument:

RETAIN_READONLY -- If a transaction is in progress and the object is modified, prevents additional changes and arranges to save the changes to the database when the transaction is committed. If no transaction is in progress, resets the contents of the object to default values. Outside a transaction, this performs the same function as RETAIN_HOLLOW.
RETAIN_HOLLOW -- If a transaction is in progress and the object is modified, prevents additional changes and arranges to save the changes to the database when the transaction commits. Always resets the contents of the object to default values.
RETAIN_STALE -- If a transaction is in progress and the object is modified, arranges to save the changes to the database when the transaction commits. Always resets the contents of the object to default values and makes it stale.

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 call. 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 following eviction. One of RETAIN_READONLY, RETAIN_HOLLOW, or RETAIN_STALE.
Throws: ObjectNotFoundException: If the object was destroyed, or its segment was destroyed.

evictAll

  public static void evictAll(int retain)

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

See Also:: evict

evictAndForget

  public static void evictAndForget(Object object)

Note: evictAndForget() is deprecated.

The method evictAndForget() is a temporary device to deal with a limitation in version 1.0.2 of the JDK. It is expected that this limitation will be fixed in an upcoming release of the JDK. When it is fixed this method will be obsolete and will be phased out of the API.

It may still be useful to use this method on platforms which do not implement "weak references". The JDK 1.1 implements such references making use of this method unnecessary.

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:: evict

isStale

  public final static boolean isStale(Object object)

Determines whether the argument is stale. This function only returns meaningful results for objects which inherit from COM.odi.Persistent.

Returns:: true if the Persistent object is Stale or Destroyed; false if it's not stale or destroyed or if it's a transient instance of a Persistent object.

isDestroyed

  public final static boolean isDestroyed(Object object)

Determines whether the argument is destroyed. This function only returns meaningful results for objects which inherit from COM.odi.Persistent.

Returns:: true if the Persistent object is destroyed; false if it's not destroyed or if it's a transient instance of a Persistent object.