001: package org.odmg;
002:
003: /**
004:
005: * The interface for interacting with an ODMG database.
006:
007: * Databases must be opened before starting any transactions that use the database
008:
009: * and closed after ending these transactions.
010:
011: * <p>
012:
013: * A database application generally begins processing by accessing one or more
014:
015: * critical objects and proceeding from there. These objects are root objects,
016:
017: * because they lead to interconnected webs of other objects.
018:
019: * The ability to name an object (using method <code>bind</code>) and
020:
021: * retrieve it later by that name (using method <code>lookup</code> facilitates
022:
023: * this start-up capability. A name is not explicitly defined as an attribute of
024:
025: * an object. Naming an object also makes it persistent.
026:
027: * <p>
028:
029: * There is a single flat name scope per database; thus all names in a particular
030:
031: * database are unique.
032:
033: * @author David Jordan (as Java Editor of the Object Data Management Group)
034:
035: * @version ODMG 3.0
036:
037: */
038:
039: public interface Database
040:
041: {
042:
043: /**
044:
045: * The database is not open.
046:
047: */
048:
049: public static final int NOT_OPEN = 0;
050:
051: /**
052:
053: * The database is opened for read-only access.
054:
055: */
056:
057: public static final int OPEN_READ_ONLY = 1;
058:
059: /**
060:
061: * The database is opened for reading and writing.
062:
063: */
064:
065: public static final int OPEN_READ_WRITE = 2;
066:
067: /**
068:
069: * The database is open for exclusive access.
070:
071: */
072:
073: public static final int OPEN_EXCLUSIVE = 3;
074:
075: /**
076:
077: * Open the named database with the specified access mode.
078:
079: * Attempts to open a database when it has already been opened will result in
080:
081: * the throwing of the exception <code>DatabaseOpenException</code>.
082:
083: * A <code>DatabaseNotFoundException</code> is thrown if the database does not exist.
084:
085: * Some implementations may throw additional exceptions that are also derived from
086:
087: * <code>ODMGException</code>.
088:
089: * @param name The name of the database.
090:
091: * @param accessMode The access mode, which should be one of the static fields:
092:
093: * <code>OPEN_READ_ONLY</code>, <code>OPEN_READ_WRITE</code>,
094:
095: * or <code>OPEN_EXCLUSIVE</code>.
096:
097: * @exception ODMGException The database could not be opened.
098:
099: */
100:
101: public void open(String name, int accessMode) throws ODMGException;
102:
103: /**
104:
105: * Close the database.
106:
107: * After you have closed a database, further attempts to access objects in the
108:
109: * database will cause the exception <code>DatabaseClosedException</code> to be thrown.
110:
111: * Some implementations may throw additional exceptions that are also derived
112:
113: * from <code>ODMGException</code>.
114:
115: * @exception ODMGException Unable to close the database.
116:
117: */
118:
119: public void close() throws ODMGException;
120:
121: /**
122:
123: * Associate a name with an object and make it persistent.
124:
125: * An object instance may be bound to more than one name.
126:
127: * Binding a previously transient object to a name makes that object persistent.
128:
129: * @param object The object to be named.
130:
131: * @param name The name to be given to the object.
132:
133: * @exception org.odmg.ObjectNameNotUniqueException
134:
135: * If an attempt is made to bind a name to an object and that name is already bound
136:
137: * to an object.
138:
139: */
140:
141: public void bind(Object object, String name)
142: throws ObjectNameNotUniqueException;
143:
144: /**
145:
146: * Lookup an object via its name.
147:
148: * @param name The name of an object.
149:
150: * @return The object with that name.
151:
152: * @exception ObjectNameNotFoundException There is no object with the specified name.
153:
154: * @see ObjectNameNotFoundException
155:
156: */
157:
158: public Object lookup(String name)
159: throws ObjectNameNotFoundException;
160:
161: /**
162:
163: * Disassociate a name with an object
164:
165: * @param name The name of an object.
166:
167: * @exception ObjectNameNotFoundException No object exists in the database with that name.
168:
169: */
170:
171: public void unbind(String name) throws ObjectNameNotFoundException;
172:
173: /**
174:
175: * Make a transient object durable in the database.
176:
177: * It must be executed in the context of an open transaction.
178:
179: * If the transaction in which this method is executed commits,
180:
181: * then the object is made durable.
182:
183: * If the transaction aborts,
184:
185: * then the makePersistent operation is considered not to have been executed,
186:
187: * and the target object is again transient.
188:
189: * ClassNotPersistenceCapableException is thrown if the implementation cannot make
190:
191: * the object persistent because of the type of the object.
192:
193: * @param object The object to make persistent.
194:
195: */
196:
197: public void makePersistent(Object object);
198:
199: /**
200:
201: * Deletes an object from the database.
202:
203: * It must be executed in the context of an open transaction.
204:
205: * If the object is not persistent, then ObjectNotPersistent is thrown.
206:
207: * If the transaction in which this method is executed commits,
208:
209: * then the object is removed from the database.
210:
211: * If the transaction aborts,
212:
213: * then the deletePersistent operation is considered not to have been executed,
214:
215: * and the target object is again in the database.
216:
217: * @param object The object to delete.
218:
219: */
220:
221: public void deletePersistent(Object object);
222:
223: }
|