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   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   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   descend(Object   obj, String  [] 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   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   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   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   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   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   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   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   peekPersisted(Object   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   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   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   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   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   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   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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags