Class COM.odi.Database

java.lang.Object
   |
   +----COM.odi.Placement
           |
           +----COM.odi.Database

public class Database

extends Placement

implements ObjectStoreConstants

Do not create subclasses of the Database class. If you do, ObjectStore will not work.

Additional information about databases is in the user guide.

All deprecated public constants now have equivalents in the ObjectStoreConstants class.

allExecute

Deprecated.

allRead

Deprecated.

allWrite

Deprecated.

groupExecute

Deprecated.

groupRead

Deprecated.

groupWrite

Deprecated.

openMVCC

Deprecated.

openReadOnly

Deprecated.

openUpdate

Deprecated.

otherExecute

Deprecated.

otherRead

Deprecated.

otherWrite

Deprecated.

ownerExecute

Deprecated.

ownerRead

Deprecated.

ownerWrite

Deprecated.

acquireLock(int, int)

Attempts to acquire a lock on a database.

check(PrintStream)

Checks all objects in the database to ensure that any objects they refer to exist and are stored in the database.

close()

Closes the database.

close(boolean)

Closes a database and specifies what should happen to any retained objects following the close.

create(String, int)

Creates and opens a database with the specified name.

create(String, int, int)

Creates and opens a database with the specified name and sets the schema installation mode for the database (this method is not available in PSE/PSE Pro).

createRoot(String, Object)

Creates a root with the specified name in this database.

createSegment()

Creates a new segment in the database if you are using ObjectStore, and not PSE or PSE Pro.

destroy()

Closes and destroys the database.

destroyRoot(String)

Destroys the root with the specified name.

evolveSchema(String, String, PersistentTypeSummary)

Evolves the database's schema by making it consistent with the schema defined by the classes in the summary argument (this method is not available in PSE or PSE Pro).

GC()

Collects garbage in the database by invoking Segment.GC() on each segment in the database.

GC(Properties)

Collects garbage in the database by invoking Segment.GC() on each segment in the database according to specified properties.

getDefaultSegment()

Returns the default segment for this database.

getOpenMode()

Retrieves the database open mode.

getPath()

Retrieves the path name of the database.

getRoot(String)

Returns a reference to the object associated with the specified root name.

getRoots()

Returns an enumeration of the roots in the database.

getSegment(int)

Returns a handle to an existing segment.

getSegments()

Returns an enumeration of the segments in the database.

getSizeInBytes()

Retrieves the number of bytes of storage occupied by the database.

installTypes(PersistentTypeSummary)

Installs schema for application types into the database schema in a single operation (this method is not available in PSE/PSE Pro).

isOpen()

Determines whether or not a database is open.

of(Object)

Returns the database that contains the specified object.

open(int)

Opens a database with the specified open mode.

open(String, int)

Opens the database with the specified name.

setDefaultSegment(Segment)

Sets the default segment for this database.

setRoot(String, Object)

Sets the object associated with the specified root name.

show(PrintStream, boolean, boolean)

Displays the contents of the database (this method is not included in PSE).

show(PrintStream, boolean, boolean, Query)

Displays the contents of the database (this method is not included in PSE).

showDB(String, PrintStream, boolean, boolean)

Displays the contents of the database (this method is not included in PSE).

  public final static int ownerRead

Note: ownerRead is deprecated. This constant has been changed to ObjectStoreConstants.OWNER_READ.

  public final static int ownerWrite

Note: ownerWrite is deprecated. This constant has been changed to ObjectStoreConstants.OWNER_WRITE.

  public final static int ownerExecute

Note: ownerExecute is deprecated. This constant has been changed to ObjectStoreConstants.OWNER_EXECUTE.

  public final static int groupRead

Note: groupRead is deprecated. This constant has been changed to ObjectStoreConstants.GROUP_READ.

  public final static int groupWrite

Note: groupWrite is deprecated. This constant has been changed to ObjectStoreConstants.GROUP_WRITE.

  public final static int groupExecute

Note: groupExecute is deprecated. This constant has been changed to ObjectStoreConstants.GROUP_EXECUTE.

  public final static int otherRead

Note: otherRead is deprecated. This constant has been changed to ObjectStoreConstants.OTHER_READ.

  public final static int otherWrite

Note: otherWrite is deprecated. This constant has been changed to ObjectStoreConstants.OTHER_WRITE.

  public final static int otherExecute

Note: otherExecute is deprecated. This constant has been changed to ObjectStoreConstants.OTHER_EXECUTE.

  public final static int allRead

Note: allRead is deprecated. This constant has been changed to ObjectStoreConstants.ALL_READ.

  public final static int allWrite

Note: allWrite is deprecated. This constant has been changed to ObjectStoreConstants.ALL_WRITE.

  public final static int allExecute

Note: allExecute is deprecated. This constant has been changed to ObjectStoreConstants.ALL_EXECUTE.

  public final static int openUpdate

Note: openUpdate is deprecated. This constant has been changed to ObjectStore.UPDATE.

  public final static int openReadOnly

Note: openReadOnly is deprecated. This constant has been changed to ObjectStore.READONLY.

  public final static int openMVCC

Note: openMVCC is deprecated. This constant has been changed to ObjectStore.MVCC.

  public static Database create(String name,
                                int fileMode)

Creates and opens a database with the specified name.

name - The name of the database being created. The name can be a relative or absolute operating system pathname. ObjectStore takes into account local network mount points when interpreting pathnames. So a pathname can refer to a database on a remote host. However, an ObjectStore Server must be running on any host containing an ObjectStore database.

If you want to refer to a database on a remote host for which there is no local mount point, you can use a Server host prefix. This is the name of the remote host followed by a colon (:), as in oak:/foo/bar.odb or jackhammer:c:\bob\mydb.odb. On Windows, you also use UNC pathname.

You can also use locator files to allow access to additional hosts. See ObjectStore Management for information.

fileMode - The protection setting for the created database. Construct this by using the or operator on the values of the file mode constants. The specified mode must provide write permission for the owner of the database. Some operating systems ignore this parameter.

Returns:

An instance of Database that functions as a handle for the database.

Throws: AccessViolationException

If unable to create the database because of a file system access violation.

Throws: DatabaseAlreadyExistsException

If a database with the specified name already exists.

Throws: DatabaseException

If other miscellaneous errors occur during database creation, such as an invalid path name or unknown host.

Throws: IllegalArgumentException

If the database name is null, or if the fileMode argument is invalid, including if the fileMode argument does not specify owner write permission.

Throws: ObjectStoreException

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

Throws: TransactionInProgressException

If there is a transaction in progress.

See Also:

open

  public static Database create(String name,
                                int fileMode,
                                int schemaInstallMode)

Creates and opens a database with the specified name and sets the schema installation mode for the database (this method is not available in PSE/PSE Pro).

Parameters:

name - The name of the database being created. The name can be a relative or absolute operating system pathname. ObjectStore takes into account local network mount points when interpreting pathnames. So a pathname can refer to a database on a remote host. However, an ObjectStore Server must be running on any host containing an ObjectStore database.

If you want to refer to a database on a remote host for which there is no local mount point, you can use a Server host prefix. This is the name of the remote host followed by a colon (:), as in oak:/foo/bar.odb or jackhammer:c:\bob\mydb.odb. On Windows, you also use UNC pathname.

You can also use locator files to allow access to additional hosts. See ObjectStore Management for information.

fileMode - The protection setting for the created database. Construct this by using the or operator on the values of the file mode constants. The specified mode must provide write permission for the owner of the database. Some operating systems ignore this parameter.

schemaInstallMode - Indicates whether to install the database schema in batch or incrementally as needed. The value must be INSTALL_SCHEMA_BATCH or INSTALL_SCHEMA_INCREMENTAL.

Returns:

An instance of Database that functions as a handle for the database.

Throws: AccessViolationException

If unable to create the database because of a file system access violation.

Throws: DatabaseAlreadyExistsException

If a database with the specified name already exists.

Throws: DatabaseException

If other miscellaneous errors occur during database creation, such as an invalid path name or unknown host.

Throws: IllegalArgumentException

If the database name is null, or if the fileMode argument is invalid, including if the fileMode argument does not specify owner write permission, or if schemaInstallMode is not one of the permitted values.

Throws: ObjectStoreException

If the current thread does not belong to a session and there is no global session.

Throws: TransactionInProgressException

If there is a transaction in progress.

See Also:

open

  public static Database open(String name,
                              int openMode)

Opens the database with the specified name. When ObjectStore opens the database, it opens it with the specified open mode. If the database is already open with the specified open mode, ObjectStore returns the handle to the database. The handle is the instance of Database that is associated with the database. ObjectStore creates the instance of Database the first time an application calls Database.create() or Database.open() for a given database name in the current session. The instance of Database is not created when you create the database file in the file system.

When you open a database, it does not matter whether or not a transaction is in progress and it does not matter whether or not the database has already been opened.

If you call this method inside a transaction, it might block. If it is important that the open operation never blocks, call this method outside a transaction.

If you abort a transaction in which you opened a database, the abort operation closes the database.

name - The name of the database being opened. The name can be a relative or absolute operating system pathname. ObjectStore takes into account local network mount points when interpreting pathnames. So a pathname can refer to a database on a remote host. However, an ObjectStore Server must be running on any host containing an ObjectStore database.

If you want to refer to a database on a remote UNIX host for which there is no local mount point, you can use a Server host prefix. This is the name of the remote host followed by a colon (:), as in oak:/foo/bar.

You can also use locator files to allow access to additional hosts. See ObjectStore Management for information.

openMode - One of the following constants:

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

This specifies whether or not the contents of the database can be modified.

Returns:

The instance of Database that represents the database and that functions as a handle for the database. ObjectStore returns this if the database was closed or if the database was already open with the same openMode.

Throws: AccessViolationException

If ObjectStore is unable to read the database because of a file system access violation.

Throws: DatabaseException

If the database is not in a valid format.

Throws: DatabaseUpgradeException

If the database has not been upgraded.

Throws: DatabaseNotFoundException

If a database with that name does not exist.

Throws: IllegalArgumentException

If the database name is null or if the openMode parameter is invalid.

Throws: IncompatibleOpenModeException

If the specified database is already open, but with a different specification for openMode.

Throws: ObjectStoreException

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

  public abstract Database open(int openMode)

Opens a database with the specified open mode. Normally, an application calls this method on a closed database. However, if the database is already open with the specified open mode, ObjectStore returns the handle to the database. The handle is the instance of Database that is associated with your database. ObjectStore creates this instance of Database the first time an application calls Database.create() or Database.open for a given database name in the current Java session. The instance of Database is not created when you create the database file in the file system.

When you open a database, it does not matter whether or not a transaction is in progress, and it does not matter whether or not the database has already been opened.

If you abort a transaction in which you opened a database, the abort operation closes the database.

openMode - One of the following constants:

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

This specifies whether or not the contents of the database can be modified.

Returns:

The instance of Database that represents the the database and that functions as a handle for the database. ObjectStore returns this if the database was closed or if the database was opened with the same openMode.

Throws: AccessViolationException

If ObjectStore is unable to read the database because of a file system access violation.

Throws: DatabaseException

If the database is broken or has the wrong OSJI or OSCI version. A database is considered broken when it has the wrong information at the start of the file and when it is a completely unrelated file, as well as when the database file somehow gets corrupted.

Throws: DatabaseNotFoundException

If a database with that name does not exist.

Throws: DatabaseOpenException

If the database is not closed.

Throws: DatabaseUpgradeException

If the database has not been upgraded.

Throws: IllegalArgumentException

If the openMode parameter is invalid.

Throws: IncompatibleOpenModeException

If the database is already open, but with a different specification for openMode.

Throws: ObjectStoreException

If the session implied by the database is not the same as the session associated with the current thread.

  public abstract boolean isOpen()

Determines whether or not a database is open.

Returns:

The true constant if the database is open, the false constant otherwise. This method always returns false for a database that has been destroyed.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract void close()

Closes the database. A transaction must not be in progress, and the database must be open. After a call to this method

• All persistent objects associated with the database become stale. This includes persistent objects retained after a transaction.
• Operations that require the database to be open throw DatabaseNotOpenException.

To close a database and retain persistent objects as transient objects, call Database.close(retainAsTransient).

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: TransactionInProgressException

If a transaction is in progress.

  public abstract void close(boolean retainAsTransient)

Closes a database and specifies what should happen to any retained objects following the close. A transaction must not be in progress, and the database must be open.

If the retainAsTransient argument is true, ObjectStore makes any retained objects transient. This has no effect on objects in the database. This form of close() is meaningful only if the last commit on the database specified ObjectStore.RETAIN_UPDATE or ObjectStore.RETAIN_READONLY. If retainAsTransient is false, it is equivalent to invoking the close() method without an argument. Any retained objects become stale and access to retained objects ends.

Objects that are retained as transient objects have their own identity that is separate from the objects in the database from which they were created. Therefore, it is possible for an aplication to reopen the database, access the persistent instances, which might have changed, and look at both the transient objects and the persistent objects. The transient objects are snapshots of the objects as they were when the transaction was committed. The persistent objects reflect the current state in the database. The transient objects and the persistent objects are separate objects in the Java VM.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: ObjectStoreException

If retainAsTransient is true and the most recent Transaction.commit() call did not specify ObjectStore.RETAIN_UPDATE or ObjectStore.RETAIN_READONLY.

Throws: TransactionInProgressException

If a transaction is in progress.

  public abstract void destroy()

Closes and destroys the database. A transaction must not be in progress and the database must be open.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: TransactionInProgressException

If a transaction is in progress.

Throws: UpdateReadOnlyException

If the database is not open for update.

  public abstract String getPath()

Retrieves the path name of the database.

Returns:

The path name of the database as it was specified when it was created or opened.

  public abstract long getSizeInBytes()

Retrieves the number of bytes of storage occupied by the database.

Returns:

The database size in bytes.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If no transaction is in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract int getOpenMode()

Retrieves the database open mode. This indicates whether or not you can modify the database contents.

Returns:

If the database is open for update this method returns the ObjectStore.UPDATE constant. If the database is open for readonly this method returns the ObjectStore.READONLY constant. If the database is open for MVCC, this method returns the ObjectStore.MVCC constant.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract Object getRoot(String name)

Returns a reference to the object associated with the specified root name. The user guide provides additional information about obtaining roots. See Chapter 6, Retrieving Persistent Objects.

In the unusual situation that you are manually annotating your code instead of using the postprocessor, an application must make certain calls after obtaining a root. After an application obtains a root, the application must call the Persistent.fetch() or Persistent.dirty() method on an object to be able to access the contents of that object. When you run the Class File Postprocessor it puts these calls in your code for you. If you do not run the postprocessor, you must insert the calls to fetch() and dirty() yourself.

Parameters:

name - The name of the root.

Returns:

A reference to the object associated with the root. A null return value indicates that the object associated with the root is null. It does not indicate the absence of the root.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: DatabaseRootNotFoundException

If there is no root with that name in the database.

Throws: IllegalArgumentException

If the name argument is null.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract void setRoot(String name,
                               Object object)

Sets the object associated with the specified root name.

Parameters:

name - The name of the root.

object - The object to associate with the root. Must be persistence-capable or null. If the object is already persistent, it must either be allocated in this database or be an exported object. For PSE and PSE Pro, the object must be in the same database. If the object is not persistent, ObjectStore migrates it into the default segment of the database when the transaction is committed and then associates it with the root.

Chapter 6 in the API User Guide provides additional information about roots.

Throws: DatabaseException

If this is the transient database. If the object is in a different database and it is not exported.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: DatabaseRootNotFoundException

If there is no root by that name in the database.

Throws: IllegalArgumentException

If the name argument is null.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable and is not null.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: UpdateReadOnlyException

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

  public abstract void createRoot(String name,
                                  Object object)

Creates a root with the specified name in this database.

Parameters:

name - The name of the root.

object - The object to associate with the root. Must be persistence-capable or null. If the object is already persistent, it must either be allocated in this database or be an exported object. If the object is not persistent, ObjectStore migrates it into the default segment of the database when the transaction is committed and then associates it with the root.

The user guide provides additional information about roots.

Throws: DatabaseException

If this is the transient database. If the object is not exported and it is in a different database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: DatabaseRootAlreadyExistsException

If a root with that name already exists in the database.

Throws: IllegalArgumentException

If the name argument is null.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable and is not null.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: UpdateReadOnlyException

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

  public abstract void destroyRoot(String name)

Destroys the root with the specified name.

Parameters:

name - The name of the root.

The user guide provides additional information about roots.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: DatabaseRootNotFoundException

If there is no root by that name in the database.

Throws: IllegalArgumentException

If the name argument is null.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: UpdateReadOnlyException

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

  public abstract DatabaseRootEnumeration getRoots()

Returns an enumeration of the roots in the database. Use the DatabaseRootEnumeration methods to access each of the roots.

The list of roots returned by this method includes a root named _DMA_Database_header. This is an internal root and ObjectStore ensures that you cannot modify it. You must not try to call methods on the value of the _DMA_Database_header root. For example, if you want to obtain the values of all roots in a database, you must either explicitly check for and avoid this root or explicitly look up roots that are known to be user-defined. If you do try to obtain the value of _DMA_Database_header, ObjectStore creates an UnregisteredType object to represent it. If you try to use the UnregisteredType object, ObjectStore throws ClassCastException.

Returns:

The enumeration of the root names in the database. This enumeration is valid only until the end of the transaction. Subsequent access throws a StaleEnumeratorException.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract Segment createSegment()

Creates a new segment in the database if you are using ObjectStore, and not PSE or PSE Pro.

Returns:

The new segment.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: SegmentException

If you are using PSE or PSE Pro. PSE and PSE Pro allow only one segment for application data per database and they create the allowed segment when they create a database.

Throws: UpdateReadOnlyException

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

  public abstract Segment getSegment(int segmentId)

Returns a handle to an existing segment. A call to getSegment() on a given database with a given segment ID always returns the same Segment object.

It is possible for a call to getSegment() to block. If you want to call Segment.acquireLock() and ensure that getSegment() does not block, follow these steps:

1. Store an object in a well-known location. This must be a segment that does not experience contention.

2. Have that object refer to an object in the desired segment.

It is not sufficient to store an object in the desired segment as the value of a database root. When you look up the value of a database root, doing so locks the object referred to by the root.

Parameters:

segmentId - The segment identifier.

Returns:

The segment.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: SegmentNotFoundException

If the segment is not found.

  public abstract Segment getDefaultSegment()

Returns the default segment for this database.

The default segment of the transient database is always the transient segment.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: SegmentNotFoundException

If the default segment is not found.

  public abstract void setDefaultSegment(Segment segment)

Sets the default segment for this database. While this is not not useful in PSE and PSE Pro, since they allow only one segment for application data, this method is provided for compatibility with ObjectStore. In PSE and PSE Pro, this method does nothing.

Parameters:

segment - The segment to make the default segment.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If this database, or the database associated with the segment argument, is not open.

Throws: IllegalArgumentException

If the segment parameter is null or is associated with a different database.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: SegmentNotFoundException

If the specified segment is not found.

  public abstract DatabaseSegmentEnumeration getSegments()

Returns an enumeration of the segments in the database. Use the DatabaseSegmentEnumeration methods to access each of the segments. If you create a segment after the call to getSegments(), the new segment might or might not be in the enumeration. If it is important that the enumeration include the new segment, create the enumeration again.

Returns:

The enumeration of the segments in the database. This enumeration is valid only until the end of the transaction. Subsequent access throws a StaleEnumeratorException.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

See Also:

DatabaseSegmentEnumeration

  public static Database of(Object object)

Returns the database that contains the specified object.

Parameters:

object - The object whose database should be determined. object must be persistent or a Java peer object that identifies a transient C++ object.

Returns:

The database. If object is a Java peer object that identifies a transient C++ object, this method returns the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: IllegalArgumentException

If the name argument is null.

Throws: NoTransactionInProgressException

If a transaction is not 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 persistent.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract void acquireLock(int lockType,
                                   int timeoutMillis)

Attempts to acquire a lock on a database. Locking a database is equivalent to locking all the objects in all the segments in the database.

To release the lock, end the transaction in which you acquired the lock. It is not possible to release a lock during a transaction.

Parameters:

lockType - The lock type. 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: DatabaseNotOpenException

If the database containing the object is not open.

Throws: IllegalArgumentException

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

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: UpdateReadOnlyException

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

  public abstract boolean check(PrintStream out)

Checks all objects in the database to ensure that any objects they refer to exist and are stored in the database. (This method is not included in PSE). When ObjectStore executes this method, it operates on the committed contents of the database and on any changes that have been saved as a result of ObjectStore.evict() or ObjectStore.evictAll(). ObjectStore does not operate on any changes that have been made but not saved.

Parameters:

out - The output stream on which to display errors.

Returns:

true if there were no problems found, false otherwise.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: FatalApplicationException

If the current thread is running PSE.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public void showDB(String dbName,
                     PrintStream out,
                     boolean showObj,
                     boolean showData)

Displays the contents of the database (this method is not included in PSE). When ObjectStore executes this method, it operates on the committed contents of the database and on any changes that have been saved as a result of ObjectStore.evict() or ObjectStore.evictAll(). ObjectStore does not operate on any changes that have been made but not saved.

Parameters:

dbName - The name of the database to be shown.

out - The output stream on which to display the contents.

showObj - true if each object in the database should be shown.

showData - true if values of strings and references should be shown. Setting this option forces showObj to be true.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: FatalApplicationException

If the current thread is running PSE.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public void show(PrintStream out,
                   boolean showObj,
                   boolean showData)

Displays the contents of the database (this method is not included in PSE). When ObjectStore executes this method, it operates on the committed contents of the database and on any changes that have been saved as a result of ObjectStore.evict() or ObjectStore.evictAll(). ObjectStore does not operate on any changes that have been made but not saved.

Parameters:

out - The output stream on which to display the contents.

showObj - true if each object in the database should be shown.

showData - true if values of strings and references should be shown. Setting this option forces showObj to be true.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: FatalApplicationException

If the current thread is running PSE.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract void show(PrintStream out,
                            boolean showObj,
                            boolean showData,
                            Query query)

Displays the contents of the database (this method is not included in PSE). When ObjectStore executes this method, it operates on the committed contents of the database and on any changes that have been saved as a result of ObjectStore.evict() or ObjectStore.evictAll(). ObjectStore does not operate on any changes that have been made but not saved.

Parameters:

out - The output stream on which to display the contents.

showObj - true if each object in the database should be shown.

showData - true if values of strings and references should be shown.

query - If non-null, only include objects which satisfy the query. Not supported in PSE.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: FatalApplicationException

If the current thread is running PSE.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

  public abstract Properties GC()

Collects garbage in the database by invoking Segment.GC() on each segment in the database.

The GC opens the database for update and starts an update transaction. While the GC has a database open, all sessions are blocked from accessing that database. They must wait until the GC closes the database and releases the lock.

If the database is already open in the current session, ObjectStore throws DatabaseOpenException. If the database is open in a concurrent session, the GC waits for that session to close the database.

Returns:

A Properties object that contains information about the results of the GC operation. The properties in this object are

int COM.odi.gc.reclaimedObjects indicates the number of objects reclaimed by the GC.

int COM.odi.gc.reachableObjects indicates the number of objects found to be reachable by the GC. (PSE Pro does not support this property. If you are using PSE Pro, this property is always null.)

Throws: AccessViolationException

If ObjectStore is unable to open the database because of a file system access violation.

Throws: DatabaseNotFoundException

If the database does not exist.

Throws: DatabaseOpenException

If this session already has the database open.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: TransactionException

If a transaction is in progress.

  public abstract Properties GC(Properties GCProperties)

Collects garbage in the database by invoking Segment.GC() on each segment in the database according to specified properties. This method is not included in PSE or PSE Pro. The database must be closed.

Parameters:

GCProperties - Specifies the properties ObjectStore should use during garbage collection. A null value instructs the GC to use the default properties, which are:

int COM.odi.gc.retries specifies the number of times the GC should try to resume the sweep operation if it runs into a lock conflict as it tries to update the segment. The default is 10.

int COM.odi.gc.retryInterval specifies the number of milliseconds the sweep operation waits before it tries to resume a sweep. The default is 1000 milliseconds.

int COM.odi.gc.lockTimeOut specifies the number of milliseconds before the sweep operation times out on a lock conflict. The default is 1000 milliseconds.

int COM.odi.gc.transctionPriority specifies the transaction priority the GC uses when it selects a victim in a deadlock. The default is 0.

int COM.odi.gc.displayGarbage if not zero, objects that are unreachable are not destroyed, but are displayed instead. The argument controls the detail: 0 - no display (the default) 1 - list the total number of candidates for garbage collection 2 - list GC object totals by type (not supported) 3 - list the location of every candidate for garbage collection 4 - list the roots of object graphs of candidates for garbage collection.

Returns:

A Properties object that contains information about the results of the GC operation.

The properties in this object are

int COM.odi.gc.reclaimedObjects indicates the number of objects reclaimed by the GC. int COM.odi.gc.reachableObjects indicates the number of objects found to be reachable by the GC.

Throws: AccessViolationException

If ObjectStore is unable to open the database because of a file system access violation.

Throws: DatabaseNotFoundException

If the database does not exist.

Throws: DatabaseOpenException

If the database is open.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: TransactionException

If a transaction is in progress.

  public abstract void installTypes(PersistentTypeSummary summary)

Installs schema for application types into the database schema in a single operation (this method is not available in PSE/PSE Pro).

First, OSJI attempts to load all classes named directly and indirectly by the persistent type summary provided. Classes named as persistent classes are looked up using java.lang.Class.forName() so that the ClassInfo object for each class gets registered. Classes named as included library summaries are expected to be subclasses of PersistentTypeSummary with a public no-argument constructor available. These classes are also looked up using java.lang.Class.forName() and are then instantiated using java.lang.Class.newInstance() so the persistent class loading process can be recursively applied.

After the loading process is complete, the type definitions for the types are installed in the schema for the database. This allows write lock contention for schema updates to be avoided in later transactions.

Before installing any types, ObjectStore ensures that a ClassInfo object is available for each type to be installed. ObjectStore throws ClassNotRegisteredException as soon as it encounters a class for which it cannot find a ClassInfo object. In this situation, no types are installed.

Parameters:

summary - Summary of persistent types used by this application.

Throws: ClassNotRegisteredException

If the ClassInfo for any of the classes being referenced either directly or indirectly is not found.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: IllegalArgumentException

If summary is null.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database, or if the method is called from PSE or PSE Pro.

Throws: UpdateReadOnlyException

If there is a readonly transaction in progress or if the database is open for readonly.

  public static void evolveSchema(String dbName,
                                  String workdbName,
                                  PersistentTypeSummary summary)

Evolves the database's schema by making it consistent with the schema defined by the classes in the summary argument (this method is not available in PSE or PSE Pro).

With this API you can change the definition of a class that is part of the schema of a database as follows:

• Add instance variables. Each new instance variable is initialized with its default value as described in section 4.6.4 of the Java Language Specification. The new fields are not initialized with the variable initializer even if the class defines one for the new field.

• Remove instance variables.

• Change the type associated with an instance variable. Changing the type associated with an instance variable results in the instance variable being default initialized except in the case when both the old and new instance variables are one of the following primitive types: byte, short, int, float or double. In this case, the appropriate narrowing or widening conversion is applied to the old value, which is then assigned to the new value. Based on the above rule, conversions that involve long or any reference type are not done and the instance variable will be default initialized instead.

You cannnot use this API to change the inheritance hierarchy of a class by adding, removing, or changing a superclass.

If the database contains collections that use indexes, you must first drop the index on the collection, then perform the schema evolution, and then restore the index on the collection.

It is always advisable to make a copy of your database before you evolve it. This allows you to restore the database if there are errors.

Parameters:

dbName - Name of the database to be evolved.

workdbName - Name of the database that is used to checkpoint the state of a schema evolution so that it can be resumed in case it is interrupted. ObjectStore creates this database when it initiates schema evolution and destroys this database after the database identified by dbName has been evolved and the checkpoint information contained in workdb is no longer needed.

summary - The summary of persistent classes that need to be evolved. If you change the definition of a class, the list must include all classes that extend this class in the schema of the database being evolved.

Throws: ClassNotRegisteredException

If the ClassInfo object for any of the classes being referenced, either directly or indirectly, in the summary is not found.

Throws: DatabaseNotFoundException

If the database does not exist.

Throws: IllegalArgumentException

If summary or workdbName is null.

Throws: ObjectStoreException

If the session implied by the database has been terminated or if the current thread is associated with a session other than the session implied by the database.

Throws: SchemaEvolutionException

If an error pertinent to schema evolution was encountered. In most cases, this results in the workdb being retained, so that schema evolution can be resumed if the problem can be corrected. Schema evolution can be resumed by reinvoking schema evolution with the same arguments. It uses the checkpointed information in the workdb to resume where it left off.

Throws: TransactionInProgressException

If a transaction is in progress.

Throws: UpdateReadOnlyException

If the database is open for readonly.