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;
022:
023: import java.util.*;
024:
025: import com.db4o.ext.*;
026: import com.db4o.query.*;
027:
028: /**
029: * the interface to a db4o database, stand-alone or client/server.
030: * <br><br>The ObjectContainer interface provides methods
031: * to store, query and delete objects and to commit and rollback
032: * transactions.<br><br>
033: * An ObjectContainer can either represent a stand-alone database
034: * or a connection to a {@link Db4o#openServer(String, int) db4o server}.
035: * <br><br>An ObjectContainer also represents a transaction. All work
036: * with db4o always is transactional. Both {@link #commit()} and
037: * {@link #rollback()} start new transactions immediately. For working
038: * against the same database with multiple transactions, open a db4o server
039: * with {@link Db4o#openServer(String, int)} and
040: * {@link ObjectServer#openClient() connect locally} or
041: * {@link Db4o#openClient(String, int, String, String) over TCP}.
042: * @see ExtObjectContainer ExtObjectContainer for extended functionality.
043: * @sharpen.partial
044: */
045: public interface ObjectContainer {
046:
047: /**
048: * activates all members on a stored object to the specified depth.
049: * <br><br>
050: * See {@link com.db4o.config.Configuration#activationDepth(int) "Why activation"}
051: * for an explanation why activation is necessary.<br><br>
052: * The activate method activates a graph of persistent objects in memory.
053: * Only deactivated objects in the graph will be touched: their
054: * fields will be loaded from the database.
055: * The activate methods starts from a
056: * root object and traverses all member objects to the depth specified by the
057: * depth parameter. The depth parameter is the distance in "field hops"
058: * (object.field.field) away from the root object. The nodes at 'depth' level
059: * away from the root (for a depth of 3: object.member.member) will be instantiated
060: * but deactivated, their fields will be null.
061: * The activation depth of individual classes can be overruled
062: * with the methods
063: * {@link com.db4o.config.ObjectClass#maximumActivationDepth maximumActivationDepth()} and
064: * {@link com.db4o.config.ObjectClass#minimumActivationDepth minimumActivationDepth()} in the
065: * {@link com.db4o.config.ObjectClass ObjectClass interface}.<br><br>
066: * A successful call to activate triggers the callback method
067: * {@link com.db4o.ext.ObjectCallbacks#objectOnActivate objectOnActivate}
068: * which can be used for cascaded activation.<br><br>
069: * @see com.db4o.config.Configuration#activationDepth Why activation?
070: * @see ObjectCallbacks Using callbacks
071: * @param obj the object to be activated.
072: * @param depth the member {@link com.db4o.config.Configuration#activationDepth depth}
073: * to which activate is to cascade.
074: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
075: * @throws DatabaseClosedException db4o database file was closed or failed to open.
076: */
077: public void activate(Object obj, int depth) throws Db4oIOException,
078: DatabaseClosedException;
079:
080: /**
081: * closes the <code>ObjectContainer</code>.
082: * <br><br>A call to <code>close()</code> automatically performs a
083: * {@link #commit commit()}.
084: * <br><br>Note that every session opened with Db4o.openFile() requires one
085: * close()call, even if the same filename was used multiple times.<br><br>
086: * Use <code>while(!close()){}</code> to kill all sessions using this container.<br><br>
087: * @return success - true denotes that the last used instance of this container
088: * and the database file were closed.
089: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
090: */
091: public boolean close() throws Db4oIOException;
092:
093: /**
094: * commits the running transaction.
095: * <br><br>Transactions are back-to-back. A call to commit will starts
096: * a new transaction immedidately.
097: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
098: * @throws DatabaseClosedException db4o database file was closed or failed to open.
099: * @throws DatabaseReadOnlyException database was configured as read-only.
100: */
101: public void commit() throws Db4oIOException,
102: DatabaseClosedException, DatabaseReadOnlyException;
103:
104: /**
105: * deactivates a stored object by setting all members to <code>NULL</code>.
106: * <br>Primitive types will be set to their default values.
107: * <br><br><b>Examples: ../com/db4o/samples/activate.</b><br><br>
108: * Calls to this method save memory.
109: * The method has no effect, if the passed object is not stored in the
110: * <code>ObjectContainer</code>.<br><br>
111: * <code>deactivate()</code> triggers the callback method
112: * {@link com.db4o.ext.ObjectCallbacks#objectOnDeactivate objectOnDeactivate}.
113: * <br><br>
114: * Be aware that calling this method with a depth parameter greater than
115: * 1 sets members on member objects to null. This may have side effects
116: * in other places of the application.<br><br>
117: * @see ObjectCallbacks Using callbacks
118: * @see com.db4o.config.Configuration#activationDepth Why activation?
119: * @param obj the object to be deactivated.
120: * @param depth the member {@link com.db4o.config.Configuration#activationDepth depth}
121: * to which deactivate is to cascade.
122: * @throws DatabaseClosedException db4o database file was closed or failed to open.
123: */
124: public void deactivate(Object obj, int depth)
125: throws DatabaseClosedException;
126:
127: /**
128: * deletes a stored object permanently.
129: * <br><br>Note that this method has to be called <b>for every single object
130: * individually</b>. Delete does not recurse to object members. Simple
131: * and array member types are destroyed.
132: * <br><br>Object members of the passed object remain untouched, unless
133: * cascaded deletes are
134: * {@link com.db4o.config.ObjectClass#cascadeOnDelete configured for the class}
135: * or for {@link com.db4o.config.ObjectField#cascadeOnDelete one of the member fields}.
136: * <br><br>The method has no effect, if
137: * the passed object is not stored in the <code>ObjectContainer</code>.
138: * <br><br>A subsequent call to
139: * <code>set()</code> with the same object newly stores the object
140: * to the <code>ObjectContainer</code>.<br><br>
141: * <code>delete()</code> triggers the callback method
142: * {@link com.db4o.ext.ObjectCallbacks#objectOnDelete objectOnDelete}
143: * which can be also used for cascaded deletes.<br><br>
144: * @see com.db4o.config.ObjectClass#cascadeOnDelete
145: * @see com.db4o.config.ObjectField#cascadeOnDelete
146: * @see ObjectCallbacks Using callbacks
147: * @param obj the object to be deleted from the
148: * <code>ObjectContainer</code>.<br>
149: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
150: * @throws DatabaseClosedException db4o database file was closed or failed to open.
151: * @throws DatabaseReadOnlyException database was configured as read-only.
152: */
153: public void delete(Object obj) throws Db4oIOException,
154: DatabaseClosedException, DatabaseReadOnlyException;
155:
156: /**
157: * returns an ObjectContainer with extended functionality.
158: * <br><br>Every ObjectContainer that db4o provides can be casted to
159: * an ExtObjectContainer. This method is supplied for your convenience
160: * to work without a cast.
161: * <br><br>The ObjectContainer functionality is split to two interfaces
162: * to allow newcomers to focus on the essential methods.<br><br>
163: * @return this, casted to ExtObjectContainer
164: */
165: public ExtObjectContainer ext();
166:
167: /**
168: * Query-By-Example interface to retrieve objects.
169: * <br><br><code>get()</code> creates an
170: * {@link ObjectSet ObjectSet} containing
171: * all objects in the <code>ObjectContainer</code> that match the passed
172: * template object.<br><br>
173: * Calling <code>get(NULL)</code> returns all objects stored in the
174: * <code>ObjectContainer</code>.<br><br><br>
175: * <b>Query Evaluation</b>
176: * <br>All non-null members of the template object are compared against
177: * all stored objects of the same class.
178: * Primitive type members are ignored if they are 0 or false respectively.
179: * <br><br>Arrays and all supported <code>Collection</code> classes are
180: * evaluated for containment. Differences in <code>length/size()</code> are
181: * ignored.
182: * <br><br>Consult the documentation of the Configuration package to
183: * configure class-specific behaviour.<br><br><br>
184: * <b>Returned Objects</b><br>
185: * The objects returned in the
186: * {@link ObjectSet ObjectSet} are instantiated
187: * and activated to the preconfigured depth of 5. The
188: * {@link com.db4o.config.Configuration#activationDepth activation depth}
189: * may be configured {@link com.db4o.config.Configuration#activationDepth globally} or
190: * {@link com.db4o.config.ObjectClass individually for classes}.
191: * <br><br>
192: * db4o keeps track of all instantiatied objects. Queries will return
193: * references to these objects instead of instantiating them a second time.
194: * <br><br>
195: * Objects newly activated by <code>get()</code> can respond to the callback
196: * method {@link com.db4o.ext.ObjectCallbacks#objectOnActivate objectOnActivate}.
197: * <br><br>
198: * @param template object to be used as an example to find all matching objects.<br><br>
199: * @return {@link ObjectSet ObjectSet} containing all found objects.<br><br>
200: * @see com.db4o.config.Configuration#activationDepth Why activation?
201: * @see ObjectCallbacks Using callbacks
202: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
203: * @throws DatabaseClosedException db4o database file was closed or failed to open.
204: */
205: public <T> ObjectSet<T> get(Object template)
206: throws Db4oIOException, DatabaseClosedException;
207:
208: /**
209: * creates a new S.O.D.A. {@link Query Query}.
210: * <br><br>
211: * Use {@link #get get(Object template)} for simple Query-By-Example.<br><br>
212: * {@link #query(Predicate) Native queries } are the recommended main db4o query
213: * interface.
214: * <br><br>
215: * @return a new Query object
216: * @throws DatabaseClosedException db4o database file was closed or failed to open.
217: */
218: public Query query() throws DatabaseClosedException;
219:
220: /**
221: * queries for all instances of a class.
222: * @param clazz the class to query for.
223: * @return the {@link ObjectSet} returned by the query.
224: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
225: * @throws DatabaseClosedException db4o database file was closed or failed to open.
226: */
227: public <TargetType> ObjectSet<TargetType> query(
228: Class<TargetType> clazz) throws Db4oIOException,
229: DatabaseClosedException;
230:
231: /**
232: * Native Query Interface.
233: * <br><br>Native Queries allow typesafe, compile-time checked and refactorable
234: * querying, following object-oriented principles. Native Queries expressions
235: * are written as if one or more lines of code would be run against all
236: * instances of a class. A Native Query expression should return true to mark
237: * specific instances as part of the result set.
238: * db4o will attempt to optimize native query expressions and execute them
239: * against indexes and without instantiating actual objects, where this is
240: * possible.<br><br>
241: * The syntax of the enclosing object for the native query expression varies,
242: * depending on the language version used. Here are some examples,
243: * how a simple native query will look like in some of the programming languages
244: * and dialects that db4o supports:<br><br>
245: *
246: * <code>
247: * <b>// C# .NET 2.0</b><br>
248: * IList <Cat> cats = db.Query <Cat> (delegate(Cat cat) {<br>
249: *    return cat.Name == "Occam";<br>
250: * });<br>
251: * <br>
252: *<br>
253: * <b>// Java JDK 5</b><br>
254: * List <Cat> cats = db.query(new Predicate<Cat>() {<br>
255: *    public boolean match(Cat cat) {<br>
256: *       return cat.getName().equals("Occam");<br>
257: *    }<br>
258: * });<br>
259: * <br>
260: * <br>
261: * <b>// Java JDK 1.2 to 1.4</b><br>
262: * List cats = db.query(new Predicate() {<br>
263: *    public boolean match(Cat cat) {<br>
264: *       return cat.getName().equals("Occam");<br>
265: *    }<br>
266: * });<br>
267: * <br>
268: * <br>
269: * <b>// Java JDK 1.1</b><br>
270: * ObjectSet cats = db.query(new CatOccam());<br>
271: * <br>
272: * public static class CatOccam extends Predicate {<br>
273: *    public boolean match(Cat cat) {<br>
274: *       return cat.getName().equals("Occam");<br>
275: *    }<br>
276: * });<br>
277: * <br>
278: * <br>
279: * <b>// C# .NET 1.1</b><br>
280: * IList cats = db.Query(new CatOccam());<br>
281: * <br>
282: * public class CatOccam : Predicate {<br>
283: *    public boolean Match(Cat cat) {<br>
284: *       return cat.Name == "Occam";<br>
285: *    }<br>
286: * });<br>
287: * </code>
288:
289: * <br>
290: * Summing up the above:<br>
291: * In order to run a Native Query, you can<br>
292: * - use the delegate notation for .NET 2.0.<br>
293: * - extend the Predicate class for all other language dialects<br><br>
294: * A class that extends Predicate is required to
295: * implement the #match() / #Match() method, following the native query
296: * conventions:<br>
297: * - The name of the method is "#match()" (Java) / "#Match()" (.NET).<br>
298: * - The method must be public public.<br>
299: * - The method returns a boolean.<br>
300: * - The method takes one parameter.<br>
301: * - The Type (.NET) / Class (Java) of the parameter specifies the extent.<br>
302: * - For all instances of the extent that are to be included into the
303: * resultset of the query, the match method should return true. For all
304: * instances that are not to be included, the match method should return
305: * false.<br><br>
306: *
307: * @param predicate the {@link Predicate} containing the native query expression.
308: * @return the {@link ObjectSet} returned by the query.
309: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
310: * @throws DatabaseClosedException db4o database file was closed or failed to open.
311: */
312: public <TargetType> ObjectSet<TargetType> query(
313: Predicate<TargetType> predicate) throws Db4oIOException,
314: DatabaseClosedException;
315:
316: /**
317: * Native Query Interface. Queries as with {@link com.db4o.ObjectContainer#query(com.db4o.query.Predicate)},
318: * but will sort the resulting {@link com.db4o.ObjectSet} according to the given {@link com.db4o.query.QueryComparator}.
319: *
320: * @param predicate the {@link Predicate} containing the native query expression.
321: * @param comparator the {@link QueryComparator} specifiying the sort order of the result
322: * @return the {@link ObjectSet} returned by the query.
323: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
324: * @throws DatabaseClosedException db4o database file was closed or failed to open.
325: */
326: public <TargetType> ObjectSet<TargetType> query(
327: Predicate<TargetType> predicate,
328: QueryComparator<TargetType> comparator)
329: throws Db4oIOException, DatabaseClosedException;
330:
331: /**
332: * Native Query Interface. Queries as with {@link com.db4o.ObjectContainer#query(com.db4o.query.Predicate)},
333: * but will sort the resulting {@link com.db4o.ObjectSet} according to the given {@link com.db4o.query.QueryComparator}.
334: *
335: * @param predicate the {@link Predicate} containing the native query expression.
336: * @param comparator the java.util.Comparator specifying the sort order of the result
337: * @return the {@link ObjectSet} returned by the query.
338: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
339: * @throws DatabaseClosedException db4o database file was closed or failed to open.
340: */
341: public <TargetType> ObjectSet<TargetType> query(
342: Predicate<TargetType> predicate,
343: Comparator<TargetType> comparator) throws Db4oIOException,
344: DatabaseClosedException;
345:
346: /**
347: * rolls back the running transaction.
348: * <br><br>Modified application objects im memory are not restored.
349: * Use combined calls to {@link #deactivate deactivate()}
350: * and {@link #activate activate()} to reload an objects member values.
351: * @throws Db4oIOException I/O operation failed or was unexpectedly interrupted.
352: * @throws DatabaseClosedException db4o database file was closed or failed to open.
353: * @throws DatabaseReadOnlyException database was configured as read-only.
354: */
355: public void rollback() throws Db4oIOException,
356: DatabaseClosedException, DatabaseReadOnlyException;
357:
358: /**
359: * newly stores objects or updates stored objects.
360: * <br><br>An object not yet stored in the <code>ObjectContainer</code> will be
361: * stored when it is passed to <code>set()</code>. An object already stored
362: * in the <code>ObjectContainer</code> will be updated.
363: * <br><br><b>Updates</b><br>
364: * - will affect all simple type object members.<br>
365: * - links to object members that are already stored will be updated.<br>
366: * - new object members will be newly stored. The algorithm traverses down
367: * new members, as long as further new members are found.<br>
368: * - object members that are already stored will <b>not</b> be updated
369: * themselves.<br>Every object member needs to be updated individually with a
370: * call to <code>set()</code> unless a deep
371: * {@link com.db4o.config.Configuration#updateDepth global} or
372: * {@link com.db4o.config.ObjectClass#updateDepth class-specific}
373: * update depth was configured or cascaded updates were
374: * {@link com.db4o.config.ObjectClass#cascadeOnUpdate defined in the class}
375: * or in {@link com.db4o.config.ObjectField#cascadeOnUpdate one of the member fields}.
376: * <br><br><b>Examples: ../com/db4o/samples/update.</b><br><br>
377: * Depending if the passed object is newly stored or updated, the
378: * callback method
379: * {@link com.db4o.ext.ObjectCallbacks#objectOnNew objectOnNew} or
380: * {@link com.db4o.ext.ObjectCallbacks#objectOnUpdate objectOnUpdate} is triggered.
381: * {@link com.db4o.ext.ObjectCallbacks#objectOnUpdate objectOnUpdate}
382: * might also be used for cascaded updates.<br><br>
383: * @param obj the object to be stored or updated.
384: * @see ExtObjectContainer#set(java.lang.Object, int) ExtObjectContainer#set(object, depth)
385: * @see com.db4o.config.Configuration#updateDepth
386: * @see com.db4o.config.ObjectClass#updateDepth
387: * @see com.db4o.config.ObjectClass#cascadeOnUpdate
388: * @see com.db4o.config.ObjectField#cascadeOnUpdate
389: * @see ObjectCallbacks Using callbacks
390: * @throws DatabaseClosedException db4o database file was closed or failed to open.
391: * @throws DatabaseReadOnlyException database was configured as read-only.
392: */
393: public void set(Object obj) throws DatabaseClosedException,
394: DatabaseReadOnlyException;
395:
396: }
|