ObjectContainer


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;
22  
23  import com.db4o.ext.*;
24  import com.db4o.query.*;
25  
26  
27  /**
28   * the interface to a db4o database, stand-alone or client/server.
29   * <br><br>The ObjectContainer interface provides methods
30   * to store, query and delete objects and to commit and rollback
31   * transactions.<br><br>
32   * An ObjectContainer can either represent a stand-alone database
33   * or a connection to a {@link Db4o#openServer(String, int) db4o server}.
34   * <br><br>An ObjectContainer also represents a transaction. All work
35   * with db4o always is transactional. Both {@link #commit()} and
36   * {@link #rollback()} start new transactions immediately. For working 
37   * against the same database with multiple transactions, open a db4o server
38   * with {@link Db4o#openServer(String, int)} and 
39   * {@link ObjectServer#openClient() connect locally} or
40   * {@link Db4o#openClient(String, int, String, String) over TCP}.
41   * @see ExtObjectContainer ExtObjectContainer for extended functionality.
42   * 
43   * @sharpen.partial
44   * @sharpen.ignore
45   */
46  public interface ObjectContainer {
47      
48      /**
49       * activates all members on a stored object to the specified depth.
50       * <br><br>
51       * See {@link com.db4o.config.Configuration#activationDepth(int) "Why activation"}
52       * for an explanation why activation is necessary.<br><br>
53       * The activate method activates a graph of persistent objects in memory.
54       * Only deactivated objects in the graph will be touched: their
55       * fields will be loaded from the database. 
56       * The activate methods starts from a
57       * root object and traverses all member objects to the depth specified by the
58       * depth parameter. The depth parameter is the distance in "field hops" 
59       * (object.field.field) away from the root object. The nodes at 'depth' level
60       * away from the root (for a depth of 3: object.member.member) will be instantiated
61       * but deactivated, their fields will be null.
62       * The activation depth of individual classes can be overruled
63       * with the methods
64       * {@link com.db4o.config.ObjectClass#maximumActivationDepth maximumActivationDepth()} and
65       * {@link com.db4o.config.ObjectClass#minimumActivationDepth minimumActivationDepth()} in the
66       * {@link com.db4o.config.ObjectClass ObjectClass interface}.<br><br>
67       * A successful call to activate triggers the callback method
68       * {@link com.db4o.ext.ObjectCallbacks#objectOnActivate objectOnActivate}
69       * which can be used for cascaded activation.<br><br>
70       * @see com.db4o.config.Configuration#activationDepth Why activation?
71       * @see ObjectCallbacks Using callbacks
72       * @param obj the object to be activated.
73       * @param depth the member {@link com.db4o.config.Configuration#activationDepth depth}
74       *  to which activate is to cascade.
75       */
76      public void activate (Object   obj, int depth);
77      
78      /**
79       * closes this ObjectContainer.
80       * <br><br>A call to close() automatically performs a 
81       * {@link #commit commit()}.
82       * <br><br>Note that every session opened with Db4o.openFile() requires one
83       * close()call, even if the same filename was used multiple times.<br><br>
84       * Use <code>while(!close()){}</code> to kill all sessions using this container.<br><br>
85       * @return success - true denotes that the last used instance of this container
86       * and the database file were closed.
87       */
88      public boolean close ();
89  
90      /**
91       * commits the running transaction.
92       * <br><br>Transactions are back-to-back. A call to commit will starts
93       * a new transaction immedidately.
94       */
95      public void commit ();
96      
97  
98      /**
99       * deactivates a stored object by setting all members to <code>NULL</code>.
100      * <br>Primitive types will be set to their default values.
101      * <br><br><b>Examples: ../com/db4o/samples/activate.</b><br><br>
102      * Calls to this method save memory.
103      * The method has no effect, if the passed object is not stored in the
104      * <code>ObjectContainer</code>.<br><br>
105      * <code>deactivate()</code> triggers the callback method
106      * {@link com.db4o.ext.ObjectCallbacks#objectOnDeactivate objectOnDeactivate}.
107      * <br><br>
108      * Be aware that calling this method with a depth parameter greater than 
109      * 1 sets members on member objects to null. This may have side effects 
110      * in other places of the application.<br><br>
111      * @see ObjectCallbacks Using callbacks
112      * @see com.db4o.config.Configuration#activationDepth Why activation?
113      * @param obj the object to be deactivated.
114      * @param depth the member {@link com.db4o.config.Configuration#activationDepth depth} 
115      * to which deactivate is to cascade.
116     */
117     public void deactivate (Object   obj, int depth);
118 
119     /**
120      * deletes a stored object permanently.
121      * <br><br>Note that this method has to be called <b>for every single object
122      * individually</b>. Delete does not recurse to object members. Simple
123      * and array member types are destroyed.
124      * <br><br>Object members of the passed object remain untouched, unless
125      * cascaded deletes are  
126      * {@link com.db4o.config.ObjectClass#cascadeOnDelete configured for the class}
127      * or for {@link com.db4o.config.ObjectField#cascadeOnDelete one of the member fields}.
128      * <br><br>The method has no effect, if
129      * the passed object is not stored in the <code>ObjectContainer</code>.
130      * <br><br>A subsequent call to
131      * <code>set()</code> with the same object newly stores the object
132      * to the <code>ObjectContainer</code>.<br><br>
133      * <code>delete()</code> triggers the callback method
134      * {@link com.db4o.ext.ObjectCallbacks#objectOnDelete objectOnDelete}
135      * which can be also used for cascaded deletes.<br><br>
136      * @see com.db4o.config.ObjectClass#cascadeOnDelete
137      * @see com.db4o.config.ObjectField#cascadeOnDelete
138      * @see ObjectCallbacks Using callbacks
139      * @param obj the object to be deleted from the
140      * <code>ObjectContainer</code>.<br>
141      */
142     public void delete (Object   obj);
143     
144     /**
145      * returns an ObjectContainer with extended functionality.
146      * <br><br>Every ObjectContainer that db4o provides can be casted to
147      * an ExtObjectContainer. This method is supplied for your convenience
148      * to work without a cast.
149      * <br><br>The ObjectContainer functionality is split to two interfaces
150      * to allow newcomers to focus on the essential methods.<br><br>
151      * @return this, casted to ExtObjectContainer
152      */
153     public ExtObjectContainer ext();
154     
155     /**
156      * Query-By-Example interface to retrieve objects.
157      * <br><br><code>get()</code> creates an
158      * {@link ObjectSet ObjectSet} containing
159      * all objects in the <code>ObjectContainer</code> that match the passed
160      * template object.<br><br>
161      * Calling <code>get(NULL)</code> returns all objects stored in the
162      * <code>ObjectContainer</code>.<br><br><br>
163      * <b>Query Evaluation</b>
164      * <br>All non-null members of the template object are compared against
165      * all stored objects of the same class.
166      * Primitive type members are ignored if they are 0 or false respectively.
167      * <br><br>Arrays and all supported <code>Collection</code> classes are
168      * evaluated for containment. Differences in <code>length/size()</code> are
169      * ignored.
170      * <br><br>Consult the documentation of the Configuration package to
171      * configure class-specific behaviour.<br><br><br>
172      * <b>Returned Objects</b><br>
173      * The objects returned in the
174      * {@link ObjectSet ObjectSet} are instantiated
175      * and activated to the preconfigured depth of 5. The
176      * {@link com.db4o.config.Configuration#activationDepth activation depth}
177      * may be configured {@link com.db4o.config.Configuration#activationDepth globally} or
178      * {@link com.db4o.config.ObjectClass individually for classes}.
179      * <br><br>
180      * db4o keeps track of all instantiatied objects. Queries will return
181      * references to these objects instead of instantiating them a second time.
182      * <br><br>
183      * Objects newly activated by <code>get()</code> can respond to the callback
184      * method {@link com.db4o.ext.ObjectCallbacks#objectOnActivate objectOnActivate}.
185      * <br><br>
186      * @param template object to be used as an example to find all matching objects.<br><br>
187      * @return {@link ObjectSet ObjectSet} containing all found objects.<br><br>
188      * @see com.db4o.config.Configuration#activationDepth Why activation?
189      * @see ObjectCallbacks Using callbacks
190      */
191     public ObjectSet get (Object   template);
192     
193     /**
194      * creates a new SODA {@link Query Query}.
195      * <br><br>
196      * Use {@link #get get(Object template)} for simple Query-By-Example.<br><br>
197      * {@link #query(Predicate) Native queries } are the recommended main db4o query
198      * interface. 
199      * <br><br>
200      * @return a new Query object
201      */
202     public Query query ();
203     
204     /**
205      * queries for all instances of a class.
206      * @param clazz the class to query for.
207      * @return the {@link ObjectSet} returned by the query.
208      */
209     public ObjectSet query(Class   clazz);
210 
211     
212     /**
213      * Native Query Interface.
214      * <br><br>Native Queries allow typesafe, compile-time checked and refactorable 
215      * querying, following object-oriented principles. Native Queries expressions
216      * are written as if one or more lines of code would be run against all
217      * instances of a class. A Native Query expression should return true to mark 
218      * specific instances as part of the result set. 
219      * db4o will  attempt to optimize native query expressions and execute them 
220      * against indexes and without instantiating actual objects, where this is 
221      * possible.<br><br>
222      * The syntax of the enclosing object for the native query expression varies,
223      * depending on the language version used. Here are some examples,
224      * how a simple native query will look like in some of the programming languages 
225      * and dialects that db4o supports:<br><br>
226      * 
227      * <code>
228      * <b>// C# .NET 2.0</b><br>
229      * IList &lt;Cat&gt; cats = db.Query &lt;Cat&gt; (delegate(Cat cat) {<br>
230      * &#160;&#160;&#160;return cat.Name == "Occam";<br>
231      * });<br>
232      * <br>
233      *<br>
234      * <b>// Java JDK 5</b><br>
235      * List &lt;Cat&gt; cats = db.query(new Predicate&lt;Cat&gt;() {<br>
236      * &#160;&#160;&#160;public boolean match(Cat cat) {<br>
237      * &#160;&#160;&#160;&#160;&#160;&#160;return cat.getName().equals("Occam");<br>
238      * &#160;&#160;&#160;}<br>
239      * });<br>
240      * <br>
241      * <br>
242      * <b>// Java JDK 1.2 to 1.4</b><br>
243      * List cats = db.query(new Predicate() {<br>
244      * &#160;&#160;&#160;public boolean match(Cat cat) {<br>
245      * &#160;&#160;&#160;&#160;&#160;&#160;return cat.getName().equals("Occam");<br>
246      * &#160;&#160;&#160;}<br>
247      * });<br>
248      * <br>
249      * <br>
250      * <b>// Java JDK 1.1</b><br>
251      * ObjectSet cats = db.query(new CatOccam());<br>
252      * <br>
253      * public static class CatOccam extends Predicate {<br>
254      * &#160;&#160;&#160;public boolean match(Cat cat) {<br>
255      * &#160;&#160;&#160;&#160;&#160;&#160;return cat.getName().equals("Occam");<br>
256      * &#160;&#160;&#160;}<br>
257      * });<br>
258      * <br>
259      * <br>     
260      * <b>// C# .NET 1.1</b><br>
261      * IList cats = db.Query(new CatOccam());<br>
262      * <br>
263      * public class CatOccam : Predicate {<br>
264      * &#160;&#160;&#160;public boolean Match(Cat cat) {<br>
265      * &#160;&#160;&#160;&#160;&#160;&#160;return cat.Name == "Occam";<br>
266      * &#160;&#160;&#160;}<br>
267      * });<br>
268      * </code>
269      * <br>
270      * Summing up the above:<br>
271      * In order to run a Native Query, you can<br>
272      * - use the delegate notation for .NET 2.0.<br>
273      * - extend the Predicate class for all other language dialects<br><br>
274      * A class that extends Predicate is required to 
275      * implement the #match() / #Match() method, following the native query
276      * conventions:<br>
277      * - The name of the method is "#match()" (Java) / "#Match()" (.NET).<br>
278      * - The method must be public public.<br>
279      * - The method returns a boolean.<br>
280      * - The method takes one parameter.<br>
281      * - The Type (.NET) / Class (Java) of the parameter specifies the extent.<br>
282      * - For all instances of the extent that are to be included into the
283      * resultset of the query, the match method should return true. For all
284      * instances that are not to be included, the match method should return
285      * false.<br><br>  
286      *   
287      * @param predicate the {@link Predicate} containing the native query expression.
288      * @return the {@link ObjectSet} returned by the query.
289      */
290     public ObjectSet query(Predicate predicate);
291 
292     /**
293      * Native Query Interface. Queries as with {@link com.db4o.ObjectContainer#query(com.db4o.query.Predicate)},
294      * but will sort the resulting {@link com.db4o.ObjectSet} according to the given {@link com.db4o.query.QueryComparator}.
295      * 
296      * @param predicate the {@link Predicate} containing the native query expression.
297      * @param comparator the {@link QueryComparator} specifiying the sort order of the result
298      * @return the {@link ObjectSet} returned by the query.
299      */
300     public ObjectSet query(Predicate predicate,QueryComparator comparator);
301 
302     /**
303      * rolls back the running transaction.
304      * <br><br>Transactions are back-to-back. A call to rollback will starts
305      * a new transaction immedidately.
306      * <br><br>rollback will not restore modified objects in memory. They
307      * can be refreshed from the database by calling 
308      * {@link ExtObjectContainer#refresh(Object, int)}.
309      */
310     public void rollback();
311     
312     /**
313      * newly stores objects or updates stored objects.
314      * <br><br>An object not yet stored in the <code>ObjectContainer</code> will be
315      * stored when it is passed to <code>set()</code>. An object already stored
316      * in the <code>ObjectContainer</code> will be updated.
317      * <br><br><b>Updates</b><br>
318      * - will affect all simple type object members.<br>
319      * - links to object members that are already stored will be updated.<br>
320      * - new object members will be newly stored. The algorithm traverses down
321      * new members, as long as further new members are found.<br>
322      * - object members that are already stored will <b>not</b> be updated
323      * themselves.<br>Every object member needs to be updated individually with a
324      * call to <code>set()</code> unless a deep
325      * {@link com.db4o.config.Configuration#updateDepth global} or 
326      * {@link com.db4o.config.ObjectClass#updateDepth class-specific}
327      * update depth was configured or cascaded updates were 
328      * {@link com.db4o.config.ObjectClass#cascadeOnUpdate defined in the class}
329      * or in {@link com.db4o.config.ObjectField#cascadeOnUpdate one of the member fields}.
330      * <br><br><b>Examples: ../com/db4o/samples/update.</b><br><br>
331      * Depending if the passed object is newly stored or updated, the
332      * callback method
333      * {@link com.db4o.ext.ObjectCallbacks#objectOnNew objectOnNew} or
334      * {@link com.db4o.ext.ObjectCallbacks#objectOnUpdate objectOnUpdate} is triggered.
335      * {@link com.db4o.ext.ObjectCallbacks#objectOnUpdate objectOnUpdate}
336      * might also be used for cascaded updates.<br><br>
337      * @param obj the object to be stored or updated.
338      * @see ExtObjectContainer#set(java.lang.Object, int) ExtObjectContainer#set(object, depth)
339      * @see com.db4o.config.Configuration#updateDepth
340      * @see com.db4o.config.ObjectClass#updateDepth
341      * @see com.db4o.config.ObjectClass#cascadeOnUpdate
342      * @see com.db4o.config.ObjectField#cascadeOnUpdate
343      * @see ObjectCallbacks Using callbacks
344      */
345     public void set (Object   obj);
346     
347     
348     
349 }
350 
351 
352 
353
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags