Source code: org/odmg/Database.java
1 package org.odmg;
2
3 /**
4 * The interface for interacting with an ODMG database.
5 * Databases must be opened before starting any transactions that use the database
6 * and closed after ending these transactions.
7 * <p>
8 * A database application generally begins processing by accessing one or more
9 * critical objects and proceeding from there. These objects are root objects,
10 * because they lead to interconnected webs of other objects.
11 * The ability to name an object (using method <code>bind</code>) and
12 * retrieve it later by that name (using method <code>lookup</code> facilitates
13 * this start-up capability. A name is not explicitly defined as an attribute of
14 * an object. Naming an object also makes it persistent.
15 * <p>
16 * There is a single flat name scope per database; thus all names in a particular
17 * database are unique.
18 * @author David Jordan (as Java Editor of the Object Data Management Group)
19 * @version ODMG 3.0
20 */
21
22 public interface Database
23 {
24 /**
25 * The database is not open.
26 */
27 public static final int NOT_OPEN = 0;
28
29 /**
30 * The database is opened for read-only access.
31 */
32 public static final int OPEN_READ_ONLY = 1;
33
34 /**
35 * The database is opened for reading and writing.
36 */
37 public static final int OPEN_READ_WRITE = 2;
38
39 /**
40 * The database is open for exclusive access.
41 */
42 public static final int OPEN_EXCLUSIVE = 3;
43
44 /**
45 * Open the named database with the specified access mode.
46 * Attempts to open a database when it has already been opened will result in
47 * the throwing of the exception <code>DatabaseOpenException</code>.
48 * A <code>DatabaseNotFoundException</code> is thrown if the database does not exist.
49 * Some implementations may throw additional exceptions that are also derived from
50 * <code>ODMGException</code>.
51 * @param name The name of the database.
52 * @param accessMode The access mode, which should be one of the static fields:
53 * <code>OPEN_READ_ONLY</code>, <code>OPEN_READ_WRITE</code>,
54 * or <code>OPEN_EXCLUSIVE</code>.
55 * @exception ODMGException The database could not be opened.
56 */
57 public void open(String name, int accessMode) throws ODMGException;
58
59 /**
60 * Close the database.
61 * After you have closed a database, further attempts to access objects in the
62 * database will cause the exception <code>DatabaseClosedException</code> to be thrown.
63 * Some implementations may throw additional exceptions that are also derived
64 * from <code>ODMGException</code>.
65 * @exception ODMGException Unable to close the database.
66 */
67 public void close() throws ODMGException;
68
69 /**
70 * Associate a name with an object and make it persistent.
71 * An object instance may be bound to more than one name.
72 * Binding a previously transient object to a name makes that object persistent.
73 * @param object The object to be named.
74 * @param name The name to be given to the object.
75 * @exception org.odmg.ObjectNameNotUniqueException
76 * If an attempt is made to bind a name to an object and that name is already bound
77 * to an object.
78 */
79 public void bind(Object object, String name) throws ObjectNameNotUniqueException;
80
81 /**
82 * Lookup an object via its name.
83 * @param name The name of an object.
84 * @return The object with that name.
85 * @exception ObjectNameNotFoundException There is no object with the specified name.
86 * @see ObjectNameNotFoundException
87 */
88 public Object lookup(String name) throws ObjectNameNotFoundException;
89
90 /**
91 * Disassociate a name with an object
92 * @param name The name of an object.
93 * @exception ObjectNameNotFoundException No object exists in the database with that name.
94 */
95 public void unbind(String name) throws ObjectNameNotFoundException;
96
97 /**
98 * Make a transient object durable in the database.
99 * It must be executed in the context of an open transaction.
100 * If the transaction in which this method is executed commits,
101 * then the object is made durable.
102 * If the transaction aborts,
103 * then the makePersistent operation is considered not to have been executed,
104 * and the target object is again transient.
105 * ClassNotPersistenceCapableException is thrown if the implementation cannot make
106 * the object persistent because of the type of the object.
107 * @param object The object to make persistent.
108 */
109 public void makePersistent(Object object);
110
111 /**
112 * Deletes an object from the database.
113 * It must be executed in the context of an open transaction.
114 * If the object is not persistent, then ObjectNotPersistent is thrown.
115 * If the transaction in which this method is executed commits,
116 * then the object is removed from the database.
117 * If the transaction aborts,
118 * then the deletePersistent operation is considered not to have been executed,
119 * and the target object is again in the database.
120 * @param object The object to delete.
121 */
122 public void deletePersistent(Object object);
123 }