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