KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > db4o > ext > ExtObjectContainer


1 /* Copyright (C) 2004 - 2006 db4objects Inc. http://www.db4o.com
2
3 This file is part of the db4o open source object database.
4
5 db4o is free software; you can redistribute it and/or modify it under
6 the terms of version 2 of the GNU General Public License as published
7 by the Free Software Foundation and as clarified by db4objects' GPL
8 interpretation policy, available at
9 http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
10 Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
11 Suite 350, San Mateo, CA 94403, USA.
12
13 db4o is distributed in the hope that it will be useful, but WITHOUT ANY
14 WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 for more details.
17
18 You should have received a copy of the GNU General Public License along
19 with this program; if not, write to the Free Software Foundation, Inc.,
20 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */

21 package com.db4o.ext;
22
23 import java.io.*;
24
25 import com.db4o.*;
26 import com.db4o.config.*;
27 import com.db4o.reflect.*;
28 import com.db4o.reflect.generic.*;
29 import com.db4o.replication.*;
30 import com.db4o.types.*;
31
32 /**
33  * extended functionality for the
34  * {@link com.db4o.ObjectContainer ObjectContainer} interface.
35  * <br><br>Every db4o {@link com.db4o.ObjectContainer ObjectContainer}
36  * always is an <code>ExtObjectContainer</code> so a cast is possible.<br><br>
37  * {@link com.db4o.ObjectContainer#ext}
38  * is a convenient method to perform the cast.<br><br>
39  * The ObjectContainer functionality is split to two interfaces to allow newcomers to
40  * focus on the essential methods.
41  */

42 public interface ExtObjectContainer extends ObjectContainer {
43     
44     /**
45      * backs up a database file of an open ObjectContainer.
46      * <br><br>While the backup is running, the ObjectContainer can continue to be
47      * used. Changes that are made while the backup is in progress, will be applied to
48      * the open ObjectContainer and to the backup.<br><br>
49      * While the backup is running, the ObjectContainer should not be closed.<br><br>
50      * If a file already exists at the specified path, it will be overwritten.<br><br>
51      * @param path a fully qualified path
52      */

53     public void backup(String JavaDoc path) throws IOException;
54
55
56     /**
57      * binds an object to an internal object ID.
58      * <br><br>This method uses the ID parameter to load the
59      * correspondig stored object into memory and replaces this memory
60      * reference with the object parameter. The method may be used to replace
61      * objects or to reassociate an object with it's stored instance
62      * after closing and opening a database file. A subsequent call to
63      * {@link com.db4o.ObjectContainer#set set(Object)} is
64      * necessary to update the stored object.<br><br>
65      * <b>Requirements:</b><br>- The ID needs to be a valid internal object ID,
66      * previously retrieved with
67      * {@link #getID getID(Object)}.<br>
68      * - The object parameter needs to be of the same class as the stored object.<br><br>
69      * @see #getID(java.lang.Object)
70      * @param obj the object that is to be bound
71      * @param id the internal id the object is to be bound to
72      */

73     public void bind(Object JavaDoc obj, long id);
74     
75     
76     /**
77      * returns the {@link Db4oCollections} interface to create or modify database-aware
78      * collections for this {@link ObjectContainer}.<br><br>
79      * @return the {@link Db4oCollections} interface for this {@link ObjectContainer}.
80      */

81     public Db4oCollections collections();
82     
83
84     /**
85      * returns the Configuration context for this ObjectContainer.
86      * <br><br>
87      * Upon opening an ObjectContainer with any of the factory methods in the
88      * {@link com.db4o.Db4o Db4o class}, the global
89      * {@link com.db4o.config.Configuration Configuration} context
90      * is copied into the ObjectContainer. The
91      * {@link com.db4o.config.Configuration Configuration}
92      * can be modified individually for
93      * each ObjectContainer without any effects on the global settings.<br><br>
94      * @return {@link com.db4o.config.Configuration Configuration} the Configuration
95      * context for this ObjectContainer
96      * @see Db4o#configure
97      */

98     public Configuration configure();
99     
100     
101     /**
102      * returns a member at the specific path without activating intermediate objects.
103      * <br><br>
104      * This method allows navigating from a persistent object to it's members in a
105      * performant way without activating or instantiating intermediate objects.
106      * @param obj the parent object that is to be used as the starting point.
107      * @param path an array of field names to navigate by
108      * @return the object at the specified path or null if no object is found
109      */

110     public Object JavaDoc descend(Object JavaDoc obj, String JavaDoc[] path);
111
112
113     /**
114      * returns the stored object for an internal ID.
115      * <br><br>This is the fastest method for direct access to objects. Internal
116      * IDs can be obtained with {@link #getID getID(Object)}.
117      * Objects will not be activated by this method. They will be returned in the
118      * activation state they are currently in, in the local cache.<br><br>
119      * @param ID the internal ID
120      * @return the object associated with the passed ID or <code>null</code>,
121      * if no object is associated with this ID in this <code>ObjectContainer</code>.
122      * @see com.db4o.config.Configuration#activationDepth Why activation?
123      */

124     public Object JavaDoc getByID(long ID);
125     
126     /**
127      * returns a stored object for a {@link Db4oUUID}.
128      * <br><br>
129      * This method is intended for replication and for long-term
130      * external references to objects. To get a {@link Db4oUUID} for an
131      * object use {@link #getObjectInfo(Object)} and {@link ObjectInfo#getUUID()}.<br><br>
132      * Objects will not be activated by this method. They will be returned in the
133      * activation state they are currently in, in the local cache.<br><br>
134      * @param uuid the UUID
135      * @return the object for the UUID
136      * @see com.db4o.config.Configuration#activationDepth Why activation?
137      */

138     public Object JavaDoc getByUUID(Db4oUUID uuid);
139
140     /**
141      * returns the internal unique object ID.
142      * <br><br>db4o assigns an internal ID to every object that is stored. IDs are
143      * guaranteed to be unique within one <code>ObjectContainer</code>.
144      * An object carries the same ID in every db4o session. Internal IDs can
145      * be used to look up objects with the very fast
146      * {@link #getByID getByID} method.<br><br>
147      * Internal IDs will change when a database is defragmented. Use
148      * {@link #getObjectInfo(Object)}, {@link ObjectInfo#getUUID()} and
149      * {@link #getByUUID(Db4oUUID)} for long-term external references to
150      * objects.<br><br>
151      * @param obj any object
152      * @return the associated internal ID or <code>0</code>, if the passed
153      * object is not stored in this <code>ObjectContainer</code>.
154      */

155     public long getID(Object JavaDoc obj);
156     
157     /**
158      * returns the {@link ObjectInfo} for a stored object.
159      * <br><br>This method will return null, if the passed
160      * object is not stored to this <code>ObjectContainer</code>.<br><br>
161      * @param obj the stored object
162      * @return the {@link ObjectInfo}
163      */

164     public ObjectInfo getObjectInfo(Object JavaDoc obj);
165     
166     /**
167      * returns the Db4oDatabase identity object for this ObjectContainer.
168      * @return the Db4oDatabase identity object for this ObjectContainer.
169      */

170     public Db4oDatabase identity();
171
172     /**
173      * tests if an object is activated.
174      * <br><br><code>isActive</code> returns <code>false</code> if an object is not
175      * stored within the <code>ObjectContainer</code>.<br><br>
176      * @param obj to be tested<br><br>
177      * @return <code>true</code> if the passed object is active.
178      */

179     public boolean isActive(Object JavaDoc obj);
180
181     /**
182      * tests if an object with this ID is currently cached.
183      * <br><br>
184      * @param ID the internal ID
185      */

186     public boolean isCached(long ID);
187
188     /**
189      * tests if this <code>ObjectContainer</code> is closed.
190      * <br><br>
191      * @return <code>true</code> if this <code>ObjectContainer</code> is closed.
192      */

193     public boolean isClosed();
194
195     /**
196      * tests if an object is stored in this <code>ObjectContainer</code>.
197      * <br><br>
198      * @param obj to be tested<br><br>
199      * @return <code>true</code> if the passed object is stored.
200      */

201     public boolean isStored(Object JavaDoc obj);
202     
203     /**
204      * returns all class representations that are known to this
205      * ObjectContainer because they have been used or stored.
206      * @return all class representations that are known to this
207      * ObjectContainer because they have been used or stored.
208      */

209     public ReflectClass[] knownClasses();
210
211     /**
212      * returns the main synchronisation lock.
213      * <br><br>
214      * Synchronize over this object to ensure exclusive access to
215      * the ObjectContainer.<br><br>
216      * Handle the use of this functionality with extreme care,
217      * since deadlocks can be produced with just two lines of code.
218      * @return Object the ObjectContainer lock object
219      */

220     public Object JavaDoc lock();
221     
222     
223     /**
224      * aids migration of objects between ObjectContainers.
225      * <br><br>When objects are migrated from one ObjectContainer to another, it is
226      * desirable to preserve virtual object attributes such as the object version number
227      * or the UUID. Use this method to signal to an ObjectContainer that it should read
228      * existing version numbers and UUIDs from another ObjectContainer. This method should
229      * also be used during the Defragment. It is included in the default
230      * implementation supplied in Defragment.java/Defragment.cs.<br><br>
231      * @param objectContainer the {@link ObjectContainer} objects are to be migrated
232      * from or <code>null</code> to denote that migration is completed.
233      */

234     public void migrateFrom(ObjectContainer objectContainer);
235     
236     /**
237      * returns a transient copy of a persistent object with all members set
238      * to the values that are currently stored to the database.
239      * <br><br>
240      * The returned objects have no connection to the database.<br><br>
241      * With the <code>committed</code> parameter it is possible to specify,
242      * whether the desired object should contain the committed values or the
243      * values that were set by the running transaction with
244      * {@link ObjectContainer#set(java.lang.Object)}.
245      * <br><br>A possible usecase for this feature:<br>
246      * An application might want to check all changes applied to an object
247      * by the running transaction.<br><br>
248      * @param object the object that is to be cloned
249      * @param depth the member depth to which the object is to be instantiated
250      * @param committed whether committed or set values are to be returned
251      * @return the object
252      */

253     public Object JavaDoc peekPersisted(Object JavaDoc object,int depth, boolean committed);
254     
255
256     /**
257     * unloads all clean indices from memory and frees unused objects.
258     * <br><br>Call commit() and purge() consecutively to achieve the best
259     * result possible. This method can have a negative impact
260     * on performance since indices will have to be reread before further
261     * inserts, updates or queries can take place.
262     */

263     public void purge();
264
265     /**
266      * unloads a specific object from the db4o reference mechanism.
267      * <br><br>db4o keeps references to all newly stored and
268      * instantiated objects in memory, to be able to manage object identities.
269      * <br><br>With calls to this method it is possible to remove an object from the
270      * reference mechanism, to allow it to be garbage collected. You are not required to
271      * call this method in the .NET and JDK 1.2 versions, since objects are
272      * referred to by weak references and garbage collection happens
273      * automatically.<br><br>An object removed with <code>purge(Object)</code> is not
274      * "known" to the <code>ObjectContainer</code> afterwards, so this method may also be
275      * used to create multiple copies of objects.<br><br> <code>purge(Object)</code> has
276      * no influence on the persistence state of objects. "Purged" objects can be
277      * reretrieved with queries.<br><br>
278      * @param obj the object to be removed from the reference mechanism.
279      */

280     public void purge(Object JavaDoc obj);
281     
282     /**
283      * Return the reflector currently being used by db4objects.
284      *
285      * @return the current Reflector.
286      */

287     public GenericReflector reflector();
288     
289     /**
290      * refreshs all members on a stored object to the specified depth.
291      * <br><br>If a member object is not activated, it will be activated by this method.
292      * <br><br>The isolation used is READ COMMITTED. This method will read all objects
293      * and values that have been committed by other transactions.<br><br>
294      * @param obj the object to be refreshed.
295      * @param depth the member {@link Configuration#activationDepth(int) depth}
296      * to which refresh is to cascade.
297      */

298     public void refresh(Object JavaDoc obj, int depth);
299
300
301     /**
302      * releases a semaphore, if the calling transaction is the owner.
303      * @param name the name of the semaphore to be released.
304      */

305     public void releaseSemaphore(String JavaDoc name);
306     
307     /**
308      * prepares for replication with another {@link ObjectContainer}.
309      * <br><br>An {@link ObjectContainer} can only be involved in a replication
310      * process with one other {@link ObjectContainer} at the same time.<br><br>
311      * The returned {@link ReplicationProcess} interface provides methods to commit
312      * and to cancel the replication process.
313      * <br><br>This ObjectContainer will be "peerA" for the
314      * returned ReplicationProcess. The other ObjectContainer will be "peerB".
315      * @param peerB the {@link ObjectContainer} to replicate with.
316      * @param conflictHandler the conflict handler for this ReplicationProcess.
317      * Conflicts occur
318      * whenever {@link ReplicationProcess#replicate(Object)} is called with an
319      * object that was modified in both ObjectContainers since the last
320      * replication run between the two. Upon a conflict the
321      * {@link ReplicationConflictHandler#resolveConflict(ReplicationProcess, Object, Object)}
322      * method will be called in the conflict handler.
323      * @return the {@link ReplicationProcess} interface for this replication process.
324      */

325     public ReplicationProcess replicationBegin(ObjectContainer peerB, ReplicationConflictHandler conflictHandler);
326     
327     
328     /**
329      * deep update interface to store or update objects.
330      * <br><br>In addition to the normal storage interface,
331      * {@link com.db4o.ObjectContainer#set ObjectContainer#set(Object)},
332      * this method allows a manual specification of the depth, the passed object is to be updated.<br><br>
333      * @param obj the object to be stored or updated.
334      * @param depth the depth to which the object is to be updated
335      * @see com.db4o.ObjectContainer#set
336      */

337     public void set (Object JavaDoc obj, int depth);
338     
339
340     /**
341      * attempts to set a semaphore.
342      * <br><br>
343      * Semaphores are transient multi-purpose named flags for
344      * {@link ObjectContainer ObjectContainers}.
345      * <br><br>
346      * A transaction that successfully sets a semaphore becomes
347      * the owner of the semaphore. Semaphores can only be owned
348      * by a single transaction at one point in time.<br><br>
349      * This method returns true, if the transaction already owned
350      * the semaphore before the method call or if it successfully
351      * acquires ownership of the semaphore.<br><br>
352      * The waitForAvailability parameter allows to specify a time
353      * in milliseconds to wait for other transactions to release
354      * the semaphore, in case the semaphore is already owned by
355      * another transaction.<br><br>
356      * Semaphores are released by the first occurence of one of the
357      * following:<br>
358      * - the transaction releases the semaphore with
359      * {@link #releaseSemaphore(java.lang.String)}<br> - the transaction is closed with {@link
360      * ObjectContainer#close()}<br> - C/S only: the corresponding {@link ObjectServer} is
361      * closed.<br> - C/S only: the client {@link ObjectContainer} looses the connection and is timed
362      * out.<br><br> Semaphores are set immediately. They are independant of calling {@link
363      * ObjectContainer#commit()} or {@link ObjectContainer#rollback()}.<br><br> <b>Possible usecases
364      * for semaphores:</b><br> - prevent other clients from inserting a singleton at the same time.
365      * A suggested name for the semaphore: "SINGLETON_" + Object#getClass().getName().<br> - lock
366      * objects. A suggested name: "LOCK_" + {@link #getID(java.lang.Object) getID(Object)}<br> -
367      * generate a unique client ID. A suggested name: "CLIENT_" +
368      * System.currentTimeMillis().<br><br>
369      *
370      * @param name the name of the semaphore to be set
371      * @param waitForAvailability the time in milliseconds to wait for other
372      * transactions to release the semaphore. The parameter may be zero, if
373      * the method is to return immediately.
374      * @return boolean flag
375      * <br><code>true</code>, if the semaphore could be set or if the
376      * calling transaction already owned the semaphore.
377      * <br><code>false</code>, if the semaphore is owned by another
378      * transaction.
379      */

380     public boolean setSemaphore(String JavaDoc name, int waitForAvailability);
381     
382     /**
383     * returns a {@link StoredClass} meta information object.
384     * <br><br>
385     * There are three options how to use this method.<br>
386     * Any of the following parameters are possible:<br>
387     * - a fully qualified classname.<br>
388     * - a Class object.<br>
389     * - any object to be used as a template.<br><br>
390     * @param clazz class name, Class object, or example object.<br><br>
391     * @return an instance of an {@link StoredClass} meta information object.
392     */

393     public StoredClass storedClass(Object JavaDoc clazz);
394
395     /**
396      * returns an array of all {@link StoredClass} meta information objects.
397      */

398     public StoredClass[] storedClasses();
399     
400     /**
401      * returns the {@link SystemInfo} for this ObjectContainer.
402      * <br><br>The {@link SystemInfo} supplies methods that provide
403      * information about system state and system settings of this
404      * ObjectContainer.
405      * @return the {@link SystemInfo} for this ObjectContainer.
406      */

407     public SystemInfo systemInfo();
408     
409     /**
410      * returns the current transaction serial number.
411      * <br><br>This serial number can be used to query for modified objects
412      * and for replication purposes.
413      * @return the current transaction serial number.
414      */

415     public long version();
416     
417 }
Popular Tags