com.objy.db.app
Class Database

java.lang.Object
  |
  +--com.objy.db.app.Database

public final class Database

extends Object

Represents an ODMG database.

API Summary

The ODMG standard does not include the concept of a federation of databases; as a consequence, an ODMG database corresponds to an Objectivity/DB federated database in which all persistent objects are stored in the default database.

Methods of Database allow you to open and close a database and to store and retrieve persistent objects by their root names.

Note: Your application should work with an instance of this class only if it requires ODMG compliance; otherwise, it should work with a connection object instead. For additional information about ODMG applications, see ODMG Application Objects.

API Summary

Constant Types

Open modes (ODMG) Specify how a connection to the federated database is opened.

notOpen openReadOnly openReadWrite

Functionality

Opening and Closing Databases	open(String, int) (ODMG) isOpen() close() (ODMG)
Getting Information	current() getConnection()
Testing	isOpen()
Working With Named Roots	bind(Object, String) (ODMG) unbind(String) (ODMG) lookup(String) (ODMG)
Static Utilities	open(String, int) (ODMG) current()

Field Summary

static int	notOpen (ODMG) Open mode: The database is not open; transactions may not be created.
static int	openExclusive (ODMG) Not supported.
static int	openReadOnly (ODMG) Open mode: The database is open for read-only access.
static int	openReadWrite (ODMG) Open mode: The database is open for read/write access.

Constructor Summary

Database(PConnection persistor)
Reserved for internal use; to create an ODMG database object, call the static method Database.open.

Method Summary

void	bind(Object object, String name) (ODMG) Names the specified object with the specified root name in the connected federated database.
void	close() (ODMG) Closes the connection associated with this ODMG database object.
static Database	current() Gets this application's ODMG database object.
Connection	getConnection() Gets the connection associated with this ODMG database object.
boolean	isOpen() Tests whether the connection between the associated connection object and the federated database is open.
Object	lookup(String name) (ODMG) Retrieves the object with the specified root name in the connected federated database.
static Database	open(String bootFilePath, int mode) (ODMG) Opens a connection to the specified federated database and returns the ODMG database object associated with the connection.
void	unbind(String name) (ODMG) Removes the specified root name from the connected federated database.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

notOpen

public static final int notOpen

(ODMG) Open mode: The database is not open; transactions may not be created.

openReadOnly

public static final int openReadOnly

(ODMG) Open mode: The database is open for read-only access.

openReadWrite

public static final int openReadWrite

(ODMG) Open mode: The database is open for read/write access.

openExclusive

public static final int openExclusive

(ODMG) Not supported. Do not use this constant.

Constructor Detail

Database

public Database(PConnection persistor)

Reserved for internal use; to create an ODMG database object, call the static method Database.open.

You should not use this constructor.

Method Detail

open

public static Database open(String bootFilePath,
                            int mode)
                     throws DatabaseOpenException,
                            DatabaseNotFoundException

(ODMG) Opens a connection to the specified federated database and returns the ODMG database object associated with the connection.

You must open a connection before creating any transactions (or sessions) that interact with the federated database.

Note: There can be only one instance of the Database class in an application.

This method creates the connection object through which your application interacts with the federated database. You can obtain the connection object by calling the getConnection method of the returned ODMG database object.

Parameters:

bootFilePath - The pathname of the boot file of the federated database to which a connection is being opened. If this parameter is an empty string ("") or null, the value of the OO_FD_BOOT environment variable is used as the boot file path.

mode - The open mode for the new ODMG database object; one of the following constants defined in this class (and also in the oo interface):

openReadOnly

Open the database for read-only access.

openReadWrite

Open the database for read/write access.

The open mode limits the open mode of each session object created after the database is opened. As a consequence, it also limits the lock modes of any storage objects or persistent objects that belong to those sessions. A database open mode of openReadWrite permits session open modes of openReadWrite or openReadOnly; a database open mode of openReadOnly permits the session open mode openReadOnly.

Returns:

The newly created ODMG database object.

Throws:

DatabaseOpenException - If a connection to the federated database is already open.

DatabaseNotFoundException - If the federated database doesn't exist.

See Also:

close(), isOpen()

isOpen

public boolean isOpen()

Tests whether the connection between the associated connection object and the federated database is open.

Returns:

True if the connection is open; otherwise false.

See Also:

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

current

public static Database current()

Gets this application's ODMG database object.

Returns:

The current ODMG database object, or null if there is no such object (because the static method Database.open has not been called).

getConnection

public Connection getConnection()

Gets the connection associated with this ODMG database object.

Returns:

The connection object associated with this ODMG database object.

close

public void close()
           throws DatabaseClosedException

(ODMG) Closes the connection associated with this ODMG database object.

This method terminates all sessions. It should be called before exiting from an application.

Throws:

DatabaseClosedException - If this connection object is already closed.

TransactionInProgressException - If any transaction is open without terminating any sessions and have the database open.

See Also:

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

bind

public void bind(Object object,
                 String name)
          throws ObjectNameNotUniqueException

(ODMG) Names the specified object with the specified root name in the connected federated database.

Giving an object a root name makes the object persistent. The named object is made persistent immediately; all transient objects reachable from the named object are made persistent on transaction commit.

This method can be called only during a transaction.

Parameters:

object - The object being named.

name - The root name for the object. This name can be any valid Java string and must be unique within the root dictionary of the federated database.

Throws:

ObjectNameNotUniqueException - If the name already exists in the root dictionary.

See Also:

unbind(java.lang.String), ooFDObj.getDefaultDB()

unbind

public void unbind(String name)
            throws ObjectNameNotFoundException

(ODMG) Removes the specified root name from the connected federated database.

This method can be called only during a transaction.

Parameters:

name - The root name to be removed.

Throws:

ObjectNameNotFoundException - If the name doesn't exist in the root dictionary.

lookup

public Object lookup(String name)
              throws ObjectNameNotFoundException

(ODMG) Retrieves the object with the specified root name in the connected federated database.

This method can be called only during a transaction.

Parameters:

name - The root name of the object.

Returns:

The object with the specified root name. If that object is the root of a graph of objects, only the root object is retrieved.

Throws:

ObjectNameNotFoundException - If the name doesn't exist in the root dictionary.