com.odi
Class Database

java.lang.Object
  com.odi.Placement
      com.odi.Database

All Implemented Interfaces:

ObjectStoreConstants

public abstract class Database

extends Placement

implements ObjectStoreConstants

The Database class is an abstract class that represents a database. For each database you create or open, PSE/PSE Pro automatically finds the subclass of Database and creates an instance of that subclass. PSE/PSE Pro then associates the instance with your database. The instance represents your database and provides a handle to your database. Consequently, you can use object identity comparison operators to determine whether or not two Database instances represent the same database.

Do not create subclasses of the Database class. If you do, PSE/PSE Pro will not work.

Additional information about databases is in the user guide.

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

Field Summary

static int	allExecute Deprecated. This constant has been changed to ObjectStoreConstants.ALL_EXECUTE.
static int	allRead Deprecated. This constant has been changed to ObjectStoreConstants.ALL_READ.
static int	allWrite Deprecated. This constant has been changed to ObjectStoreConstants.ALL_WRITE.
static int	groupExecute Deprecated. This constant has been changed to ObjectStoreConstants.GROUP_EXECUTE.
static int	groupRead Deprecated. This constant has been changed to ObjectStoreConstants.GROUP_READ.
static int	groupWrite Deprecated. This constant has been changed to ObjectStoreConstants.GROUP_WRITE.
static int	openMVCC Deprecated. This constant has been changed to ObjectStore.MVCC.
static int	openReadOnly Deprecated. This constant has been changed to ObjectStore.READONLY.
static int	openUpdate Deprecated. This constant has been changed to ObjectStore.UPDATE.
static int	otherExecute Deprecated. This constant has been changed to ObjectStoreConstants.OTHER_EXECUTE.
static int	otherRead Deprecated. This constant has been changed to ObjectStoreConstants.OTHER_READ.
static int	otherWrite Deprecated. This constant has been changed to ObjectStoreConstants.OTHER_WRITE.
static int	ownerExecute Deprecated. This constant has been changed to ObjectStoreConstants.OWNER_EXECUTE.
static int	ownerRead Deprecated. This constant has been changed to ObjectStoreConstants.OWNER_READ.
static int	ownerWrite Deprecated. This constant has been changed to ObjectStoreConstants.OWNER_WRITE.

Fields inherited from interface com.odi.ObjectStoreConstants

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

Method Summary

abstract void	acquireLock(int lockType, int timeoutMillis) Attempts to acquire a lock on a database
abstract void	affiliate(Database targetDatabase, boolean deep) Marks this database to permit storing in it references to the target database (not available in PSE or PSE Pro).
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 (not available in PSE)
abstract void	close() Closes the database.
abstract void	close(boolean retainAsTransient) Closes a database and specifies what should happen to any retained objects following the close.
static Database	create(String name, int fileMode) Creates and opens a database with the specified name
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)
static Database	create(String name, int fileMode, int schemaInstallMode, Database schemaDatabase) Creates and opens a database with the specified name and sets the schema database for the database (this method is not available in PSE/PSE Pro)
abstract void	createRoot(String name, Object object) Creates a root with the specified name in this database.
abstract Segment	createSegment() Creates a new segment in the database if you are using ObjectStore, and not PSE or PSE Pro.
abstract void	destroy() Closes and destroys the database.
abstract void	destroyRoot(String name) Destroys the root with the specified name.
static void	evolveSchema(String[] dbNames, String workdbName, PersistentTypeSummary summary) Evolves the databases' schema by making it consistent with the schema defined by the classes in the summary argument (not available in PSE or PSE Pro).
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 (not available in PSE or PSE Pro).
abstract Properties	GC() Collects garbage in the database by invoking Segment.GC() on each segment in the database.
abstract Properties	GC(Properties GCProperties) Collects garbage in the database by invoking Segment.GC() on each segment in the database according to specified properties.
abstract Iterator	getAffiliatedDatabases() Returns an iterator of the databases affiliated with this database (not available in PSE or PSE Pro).
abstract Segment	getDefaultSegment() Returns the default segment for this database.
abstract String	getHostName() Gets the host containing this database.
abstract int	getOpenMode() Retrieves the database open mode.
abstract String	getPath() Retrieves the path name of the database.
abstract Object	getRoot(String name) Returns a reference to the object associated with the specified root name.
abstract DatabaseRootEnumeration	getRoots() Returns an enumeration of the roots in the database.
abstract Database	getSchemaDatabase() Gets the schema database for this database.
abstract Segment	getSegment(int segmentId) Returns a handle to an existing segment.
abstract DatabaseSegmentEnumeration	getSegments() Returns an enumeration of the segments in the database.
abstract long	getSizeInBytes() Retrieves the number of bytes of storage occupied by the database
abstract void	installTypes(PersistentTypeSummary summary) Installs schema for application types into the database schema in a single operation (not available in PSE/PSE Pro).
abstract boolean	isOpen() Determines whether or not a database is open.
static Database	of(Object object) Returns the database that contains the specified object.
abstract Database	open(int openMode) Opens a database with the specified open mode.
static Database	open(String name, int openMode) Opens the database with the specified name.
abstract void	setDefaultSegment(Segment segment) Sets the default segment for this database.
abstract void	setRoot(String name, Object object) Sets the object associated with the specified root name.
abstract void	setSchemaDatabase(Database schemaDb) Sets the schema database for this database if the schema is stored remotely (not available in PSE Pro).
void	show(PrintStream out, boolean showObj, boolean showData) Displays the contents of the database (not available in PSE)
abstract void	show(PrintStream out, boolean showObj, boolean showData, Query query) Displays the contents of the database (not available in PSE)
void	showDB(String dbName, PrintStream out, boolean showObj, boolean showData) Displays the contents of the database (not available in PSE)

Methods inherited from class com.odi.Placement

getCluster, getDatabase, getSegment, getSession

Field Detail

ownerRead

public static final int ownerRead

Deprecated. This constant has been changed to ObjectStoreConstants.OWNER_READ.

See Also:

Constant Field Values

ownerWrite

public static final int ownerWrite

Deprecated. This constant has been changed to ObjectStoreConstants.OWNER_WRITE.

See Also:

Constant Field Values

ownerExecute

public static final int ownerExecute

Deprecated. This constant has been changed to ObjectStoreConstants.OWNER_EXECUTE.

See Also:

Constant Field Values

groupRead

public static final int groupRead

Deprecated. This constant has been changed to ObjectStoreConstants.GROUP_READ.

See Also:

Constant Field Values

groupWrite

public static final int groupWrite

Deprecated. This constant has been changed to ObjectStoreConstants.GROUP_WRITE.

See Also:

Constant Field Values

groupExecute

public static final int groupExecute

Deprecated. This constant has been changed to ObjectStoreConstants.GROUP_EXECUTE.

See Also:

Constant Field Values

otherRead

public static final int otherRead

Deprecated. This constant has been changed to ObjectStoreConstants.OTHER_READ.

See Also:

Constant Field Values

otherWrite

public static final int otherWrite

Deprecated. This constant has been changed to ObjectStoreConstants.OTHER_WRITE.

See Also:

Constant Field Values

otherExecute

public static final int otherExecute

Deprecated. This constant has been changed to ObjectStoreConstants.OTHER_EXECUTE.

See Also:

Constant Field Values

allRead

public static final int allRead

Deprecated. This constant has been changed to ObjectStoreConstants.ALL_READ.

See Also:

Constant Field Values

allWrite

public static final int allWrite

Deprecated. This constant has been changed to ObjectStoreConstants.ALL_WRITE.

See Also:

Constant Field Values

allExecute

public static final int allExecute

Deprecated. This constant has been changed to ObjectStoreConstants.ALL_EXECUTE.

See Also:

Constant Field Values

openUpdate

public static final int openUpdate

Deprecated. This constant has been changed to ObjectStore.UPDATE.

See Also:

Constant Field Values

openReadOnly

public static final int openReadOnly

Deprecated. This constant has been changed to ObjectStore.READONLY.

See Also:

Constant Field Values

openMVCC

public static final int openMVCC

Deprecated. This constant has been changed to ObjectStore.MVCC.

See Also:

Constant Field Values

Method Detail

create

public static Database create(String name,
                              int fileMode)

Creates and opens a database with the specified name. When PSE/PSE Pro creates a database, it creates two files. Together, these two files make up your database. One file has the name that you specify or pass when you call this method: path_name.odb. The other file has the same name except that PSE/PSE Pro replaces .odb with .odt. If you move or copy a database, be sure to keep both files together in the same directory.

Parameters:

name - The name of the database being created. The name can be an absolute or relative file name; it is interpreted in the context of the local file system. The name you specify or pass must end with the .odb extension. For example, mydatabase.odb is a valid name specification.

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.

PSE/PSE Pro checks to ensure that owner write permission is provided but otherwise ignores 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.

DatabaseAlreadyExistsException - If a database with the specified name already exists.

DatabaseException - If other miscellaneous errors occur during database creation, such as an invalid path name or unknown host. Thrown by PSE/PSE Pro if a database is open.

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.

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

TransactionInProgressException - If there is a transaction in progress.

See Also:

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

create

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

ObjectStoreException - If the current session is a PSE or PSE Pro session.

See Also:

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

create

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

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

ObjectStoreException - If the current session is a PSE or PSE Pro session.

See Also:

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

open

public static Database open(String name,
                            int openMode)

Opens the database with the specified name. When PSE/PSE Pro opens the database, it opens it with the specified open mode.

If the database is already open with the specified open mode, PSE/PSE Pro returns the handle to the database. The handle is the instance of Database that is associated with the database. PSE/PSE Pro 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.

Parameters:

name - The name of the database being opened. The name can be an absolute or relative path name; it is interpreted in the context of the local file system. The name you specify or pass must end with the .odb extension. For example, myDatabase.odb is a valid name specification.

openMode - One of the following constants:

• ObjectStore.UPDATE
• ObjectStore.READONLY
• ObjectStore.UPDATE_NON_BLOCKING
• ObjectStore.READONLY_NON_BLOCKING

This specifies whether or not the contents of the database can be modified and what action to take if the database is locked by another user or session. If either ObjectStore.UPDATE or ObjectStore.READONLY is specified and the database is locked by another user, the open blocks until the database becomes available. If either of the _NON_BLOCKING options is specified and the database is locked by another user, PSE/PSE Pro throws DatabaseLockedException and the open operation does not succeed. Database locking is disabled by default. You can enable it by setting the property com.odi.useDatabaseLocking to "true".

Returns:

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

Throws:

AccessViolationException - If PSE/PSE Pro is unable to read the database because of a file system access violation.

DatabaseException - If an attempt is made to open multiple databases per Session or for miscellaneous database errors.

DatabaseFormatException - If the database is broken or has the wrong PSE/PSE Pro 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.

DatabaseLockedException - If an attempt to open the database with either ObjectStore.UPDATE_NON_BLOCKING or ObjectStore.UPDATE_NON_BLOCKING mode is made and the database is locked by another user.

DatabaseUpgradeException - If the database has not been upgraded.

DatabaseNotFoundException - If a database with that name does not exist.

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

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

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

open

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, PSE/PSE Pro returns the handle to the database. The handle is the instance of Database that is associated with your database. PSE/PSE Pro 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.

Parameters:

openMode - One of the following constants:

• ObjectStore.UPDATE
• ObjectStore.READONLY
• ObjectStore.UPDATE_NON_BLOCKING
• ObjectStore.READONLY_NON_BLOCKING

This specifies whether or not the contents of the database can be modified and what action to take if the database is locked by another user or session.

If either ObjectStore.UPDATE or ObjectStore.READONLY is specified and the database is locked by another user, the open will block until the database becomes available.

If either of the _NON_BLOCKING options are specified and the database is locked by another user, a DatabaseLockedException will be thrown and the open will not succeed. Database locking is disabled by default, but can be enabled by setting the property com.odi.useDatabaseLocking to true.

Returns:

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

Throws:

AccessViolationException - If PSE/PSE Pro is unable to read the database because of a file system access violation.

DatabaseException - If an attempt is made to open multiple databases per Session or for miscellaneous database errors.

DatabaseFormatException - If the database is broken or has the wrong PSE/PSE Pro 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.

DatabaseLockedException - If an attempt to open the database with either ObjectStore.UPDATE_NON_BLOCKING or ObjectStore.UPDATE_NON_BLOCKING mode is made and the database is locked by another user.

DatabaseNotFoundException - If a database with that name does not exist.

DatabaseOpenException - If the database is not closed.

DatabaseUpgradeException - If the database has not been upgraded.

IllegalArgumentException - If the openMode parameter is invalid.

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

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

isOpen

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.

close

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

DatabaseNotOpenException - If the database is not open.

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.

TransactionInProgressException - If a transaction is in progress.

close

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

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.

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

TransactionInProgressException - If a transaction is in progress.

destroy

public abstract void destroy()

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

DatabaseNotOpenException - If the database is not open.

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.

TransactionInProgressException - If a transaction is in progress.

UpdateReadOnlyException - If the database is not open for update.

getPath

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.

getSizeInBytes

public abstract long getSizeInBytes()

Retrieves the number of bytes of storage occupied by the database. This includes both the .odb and the .odt files.

Returns:

The database size in bytes.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If no transaction is in progress.

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.

getOpenMode

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 or update nonblocking, this method returns the ObjectStore.UPDATE constant. If the database is open for read-only or read-only nonblocking, this method returns the ObjectStore.READONLY constant.

Throws:

DatabaseNotOpenException - If the database is not open.

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.

getRoot

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.

DatabaseNotOpenException - If the database is not open.

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

IllegalArgumentException - If the name argument is null.

NoTransactionInProgressException - If there is no transaction in progress.

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.

setRoot

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

DatabaseNotOpenException - If the database is not open.

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

IllegalArgumentException - If the name argument is null.

NoTransactionInProgressException - If there is no transaction in progress.

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

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.

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

createRoot

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 be in the same database.

If the object is not persistent, PSE/PSE Pro 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.

DatabaseNotOpenException - If the database is not open.

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

IllegalArgumentException - If the name argument is null.

NoTransactionInProgressException - If there is no transaction in progress.

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

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.

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

destroyRoot

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.

DatabaseNotOpenException - If the database is not open.

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

IllegalArgumentException - If the name argument is null.

NoTransactionInProgressException - If there is no transaction in progress.

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.

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

getRoots

public abstract DatabaseRootEnumeration getRoots()

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

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.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

createSegment

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.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

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.

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

getSegment

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.

Parameters:

segmentId - The segment identifier.

Returns:

The segment.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

SegmentNotFoundException - If the segment is not found.

getDefaultSegment

public abstract Segment getDefaultSegment()

Returns the default segment for this database.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

SegmentNotFoundException - If the default segment is not found.

setDefaultSegment

public abstract void setDefaultSegment(Segment segment)

Sets the default segment for this database. While this is not useful in PSE and PSE Pro, because 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.

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

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

NoTransactionInProgressException - If a transaction is not in progress.

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.

SegmentNotFoundException - If the specified segment is not found.

getSegments

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.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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

of

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.

Returns:

The database.

Throws:

DatabaseNotOpenException - If the database is not open.

IllegalArgumentException - If the name argument is null.

NoTransactionInProgressException - If a transaction is not in progress.

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.

ObjectNotPersistentException - If the object is not persistent.

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.

acquireLock

public abstract void acquireLock(int lockType,
                                 int timeoutMillis)

Attempts to acquire a lock on a database. This method does nothing in PSE and PSE Pro.

affiliate

public abstract void affiliate(Database targetDatabase,
                               boolean deep)

Marks this database to permit storing in it references to the target database (not available in PSE or PSE Pro).

Invoking this method causes the target database to become affiliated with this database and writes an entry in its pathname pool to the target database.

You must call affiliate() once for each target database that will contain objects pointed to by objects in the specified database. Calling affiliate() again has no effect if the target database is already affiliated with this database.

Parameters:

targetDatabase - The target database to affiliate with this database. References from this database to the target database are allowed after this call.

deep - If true, the call to affiliate() causes all databases affiliated with the target database, in addition to the target database itself, to be affiliated with this database.

If false, only the target database is affiliated. Use the true value if the target database contains references to objects in other databases that you expect this database to refer to.

Throws:

DatabaseException - If this or the target database is the transient database.

DatabaseNotOpenException - If this database or the target database is not open.

IllegalArgumentException - If the targetDatabase argument is null or if it belongs to a different session than the one implied by this database.

ObjectStoreException - In ObjectStore, 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. PSE and PSE Pro always throw ObjectStoreException.

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

getAffiliatedDatabases

public abstract Iterator getAffiliatedDatabases()

Returns an iterator of the databases affiliated with this database (not available in PSE or PSE Pro). This is the set of databases for which this database can contain references to objects.

Returns:

A read-only iterator of the affiliated databases.

This iterator must be used within the transaction in which it is created or it will raise StaleIteratorException. The iterator raises UnsupportedOperationException if remove is called.

Throws:

DatabaseException - If the database is the transient database.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

ObjectStoreException - In ObjectStore, if the session implied by the database has been terminated, if the current thread is associated with a session other than the session implied by the database. PSE and PSE Pro always throw ObjectStoreException.

check

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 (not available in PSE). When PSE Pro 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().

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

DatabaseNotOpenException - If the database is not open.

FatalApplicationException - If the current thread is running PSE.

NoTransactionInProgressException - If a transaction is not in progress.

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.

showDB

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

Displays the contents of the database (not available in PSE). When PSE Pro 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().

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

DatabaseNotOpenException - If the database is not open.

FatalApplicationException - If the current thread is running PSE.

NoTransactionInProgressException - If a transaction is not in progress.

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.

show

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

Displays the contents of the database (not available in PSE). When PSE Pro 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().

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

DatabaseNotOpenException - If the database is not open.

FatalApplicationException - If the current thread is running PSE.

NoTransactionInProgressException - If a transaction is not in progress.

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.

show

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

Displays the contents of the database (not available in PSE). When PSE Pro 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().

PSE Pro 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 that satisfy the query (not available in PSE).

DatabaseNotOpenException - If the database is not open.

FatalApplicationException - If the current thread is running PSE.

NoTransactionInProgressException - If a transaction is not in progress.

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.

GC

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 or in a concurrent session, PSE/PSE Pro throws DatabaseOpenException.

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 PSE/PSE Pro is unable to open the database because of a file system access violation.

DatabaseNotFoundException - If the database does not exist.

DatabaseOpenException - If this session already has the database open.

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.

TransactionException - If a transaction is in progress.

GC

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. Not available in PSE or PSE Pro.

installTypes

public abstract void installTypes(PersistentTypeSummary summary)

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

ObjectStoreException - If this method is called from PSE or PSE/Pro.

evolveSchema

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 (not available in PSE or PSE Pro).

ObjectStoreException - If the method is called from PSE or PSE Pro.

evolveSchema

public static void evolveSchema(String[] dbNames,
                                String workdbName,
                                PersistentTypeSummary summary)

Evolves the databases' schema by making it consistent with the schema defined by the classes in the summary argument (not available in PSE or PSE Pro).

ObjectStoreException - If the method is called from PSE or PSE Pro.

getHostName

public abstract String getHostName()

Gets the host containing this database. (not available in PSE or PSE Pro).

Throws:

NoTransactionInProgressException - if there is no current transaction.

getSchemaDatabase

public abstract Database getSchemaDatabase()

Gets the schema database for this database. (not available in PSE Pro).

setSchemaDatabase

public abstract void setSchemaDatabase(Database schemaDb)

Sets the schema database for this database if the schema is stored remotely (not available in PSE Pro).