* A database application generally begins processing by accessing one or more
* critical objects and proceeding from there. These objects are root objects,
* because they lead to interconnected webs of other objects.
* The ability to name an object (using method bind
) and
* retrieve it later by that name (using method lookup
facilitates
* this start-up capability. A name is not explicitly defined as an attribute of
* an object. Naming an object also makes it persistent.
*
* There is a single flat name scope per database; thus all names in a particular
* database are unique.
* @author David Jordan (as Java Editor of the Object Data Management Group)
* @version ODMG 3.0
*/
public interface Database {
/**
* The database is not open.
*/
public static final int NOT_OPEN = 0;
/**
* The database is opened for read-only access.
*/
public static final int OPEN_READ_ONLY = 1;
/**
* The database is opened for reading and writing.
*/
public static final int OPEN_READ_WRITE = 2;
/**
* The database is open for exclusive access.
*/
public static final int OPEN_EXCLUSIVE = 3;
/**
* Open the named database with the specified access mode.
* Attempts to open a database when it has already been opened will result in
* the throwing of the exception DatabaseOpenException
.
* A DatabaseNotFoundException
is thrown if the database does not exist.
* Some implementations may throw additional exceptions that are also derived from
* ODMGException
.
* @param name The name of the database.
* @param accessMode The access mode, which should be one of the static fields:
* OPEN_READ_ONLY
, OPEN_READ_WRITE
,
* or OPEN_EXCLUSIVE
.
* @exception ODMGException The database could not be opened.
*/
public void open(String name, int accessMode) throws ODMGException;
/**
* Close the database.
* After you have closed a database, further attempts to access objects in the
* database will cause the exception DatabaseClosedException
to be thrown.
* Some implementations may throw additional exceptions that are also derived
* from ODMGException
.
* @exception ODMGException Unable to close the database.
*/
public void close() throws ODMGException;
/**
* Associate a name with an object and make it persistent,
*
not yet available in RasDaMan.
* An object instance may be bound to more than one name.
* Binding a previously transient object to a name makes that object persistent.
* @param object The object to be named.
* @param name The name to be given to the object.
* @exception org.odmg.ObjectNameNotUniqueException
* If an attempt is made to bind a name to an object and that name is already bound
* to an object.
*/
public void bind(Object object, String name) throws ObjectNameNotUniqueException;
/**
* Lookup an object via its name,
*
not yet available in RasDaMan.
* @param name The name of an object.
* @return The object with that name.
* @exception ObjectNameNotFoundException There is no object with the specified name.
* @see ObjectNameNotFoundException
*/
public Object lookup(String name) throws ObjectNameNotFoundException;
/**
* Disassociate a name with an object,
*
not yet available in RasDaMan.
* @param name The name of an object.
* @exception ObjectNameNotFoundException No object exists in the database with that name.
*/
public void unbind(String name) throws ObjectNameNotFoundException;
/**
* Make a transient object durable in the database,
*
not yet available in RasDaMan.
* It must be executed in the context of an open transaction.
* If the transaction in which this method is executed commits,
* then the object is made durable.
* If the transaction aborts,
* then the makePersistent operation is considered not to have been executed,
* and the target object is again transient.
* ClassNotPersistenceCapableException is thrown if the implementation cannot make
* the object persistent because of the type of the object.
* @param object The object to make persistent.
*/
public void makePersistent(Object object);
/**
* Deletes an object from the database,
*
not yet available in RasDaMan.
* It must be executed in the context of an open transaction.
* If the object is not persistent, then ObjectNotPersistent is thrown.
* If the transaction in which this method is executed commits,
* then the object is removed from the database.
* If the transaction aborts,
* then the deletePersistent operation is considered not to have been executed,
* and the target object is again in the database.
* @param object The object to delete.
*/
public void deletePersistent(Object object);
}