com.db4o.ObjectContainer Maven / Gradle / Ivy
The newest version!
/* Copyright (C) 2004 - 2005 db4objects Inc. http://www.db4o.com
This file is part of the db4o open source object database.
db4o is free software; you can redistribute it and/or modify it under
the terms of version 2 of the GNU General Public License as published
by the Free Software Foundation and as clarified by db4objects' GPL
interpretation policy, available at
http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
Suite 350, San Mateo, CA 94403, USA.
db4o is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
package com.db4o;
import com.db4o.ext.*;
import com.db4o.query.*;
/**
* the interface to a db4o database, stand-alone or client/server.
*
The ObjectContainer interface provides methods
* to store, query and delete objects and to commit and rollback
* transactions.
* An ObjectContainer can either represent a stand-alone database
* or a connection to a {@link Db4o#openServer(String, int) db4o server}.
*
An ObjectContainer also represents a transaction. All work
* with db4o always is transactional. Both {@link #commit()} and
* {@link #rollback()} start new transactions immediately. For working
* against the same database with multiple transactions, open a db4o server
* with {@link Db4o#openServer(String, int)} and
* {@link ObjectServer#openClient() connect locally} or
* {@link Db4o#openClient(String, int, String, String) over TCP}.
* @see ExtObjectContainer ExtObjectContainer for extended functionality.
*/
public interface ObjectContainer {
/**
* activates all members on a stored object to the specified depth.
*
* See {@link com.db4o.config.Configuration#activationDepth(int) "Why activation"}
* for an explanation why activation is necessary.
* The activate method activates a graph of persistent objects in memory.
* Only deactivated objects in the graph will be touched: their
* fields will be loaded from the database.
* The activate methods starts from a
* root object and traverses all member objects to the depth specified by the
* depth parameter. The depth parameter is the distance in "field hops"
* (object.field.field) away from the root object. The nodes at 'depth' level
* away from the root (for a depth of 3: object.member.member) will be instantiated
* but deactivated, their fields will be null.
* The activation depth of individual classes can be overruled
* with the methods
* {@link com.db4o.config.ObjectClass#maximumActivationDepth maximumActivationDepth()} and
* {@link com.db4o.config.ObjectClass#minimumActivationDepth minimumActivationDepth()} in the
* {@link com.db4o.config.ObjectClass ObjectClass interface}.
* A successful call to activate triggers the callback method
* {@link com.db4o.ext.ObjectCallbacks#objectOnActivate objectOnActivate}
* which can be used for cascaded activation.
* @see com.db4o.config.Configuration#activationDepth Why activation?
* @see ObjectCallbacks Using callbacks
* @param obj the object to be activated.
* @param depth the member {@link com.db4o.config.Configuration#activationDepth depth}
* to which activate is to cascade.
*/
public void activate (Object obj, int depth);
/**
* closes this ObjectContainer.
*
A call to close() automatically performs a
* {@link #commit commit()}.
*
Note that every session opened with Db4o.openFile() requires one
* close()call, even if the same filename was used multiple times.
* Use while(!close()){} to kill all sessions using this container.
* @return success - true denotes that the last used instance of this container
* and the database file were closed.
*/
public boolean close ();
/**
* commits the running transaction.
*
Transactions are back-to-back. A call to commit will starts
* a new transaction immedidately.
*/
public void commit ();
/**
* deactivates a stored object by setting all members to NULL.
*
Primitive types will be set to their default values.
*
Examples: ../com/db4o/samples/activate.
* Calls to this method save memory.
* The method has no effect, if the passed object is not stored in the
* ObjectContainer.
* deactivate() triggers the callback method
* {@link com.db4o.ext.ObjectCallbacks#objectOnDeactivate objectOnDeactivate}.
*
* Be aware that calling this method with a depth parameter greater than
* 1 sets members on member objects to null. This may have side effects
* in other places of the application.
* @see ObjectCallbacks Using callbacks
* @see com.db4o.config.Configuration#activationDepth Why activation?
* @param obj the object to be deactivated.
* @param depth the member {@link com.db4o.config.Configuration#activationDepth depth}
* to which deactivate is to cascade.
*/
public void deactivate (Object obj, int depth);
/**
* deletes a stored object permanently.
*
Note that this method has to be called for every single object
* individually. Delete does not recurse to object members. Simple
* and array member types are destroyed.
*
Object members of the passed object remain untouched, unless
* cascaded deletes are
* {@link com.db4o.config.ObjectClass#cascadeOnDelete configured for the class}
* or for {@link com.db4o.config.ObjectField#cascadeOnDelete one of the member fields}.
*
The method has no effect, if
* the passed object is not stored in the ObjectContainer.
*
A subsequent call to
* set() with the same object newly stores the object
* to the ObjectContainer.
* delete() triggers the callback method
* {@link com.db4o.ext.ObjectCallbacks#objectOnDelete objectOnDelete}
* which can be also used for cascaded deletes.
* @see com.db4o.config.ObjectClass#cascadeOnDelete
* @see com.db4o.config.ObjectField#cascadeOnDelete
* @see ObjectCallbacks Using callbacks
* @param obj the object to be deleted from the
* ObjectContainer.
*/
public void delete (Object obj);
/**
* returns an ObjectContainer with extended functionality.
*
Every ObjectContainer that db4o provides can be casted to
* an ExtObjectContainer. This method is supplied for your convenience
* to work without a cast.
*
The ObjectContainer functionality is split to two interfaces
* to allow newcomers to focus on the essential methods.
* @return this, casted to ExtObjectContainer
*/
public ExtObjectContainer ext();
/**
* Query-By-Example interface to retrieve objects.
*
get() creates an
* {@link ObjectSet ObjectSet} containing
* all objects in the ObjectContainer that match the passed
* template object.
* Calling get(NULL) returns all objects stored in the
* ObjectContainer.
* Query Evaluation
*
All non-null members of the template object are compared against
* all stored objects of the same class.
* Primitive type members are ignored if they are 0 or false respectively.
*
Arrays and all supported Collection classes are
* evaluated for containment. Differences in length/size() are
* ignored.
*
Consult the documentation of the Configuration package to
* configure class-specific behaviour.
* Returned Objects
* The objects returned in the
* {@link ObjectSet ObjectSet} are instantiated
* and activated to the preconfigured depth of 5. The
* {@link com.db4o.config.Configuration#activationDepth activation depth}
* may be configured {@link com.db4o.config.Configuration#activationDepth globally} or
* {@link com.db4o.config.ObjectClass individually for classes}.
*
* db4o keeps track of all instantiatied objects. Queries will return
* references to these objects instead of instantiating them a second time.
*
* Objects newly activated by get() can respond to the callback
* method {@link com.db4o.ext.ObjectCallbacks#objectOnActivate objectOnActivate}.
*
* @param template object to be used as an example to find all matching objects.
* @return {@link ObjectSet ObjectSet} containing all found objects.
* @see com.db4o.config.Configuration#activationDepth Why activation?
* @see ObjectCallbacks Using callbacks
*/
public ObjectSet get (Object template);
/**
* creates a new SODA {@link Query Query}.
*
* Use {@link #get get(Object template)} for simple Query-By-Example.
* {@link #query(Predicate) Native queries } are the recommended main db4o query
* interface.
*
* @return a new Query object
*/
public Query query ();
/**
* queries for all instances of a class.
* @param clazz the class to query for.
* @return the {@link ObjectSet} returned by the query.
*/
public ObjectSet query(Class clazz);
/**
* Native Query Interface.
*
Native Queries allow typesafe, compile-time checked and refactorable
* querying, following object-oriented principles. Native Queries expressions
* are written as if one or more lines of code would be run against all
* instances of a class. A Native Query expression should return true to mark
* specific instances as part of the result set.
* db4o will attempt to optimize native query expressions and execute them
* against indexes and without instantiating actual objects, where this is
* possible.
* The syntax of the enclosing object for the native query expression varies,
* depending on the language version used. Here are some examples,
* how a simple native query will look like in some of the programming languages
* and dialects that db4o supports:
*
*
* // C# .NET 2.0
* IList <Cat> cats = db.Query <Cat> (delegate(Cat cat) {
* return cat.Name == "Occam";
* });
*
*
* // Java JDK 5
* List <Cat> cats = db.query(new Predicate<Cat>() {
* public boolean match(Cat cat) {
* return cat.getName().equals("Occam");
* }
* });
*
*
* // Java JDK 1.2 to 1.4
* List cats = db.query(new Predicate() {
* public boolean match(Cat cat) {
* return cat.getName().equals("Occam");
* }
* });
*
*
* // Java JDK 1.1
* ObjectSet cats = db.query(new CatOccam());
*
* public static class CatOccam extends Predicate {
* public boolean match(Cat cat) {
* return cat.getName().equals("Occam");
* }
* });
*
*
* // C# .NET 1.1
* IList cats = db.Query(new CatOccam());
*
* public class CatOccam : Predicate {
* public boolean Match(Cat cat) {
* return cat.Name == "Occam";
* }
* });
*
*
* Summing up the above:
* In order to run a Native Query, you can
* - use the delegate notation for .NET 2.0.
* - extend the Predicate class for all other language dialects
* A class that extends Predicate is required to
* implement the #match() / #Match() method, following the native query
* conventions:
* - The name of the method is "#match()" (Java) / "#Match()" (.NET).
* - The method must be public public.
* - The method returns a boolean.
* - The method takes one parameter.
* - The Type (.NET) / Class (Java) of the parameter specifies the extent.
* - For all instances of the extent that are to be included into the
* resultset of the query, the match method should return true. For all
* instances that are not to be included, the match method should return
* false.
*
* @param predicate the {@link Predicate} containing the native query expression.
* @return the {@link ObjectSet} returned by the query.
*/
public ObjectSet query(Predicate predicate);
public ObjectSet query(Predicate predicate,QueryComparator comparator);
/**
* rolls back the running transaction.
*
Transactions are back-to-back. A call to rollback will starts
* a new transaction immedidately.
*
rollback will not restore modified objects in memory. They
* can be refreshed from the database by calling
* {@link ExtObjectContainer#refresh(Object, int)}.
*/
public void rollback();
/**
* newly stores objects or updates stored objects.
*
An object not yet stored in the ObjectContainer will be
* stored when it is passed to set(). An object already stored
* in the ObjectContainer will be updated.
*
Updates
* - will affect all simple type object members.
* - links to object members that are already stored will be updated.
* - new object members will be newly stored. The algorithm traverses down
* new members, as long as further new members are found.
* - object members that are already stored will not be updated
* themselves.
Every object member needs to be updated individually with a
* call to set() unless a deep
* {@link com.db4o.config.Configuration#updateDepth global} or
* {@link com.db4o.config.ObjectClass#updateDepth class-specific}
* update depth was configured or cascaded updates were
* {@link com.db4o.config.ObjectClass#cascadeOnUpdate defined in the class}
* or in {@link com.db4o.config.ObjectField#cascadeOnUpdate one of the member fields}.
*
Examples: ../com/db4o/samples/update.
* Depending if the passed object is newly stored or updated, the
* callback method
* {@link com.db4o.ext.ObjectCallbacks#objectOnNew objectOnNew} or
* {@link com.db4o.ext.ObjectCallbacks#objectOnUpdate objectOnUpdate} is triggered.
* {@link com.db4o.ext.ObjectCallbacks#objectOnUpdate objectOnUpdate}
* might also be used for cascaded updates.
* @param obj the object to be stored or updated.
* @see ExtObjectContainer#set(java.lang.Object, int) ExtObjectContainer#set(object, depth)
* @see com.db4o.config.Configuration#updateDepth
* @see com.db4o.config.ObjectClass#updateDepth
* @see com.db4o.config.ObjectClass#cascadeOnUpdate
* @see com.db4o.config.ObjectField#cascadeOnUpdate
* @see ObjectCallbacks Using callbacks
*/
public void set (Object obj);
}