package org.odmg;

/**
 * The interface for interacting with an ODMG database.
 * Databases must be opened before starting any transactions that use the database
 * and closed after ending these transactions.
 * <p>
 * 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 <code>bind</code>) and
 * retrieve it later by that name (using method <code>lookup</code> facilitates
 * this start-up capability. A name is not explicitly defined as an attribute of
 * an object. Naming an object also makes it persistent.
 * <p>
 * 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 <code>DatabaseOpenException</code>.
     * A <code>DatabaseNotFoundException</code> is thrown if the database does not exist.
     * Some implementations may throw additional exceptions that are also derived from
     * <code>ODMGException</code>.
     * @param	name	The name of the database.
     * @param	accessMode	The access mode, which should be one of the static fields:
     * <code>OPEN_READ_ONLY</code>, <code>OPEN_READ_WRITE</code>,
     * or <code>OPEN_EXCLUSIVE</code>.
     * @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 <code>DatabaseClosedException</code> to be thrown.
     * Some implementations may throw additional exceptions that are also derived
     * from <code>ODMGException</code>.
     * @exception ODMGException Unable to close the database.
     */
    public void close() throws ODMGException;

    /**
     * Associate a name with an object and make it persistent.
     * 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.
     * @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
     * @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.
     * 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.
     * 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);
}