1 package org.odmg;
2
3
4
5 /**
6
7 * The interface for interacting with an ODMG database.
8
9 * Databases must be opened before starting any transactions that use the database
10
11 * and closed after ending these transactions.
12
13 * <p>
14
15 * A database application generally begins processing by accessing one or more
16
17 * critical objects and proceeding from there. These objects are root objects,
18
19 * because they lead to interconnected webs of other objects.
20
21 * The ability to name an object (using method <code>bind</code>) and
22
23 * retrieve it later by that name (using method <code>lookup</code> facilitates
24
25 * this start-up capability. A name is not explicitly defined as an attribute of
26
27 * an object. Naming an object also makes it persistent.
28
29 * <p>
30
31 * There is a single flat name scope per database; thus all names in a particular
32
33 * database are unique.
34
35 * @author David Jordan (as Java Editor of the Object Data Management Group)
36
37 * @version ODMG 3.0
38
39 */
40
41
42
43 public interface Database
44
45 {
46
47 /**
48
49 * The database is not open.
50
51 */
52
53 public static final int NOT_OPEN = 0;
54
55
56
57 /**
58
59 * The database is opened for read-only access.
60
61 */
62
63 public static final int OPEN_READ_ONLY = 1;
64
65
66
67 /**
68
69 * The database is opened for reading and writing.
70
71 */
72
73 public static final int OPEN_READ_WRITE = 2;
74
75
76
77 /**
78
79 * The database is open for exclusive access.
80
81 */
82
83 public static final int OPEN_EXCLUSIVE = 3;
84
85
86
87 /**
88
89 * Open the named database with the specified access mode.
90
91 * Attempts to open a database when it has already been opened will result in
92
93 * the throwing of the exception <code>DatabaseOpenException</code>.
94
95 * A <code>DatabaseNotFoundException</code> is thrown if the database does not exist.
96
97 * Some implementations may throw additional exceptions that are also derived from
98
99 * <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