Class COM.odi.Database

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

public class Database
extends Object

The Database class is an abstract class that represents a database. For each database you create, PSE/PSE Pro associates it with exactly one instance of Database to represent 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.

Additional information about databases is in the user guide.

All deprecated public constants now have equivalents in ObjectStore.

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.

check(PrintStream): Check the references of all objects 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.
createRoot(String, Object): Creates a root with the specified name in this database.
destroy(): Closes and destroys the database.
destroyRoot(String): Destroys the root with the specified name.
getOpenType(): Retrieves the database open type.
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.
getSizeInBytes(): Retrieves the number of bytes of storage occupied by the database.
isOpen(): Determines whether or not a database is open.
of(Object): Returns the database that contains the object.
open(int): Opens a database with the specified open type.
open(String, int): Opens the database with the specified name and open type.
setRoot(String, Object): Sets the object associated with the specified root name.
showDB(String, PrintStream, boolean, boolean): Show the contents of the database.

ownerRead

  public final static int ownerRead

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

ownerWrite

  public final static int ownerWrite

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

ownerExecute

  public final static int ownerExecute

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

groupRead

  public final static int groupRead

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

groupWrite

  public final static int groupWrite

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

groupExecute

  public final static int groupExecute

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

otherRead

  public final static int otherRead

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

otherWrite

  public final static int otherWrite

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

otherExecute

  public final static int otherExecute

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

allRead

  public final static int allRead

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

allWrite

  public final static int allWrite

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

allExecute

  public final static int allExecute

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

openUpdate

  public final static int openUpdate

Note: openUpdate is deprecated.

See Also:: OPEN_UPDATE

openReadOnly

  public final static int openReadOnly

Note: openReadOnly is deprecated.

See Also:: OPEN_READONLY

openMVCC

  public final static int openMVCC

Note: openMVCC is deprecated.

See Also:: OPEN_MVCC

create

  public static Database create(String name,
                                int fileMode)

Creates and opens a database with the specified name. When PSE or 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. 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.
Throws: DatabaseAlreadyExistsException: If a database with the specified name already exists.
Throws: DatabaseException: If other miscelleneous errors occur during database creation, such as an invalid path name or unknown host. Thrown by PSE or PSE Pro if a database is open.
Throws: IllegalArgumentException: If the database name is null, or if the fileMode argument is invalid, including if it does not specify owner write permission.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread.
Throws: TransactionInProgressException: If there is a transaction in progress.
See Also:: open

open

  public static Database open(String name,
                              int openType)

Opens the database with the specified name and open type. If the database is already open with the specified open type, 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 Java session. The instance of Database is not created when you create the database file in the file system.

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.

openType - One of the constants:

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.OPEN_UPDATE or ObjectStore.OPEN_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 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 openType.

Throws: AccessViolationException

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

Throws: DatabaseNotFoundException

If a database with that name does not exist.

Throws: IllegalArgumentException

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

Throws: IncompatibleOpenTypeException

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

Throws: ObjectStoreException

If PSE/PSE Pro is not initialized for the current thread.

Throws: DatabaseLockedException

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

open

  public abstract Database open(int openType)

Opens a database with the specified open type. Normally, an application calls this method on a closed database. However, if the database is already open with the specified open type, 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.

Parameters:

openType - One of the constants:

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 and if the database was opened with the same openType.

Throws: AccessViolationException

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

Throws: DatabaseNotFoundException

If a database with that name does not exist.

Throws: IllegalArgumentException

If the openType parameter is invalid.

Throws: IncompatibleOpenTypeException

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

Throws: ObjectStoreException

If PSE/PSE Pro is not initialized for the current thread or if the database is not associated with the current thread.

Throws: DatabaseLockedException

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

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 PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

close

  public abstract void close()

Closes the database. After a call to this method, operations that require the database to be open throw DatabaseNotOpenException.

Throws: DatabaseNotOpenException: If the database is not open.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.
Throws: 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. If the retainAsTransient argument is true, any retained objects are made transient. This form of close() is only meaningful if the last commit on the database specified Transaction.RETAIN_UPDATE.

Throws: DatabaseNotOpenException: If the database is not open.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.
Throws: ObjectStoreException: If retainAsTransient is true and the most recent Transaction.commit() call did not specify Transaction.RETAIN_UPDATE.
Throws: TransactionInProgressException: If a transaction is in progress.

destroy

  public abstract void destroy()

Closes and destroys the database.

Throws: DatabaseNotOpenException: If the database is not open.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.
Throws: TransactionInProgressException: If a transaction is in progress.
Throws: 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 int 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.
Throws: DatabaseNotOpenException: If the database is not open.
Throws: NoTransactionInProgressException: If no transaction is in progress.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

getOpenType

  public abstract int getOpenType()

Retrieves the database open type. This indicates whether or not you can modify the database content.

Returns:: If the database is open for update or update non-blocking, this method returns the ObjectStore.OPEN_UPDATE constant. If the database is open for read-only or read-only non-blocking, this method returns the ObjectStore.OPEN_READONLY constant.
Throws: DatabaseNotOpenException: If the database is not open.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

getRoot

  public abstract Object getRoot(String name)

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

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.

The user guide provides additional information about obtaining roots.

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: 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 PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

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, then PSE/PSE Pro migrates it into the database when the transaction is committed and then associates it with the root.

The user guide provides additional information about setting roots.

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

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

Throws: ObjectNotPersistenceCapableException

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

Throws: ObjectStoreException

If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

Throws: UpdateReadOnlyException

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

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 either be allocated in this database or be an exported object. (For PSE/PSE Pro, the object must be in the same database.) If the object is not persistent, PSE/PSE Pro migrates it into the database when the transaction is committed and then associates it with the root.

The user guide provides additional information about creating roots.

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

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

Throws: ObjectNotPersistenceCapableException

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

Throws: ObjectStoreException

If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

Throws: UpdateReadOnlyException

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

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

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 PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.

Throws: 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.
Throws: DatabaseNotOpenException: If the database is not open.
Throws: NoTransactionInProgressException: If a transaction is not in progress.

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.
Throws: NoTransactionInProgressException: If a transaction is not in progress.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the database object is not associated with this thread.
Throws: SegmentNotFoundException: If the segment is not found.

  public static Database of(Object object)

Returns the database that contains the object.

Parameters:: object - The object whose database should be determined. Must be persistent.
Returns:: The 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: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread.
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.

check

  public abstract boolean check(PrintStream out)

Check the references of all objects in the database.

Parameters:: out - The output stream on which to display errors.
Returns:: true if there were no problems found, false otherwise.

showDB

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

Show the contents of the database.

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 beshown. Setting this option forces showObj to be true.