001: package org.odmg;
002:
003: /**
004: * The interface for interacting with an ODMG database.
005: * Databases must be opened before starting any transactions that use the database
006: * and closed after ending these transactions.
007: * <p>
008: * A database application generally begins processing by accessing one or more
009: * critical objects and proceeding from there. These objects are root objects,
010: * because they lead to interconnected webs of other objects.
011: * The ability to name an object (using method <code>bind</code>) and
012: * retrieve it later by that name (using method <code>lookup</code> facilitates
013: * this start-up capability. A name is not explicitly defined as an attribute of
014: * an object. Naming an object also makes it persistent.
015: * <p>
016: * There is a single flat name scope per database; thus all names in a particular
017: * database are unique.
018: * @author David Jordan (as Java Editor of the Object Data Management Group)
019: * @version ODMG 3.0
020: */
021:
022: public interface Database {
023: /**
024: * The database is not open.
025: */
026: public static final int NOT_OPEN = 0;
027:
028: /**
029: * The database is opened for read-only access.
030: */
031: public static final int OPEN_READ_ONLY = 1;
032:
033: /**
034: * The database is opened for reading and writing.
035: */
036: public static final int OPEN_READ_WRITE = 2;
037:
038: /**
039: * The database is open for exclusive access.
040: */
041: public static final int OPEN_EXCLUSIVE = 3;
042:
043: /**
044: * Open the named database with the specified access mode.
045: * Attempts to open a database when it has already been opened will result in
046: * the throwing of the exception <code>DatabaseOpenException</code>.
047: * A <code>DatabaseNotFoundException</code> is thrown if the database does not exist.
048: * Some implementations may throw additional exceptions that are also derived from
049: * <code>ODMGException</code>.
050: * @param name The name of the database.
051: * @param accessMode The access mode, which should be one of the static fields:
052: * <code>OPEN_READ_ONLY</code>, <code>OPEN_READ_WRITE</code>,
053: * or <code>OPEN_EXCLUSIVE</code>.
054: * @exception ODMGException The database could not be opened.
055: */
056: public void open(String name, int accessMode) throws ODMGException;
057:
058: /**
059: * Close the database.
060: * After you have closed a database, further attempts to access objects in the
061: * database will cause the exception <code>DatabaseClosedException</code> to be thrown.
062: * Some implementations may throw additional exceptions that are also derived
063: * from <code>ODMGException</code>.
064: * @exception ODMGException Unable to close the database.
065: */
066: public void close() throws ODMGException;
067:
068: /**
069: * Associate a name with an object and make it persistent.
070: * An object instance may be bound to more than one name.
071: * Binding a previously transient object to a name makes that object persistent.
072: * @param object The object to be named.
073: * @param name The name to be given to the object.
074: * @exception org.odmg.ObjectNameNotUniqueException
075: * If an attempt is made to bind a name to an object and that name is already bound
076: * to an object.
077: */
078: public void bind(Object object, String name)
079: throws ObjectNameNotUniqueException;
080:
081: /**
082: * Lookup an object via its name.
083: * @param name The name of an object.
084: * @return The object with that name.
085: * @exception ObjectNameNotFoundException There is no object with the specified name.
086: * @see ObjectNameNotFoundException
087: */
088: public Object lookup(String name)
089: throws ObjectNameNotFoundException;
090:
091: /**
092: * Disassociate a name with an object
093: * @param name The name of an object.
094: * @exception ObjectNameNotFoundException No object exists in the database with that name.
095: */
096: public void unbind(String name) throws ObjectNameNotFoundException;
097:
098: /**
099: * Make a transient object durable in the database.
100: * It must be executed in the context of an open transaction.
101: * If the transaction in which this method is executed commits,
102: * then the object is made durable.
103: * If the transaction aborts,
104: * then the makePersistent operation is considered not to have been executed,
105: * and the target object is again transient.
106: * ClassNotPersistenceCapableException is thrown if the implementation cannot make
107: * the object persistent because of the type of the object.
108: * @param object The object to make persistent.
109: */
110: public void makePersistent(Object object);
111:
112: /**
113: * Deletes an object from the database.
114: * It must be executed in the context of an open transaction.
115: * If the object is not persistent, then ObjectNotPersistent is thrown.
116: * If the transaction in which this method is executed commits,
117: * then the object is removed from the database.
118: * If the transaction aborts,
119: * then the deletePersistent operation is considered not to have been executed,
120: * and the target object is again in the database.
121: * @param object The object to delete.
122: */
123: public void deletePersistent(Object object);
124:
125: /**
126: Create a new persistent instance of the given class.
127: <p>
128: THIS METHOD IS NOT IN THE ODMG 3.0 STANDARD!
129: <p>
130: It must be executed in the context of an open transaction.
131: If the transaction in which this method is executed commits,
132: then the object is made durable.
133: ClassNotPersistenceCapableException is thrown if the implementation cannot make
134: the object persistent because of the type of the object.
135: */
136: // public Object createPersistent (Class cl);
137: }
|