001: /* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com
002:
003: This file is part of the db4o open source object database.
004:
005: db4o is free software; you can redistribute it and/or modify it under
006: the terms of version 2 of the GNU General Public License as published
007: by the Free Software Foundation and as clarified by db4objects' GPL
008: interpretation policy, available at
009: http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
010: Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
011: Suite 350, San Mateo, CA 94403, USA.
012:
013: db4o is distributed in the hope that it will be useful, but WITHOUT ANY
014: WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: for more details.
017:
018: You should have received a copy of the GNU General Public License along
019: with this program; if not, write to the Free Software Foundation, Inc.,
020: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
021: package com.db4o.ext;
022:
023: import com.db4o.*;
024: import com.db4o.config.*;
025: import com.db4o.foundation.*;
026: import com.db4o.reflect.*;
027: import com.db4o.reflect.generic.*;
028: import com.db4o.replication.*;
029: import com.db4o.types.*;
030:
031: /**
032: * extended functionality for the
033: * {@link com.db4o.ObjectContainer ObjectContainer} interface.
034: * <br><br>Every db4o {@link com.db4o.ObjectContainer ObjectContainer}
035: * always is an <code>ExtObjectContainer</code> so a cast is possible.<br><br>
036: * {@link com.db4o.ObjectContainer#ext ObjectContainer.ext()}
037: * is a convenient method to perform the cast.<br><br>
038: * The ObjectContainer functionality is split to two interfaces to allow newcomers to
039: * focus on the essential methods.
040: */
041: public interface ExtObjectContainer extends ObjectContainer {
042:
043: /**
044: * backs up a database file of an open ObjectContainer.
045: * <br><br>While the backup is running, the ObjectContainer can continue to be
046: * used. Changes that are made while the backup is in progress, will be applied to
047: * the open ObjectContainer and to the backup.<br><br>
048: * While the backup is running, the ObjectContainer should not be closed.<br><br>
049: * If a file already exists at the specified path, it will be overwritten.<br><br>
050: * @param path a fully qualified path
051: * @throws DatabaseClosedException db4o database file was closed or failed to open.
052: * @throws NotSupportedException is thrown when the operation is not supported in current
053: * configuration/environment
054: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
055: */
056: public void backup(String path) throws Db4oIOException,
057: DatabaseClosedException, NotSupportedException;
058:
059: /**
060: * binds an object to an internal object ID.
061: * <br><br>This method uses the ID parameter to load the
062: * correspondig stored object into memory and replaces this memory
063: * reference with the object parameter. The method may be used to replace
064: * objects or to reassociate an object with it's stored instance
065: * after closing and opening a database file. A subsequent call to
066: * {@link com.db4o.ObjectContainer#set set(Object)} is
067: * necessary to update the stored object.<br><br>
068: * <b>Requirements:</b><br>- The ID needs to be a valid internal object ID,
069: * previously retrieved with
070: * {@link #getID getID(Object)}.<br>
071: * - The object parameter needs to be of the same class as the stored object.<br><br>
072: * @see #getID(java.lang.Object)
073: * @param obj the object that is to be bound
074: * @param id the internal id the object is to be bound to
075: * @throws DatabaseClosedException db4o database file was closed or failed to open.
076: * @throws InvalidIDException when the provided id is outside the scope of the
077: * database IDs.
078: */
079: public void bind(Object obj, long id) throws InvalidIDException,
080: DatabaseClosedException;
081:
082: /**
083: * returns the {@link Db4oCollections} interface to create or modify database-aware
084: * collections for this {@link ObjectContainer}.<br><br>
085: * @return the {@link Db4oCollections} interface for this {@link ObjectContainer}.
086: */
087: public Db4oCollections collections();
088:
089: /**
090: * returns the Configuration context for this ObjectContainer.
091: * <br><br>
092: * Upon opening an ObjectContainer with any of the factory methods in the
093: * {@link com.db4o.Db4o Db4o class}, the global
094: * {@link com.db4o.config.Configuration Configuration} context
095: * is copied into the ObjectContainer. The
096: * {@link com.db4o.config.Configuration Configuration}
097: * can be modified individually for
098: * each ObjectContainer without any effects on the global settings.<br><br>
099: * @return {@link com.db4o.config.Configuration Configuration} the Configuration
100: * context for this ObjectContainer
101: * @see Db4o#configure
102: */
103: public Configuration configure();
104:
105: /**
106: * returns a member at the specific path without activating intermediate objects.
107: * <br><br>
108: * This method allows navigating from a persistent object to it's members in a
109: * performant way without activating or instantiating intermediate objects.
110: * @param obj the parent object that is to be used as the starting point.
111: * @param path an array of field names to navigate by
112: * @return the object at the specified path or null if no object is found
113: */
114: public Object descend(Object obj, String[] path);
115:
116: /**
117: * returns the stored object for an internal ID.
118: * <br><br>This is the fastest method for direct access to objects. Internal
119: * IDs can be obtained with {@link #getID getID(Object)}.
120: * Objects will not be activated by this method. They will be returned in the
121: * activation state they are currently in, in the local cache.<br><br>
122: * @param ID the internal ID
123: * @return the object associated with the passed ID or <code>null</code>,
124: * if no object is associated with this ID in this <code>ObjectContainer</code>.
125: * @see com.db4o.config.Configuration#activationDepth Why activation?
126: * @throws DatabaseClosedException db4o database file was closed or failed to open.
127: * @throws InvalidIDException when the provided id is outside the scope of the
128: */
129: public <T> T getByID(long ID) throws DatabaseClosedException,
130: InvalidIDException;
131:
132: /**
133: * returns a stored object for a {@link Db4oUUID}.
134: * <br><br>
135: * This method is intended for replication and for long-term
136: * external references to objects. To get a {@link Db4oUUID} for an
137: * object use {@link #getObjectInfo(Object)} and {@link ObjectInfo#getUUID()}.<br><br>
138: * Objects will not be activated by this method. They will be returned in the
139: * activation state they are currently in, in the local cache.<br><br>
140: * @param uuid the UUID
141: * @return the object for the UUID
142: * @see com.db4o.config.Configuration#activationDepth Why activation?
143: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
144: * @throws DatabaseClosedException db4o database file was closed or failed to open.
145: */
146: public <T> T getByUUID(Db4oUUID uuid)
147: throws DatabaseClosedException, Db4oIOException;
148:
149: /**
150: * returns the internal unique object ID.
151: * <br><br>db4o assigns an internal ID to every object that is stored. IDs are
152: * guaranteed to be unique within one <code>ObjectContainer</code>.
153: * An object carries the same ID in every db4o session. Internal IDs can
154: * be used to look up objects with the very fast
155: * {@link #getByID getByID} method.<br><br>
156: * Internal IDs will change when a database is defragmented. Use
157: * {@link #getObjectInfo(Object)}, {@link ObjectInfo#getUUID()} and
158: * {@link #getByUUID(Db4oUUID)} for long-term external references to
159: * objects.<br><br>
160: * @param obj any object
161: * @return the associated internal ID or <code>0</code>, if the passed
162: * object is not stored in this <code>ObjectContainer</code>.
163: */
164: public long getID(Object obj);
165:
166: /**
167: * returns the {@link ObjectInfo} for a stored object.
168: * <br><br>This method will return null, if the passed
169: * object is not stored to this <code>ObjectContainer</code>.<br><br>
170: * @param obj the stored object
171: * @return the {@link ObjectInfo}
172: */
173: public ObjectInfo getObjectInfo(Object obj);
174:
175: /**
176: * returns the Db4oDatabase object for this ObjectContainer.
177: * @return the Db4oDatabase identity object for this ObjectContainer.
178: */
179: public Db4oDatabase identity();
180:
181: /**
182: * tests if an object is activated.
183: * <br><br><code>isActive</code> returns <code>false</code> if an object is not
184: * stored within the <code>ObjectContainer</code>.<br><br>
185: * @param obj to be tested<br><br>
186: * @return <code>true</code> if the passed object is active.
187: */
188: public boolean isActive(Object obj);
189:
190: /**
191: * tests if an object with this ID is currently cached.
192: * <br><br>
193: * @param ID the internal ID
194: */
195: public boolean isCached(long ID);
196:
197: /**
198: * tests if this <code>ObjectContainer</code> is closed.
199: * <br><br>
200: * @return <code>true</code> if this <code>ObjectContainer</code> is closed.
201: */
202: public boolean isClosed();
203:
204: /**
205: * tests if an object is stored in this <code>ObjectContainer</code>.
206: * <br><br>
207: * @param obj to be tested<br><br>
208: * @return <code>true</code> if the passed object is stored.
209: * @throws DatabaseClosedException db4o database file was closed or failed to open.
210: */
211: public boolean isStored(Object obj) throws DatabaseClosedException;
212:
213: /**
214: * returns all class representations that are known to this
215: * ObjectContainer because they have been used or stored.
216: * @return all class representations that are known to this
217: * ObjectContainer because they have been used or stored.
218: */
219: public ReflectClass[] knownClasses();
220:
221: /**
222: * returns the main synchronisation lock.
223: * <br><br>
224: * Synchronize over this object to ensure exclusive access to
225: * the ObjectContainer.<br><br>
226: * Handle the use of this functionality with extreme care,
227: * since deadlocks can be produced with just two lines of code.
228: * @return Object the ObjectContainer lock object
229: */
230: public Object lock();
231:
232: /**
233: * aids migration of objects between ObjectContainers.
234: * <br><br>When objects are migrated from one ObjectContainer to another, it is
235: * desirable to preserve virtual object attributes such as the object version number
236: * or the UUID. Use this method to signal to an ObjectContainer that it should read
237: * existing version numbers and UUIDs from another ObjectContainer. This method should
238: * also be used during the {@link com.db4o.tools.Defragment Defragment} operation. It is included in the default
239: * implementation supplied in Defragment.java/Defragment.cs.<br><br>
240: * @param objectContainer the {@link ObjectContainer} objects are to be migrated
241: * from or <code>null</code> to denote that migration is completed.
242: */
243: public void migrateFrom(ObjectContainer objectContainer);
244:
245: /**
246: * returns a transient copy of a persistent object with all members set
247: * to the values that are currently stored to the database.
248: * <br><br>
249: * The returned objects have no connection to the database.<br><br>
250: * With the <code>committed</code> parameter it is possible to specify,
251: * whether the desired object should contain the committed values or the
252: * values that were set by the running transaction with
253: * {@link ObjectContainer#set(java.lang.Object)}.
254: * <br><br>A possible usecase for this feature:<br>
255: * An application might want to check all changes applied to an object
256: * by the running transaction.<br><br>
257: * @param object the object that is to be cloned
258: * @param depth the member depth to which the object is to be instantiated
259: * @param committed whether committed or set values are to be returned
260: * @return the object
261: */
262: public <T> T peekPersisted(T object, int depth, boolean committed);
263:
264: /**
265: * unloads all clean indices from memory and frees unused objects.
266: * <br><br>Call commit() and purge() consecutively to achieve the best
267: * result possible. This method can have a negative impact
268: * on performance since indices will have to be reread before further
269: * inserts, updates or queries can take place.
270: */
271: public void purge();
272:
273: /**
274: * unloads a specific object from the db4o reference mechanism.
275: * <br><br>db4o keeps references to all newly stored and
276: * instantiated objects in memory, to be able to manage object identities.
277: * <br><br>With calls to this method it is possible to remove an object from the
278: * reference mechanism, to allow it to be garbage collected. You are not required to
279: * call this method in the .NET and JDK 1.2 versions, since objects are
280: * referred to by weak references and garbage collection happens
281: * automatically.<br><br>An object removed with <code>purge(Object)</code> is not
282: * "known" to the <code>ObjectContainer</code> afterwards, so this method may also be
283: * used to create multiple copies of objects.<br><br> <code>purge(Object)</code> has
284: * no influence on the persistence state of objects. "Purged" objects can be
285: * reretrieved with queries.<br><br>
286: * @param obj the object to be removed from the reference mechanism.
287: */
288: public void purge(Object obj);
289:
290: /**
291: * Return the reflector currently being used by db4objects.
292: *
293: * @return the current Reflector.
294: */
295: public GenericReflector reflector();
296:
297: /**
298: * refreshs all members on a stored object to the specified depth.
299: * <br><br>If a member object is not activated, it will be activated by this method.
300: * <br><br>The isolation used is READ COMMITTED. This method will read all objects
301: * and values that have been committed by other transactions.<br><br>
302: * @param obj the object to be refreshed.
303: * @param depth the member {@link Configuration#activationDepth(int) depth}
304: * to which refresh is to cascade.
305: */
306: public void refresh(Object obj, int depth);
307:
308: /**
309: * releases a semaphore, if the calling transaction is the owner.
310: * @param name the name of the semaphore to be released.
311: */
312: public void releaseSemaphore(String name);
313:
314: /**
315: * @deprecated Since db4o-5.2. Use db4o Replication System (dRS)
316: * instead.<br><br>
317: * prepares for replication with another {@link ObjectContainer}.
318: * <br><br>An {@link ObjectContainer} can only be involved in a replication
319: * process with one other {@link ObjectContainer} at the same time.<br><br>
320: * The returned {@link ReplicationProcess} interface provides methods to commit
321: * and to cancel the replication process.
322: * <br><br>This ObjectContainer will be "peerA" for the
323: * returned ReplicationProcess. The other ObjectContainer will be "peerB".
324: * @param peerB the {@link ObjectContainer} to replicate with.
325: * @param conflictHandler the conflict handler for this ReplicationProcess.
326: * Conflicts occur
327: * whenever {@link ReplicationProcess#replicate(Object)} is called with an
328: * object that was modified in both ObjectContainers since the last
329: * replication run between the two. Upon a conflict the
330: * {@link ReplicationConflictHandler#resolveConflict(ReplicationProcess, Object, Object)}
331: * method will be called in the conflict handler.
332: * @return the {@link ReplicationProcess} interface for this replication process.
333: */
334: public ReplicationProcess replicationBegin(ObjectContainer peerB,
335: ReplicationConflictHandler conflictHandler);
336:
337: /**
338: * deep update interface to store or update objects.
339: * <br><br>In addition to the normal storage interface,
340: * {@link com.db4o.ObjectContainer#set ObjectContainer#set(Object)},
341: * this method allows a manual specification of the depth, the passed object is to be updated.<br><br>
342: * @param obj the object to be stored or updated.
343: * @param depth the depth to which the object is to be updated
344: * @see com.db4o.ObjectContainer#set
345: */
346: public void set(Object obj, int depth);
347:
348: /**
349: * attempts to set a semaphore.
350: * <br><br>
351: * Semaphores are transient multi-purpose named flags for
352: * {@link ObjectContainer ObjectContainers}.
353: * <br><br>
354: * A transaction that successfully sets a semaphore becomes
355: * the owner of the semaphore. Semaphores can only be owned
356: * by a single transaction at one point in time.<br><br>
357: * This method returns true, if the transaction already owned
358: * the semaphore before the method call or if it successfully
359: * acquires ownership of the semaphore.<br><br>
360: * The waitForAvailability parameter allows to specify a time
361: * in milliseconds to wait for other transactions to release
362: * the semaphore, in case the semaphore is already owned by
363: * another transaction.<br><br>
364: * Semaphores are released by the first occurence of one of the
365: * following:<br>
366: * - the transaction releases the semaphore with
367: * {@link #releaseSemaphore(java.lang.String)}<br> - the transaction is closed with {@link
368: * ObjectContainer#close()}<br> - C/S only: the corresponding {@link ObjectServer} is
369: * closed.<br> - C/S only: the client {@link ObjectContainer} looses the connection and is timed
370: * out.<br><br> Semaphores are set immediately. They are independant of calling {@link
371: * ObjectContainer#commit()} or {@link ObjectContainer#rollback()}.<br><br> <b>Possible usecases
372: * for semaphores:</b><br> - prevent other clients from inserting a singleton at the same time.
373: * A suggested name for the semaphore: "SINGLETON_" + Object#getClass().getName().<br> - lock
374: * objects. A suggested name: "LOCK_" + {@link #getID(java.lang.Object) getID(Object)}<br> -
375: * generate a unique client ID. A suggested name: "CLIENT_" +
376: * System.currentTimeMillis().<br><br>
377: *
378: * @param name the name of the semaphore to be set
379: * @param waitForAvailability the time in milliseconds to wait for other
380: * transactions to release the semaphore. The parameter may be zero, if
381: * the method is to return immediately.
382: * @return boolean flag
383: * <br><code>true</code>, if the semaphore could be set or if the
384: * calling transaction already owned the semaphore.
385: * <br><code>false</code>, if the semaphore is owned by another
386: * transaction.
387: */
388: public boolean setSemaphore(String name, int waitForAvailability);
389:
390: /**
391: * returns a {@link StoredClass} meta information object.
392: * <br><br>
393: * There are three options how to use this method.<br>
394: * Any of the following parameters are possible:<br>
395: * - a fully qualified classname.<br>
396: * - a Class object.<br>
397: * - any object to be used as a template.<br><br>
398: * @param clazz class name, Class object, or example object.<br><br>
399: * @return an instance of an {@link StoredClass} meta information object.
400: */
401: public StoredClass storedClass(Object clazz);
402:
403: /**
404: * returns an array of all {@link StoredClass} meta information objects.
405: */
406: public StoredClass[] storedClasses();
407:
408: /**
409: * returns the {@link SystemInfo} for this ObjectContainer.
410: * <br><br>The {@link SystemInfo} supplies methods that provide
411: * information about system state and system settings of this
412: * ObjectContainer.
413: * @return the {@link SystemInfo} for this ObjectContainer.
414: */
415: public SystemInfo systemInfo();
416:
417: /**
418: * returns the current transaction serial number.
419: * <br><br>This serial number can be used to query for modified objects
420: * and for replication purposes.
421: * @return the current transaction serial number.
422: */
423: public long version();
424:
425: }
|