Database


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 
247
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags