com.db4o

Interface ObjectContainer

All Known Subinterfaces:

EmbeddedObjectContainer, ExtClient, ExtObjectContainer, InternalObjectContainer, ObjectContainerSpec

All Known Implementing Classes:

ExternalObjectContainer, IoAdaptedObjectContainer, LocalObjectContainer, ObjectContainerBase, ObjectContainerSession, TransportObjectContainer

public interface ObjectContainer

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 db4o server.

An ObjectContainer also represents a transaction. All work with db4o always is transactional. Both commit() and rollback() start new transactions immediately. For working against the same database with multiple transactions, open a db4o server with Db4o.openServer(String, int) and connect locally or over TCP.

See Also:

ExtObjectContainer for extended functionality.

Method Summary

Methods

Modifier and Type	Method and Description
void	activate(java.lang.Object obj, int depth) activates all members on a stored object to the specified depth.
boolean	close() closes the ObjectContainer.
void	commit() commits the running transaction.
void	deactivate(java.lang.Object obj, int depth) deactivates a stored object by setting all members to NULL.
void	delete(java.lang.Object obj) deletes a stored object permanently.
ExtObjectContainer	ext() returns an ObjectContainer with extended functionality.
Query	query() creates a new S.O.D.A.
<TargetType> ObjectSet<TargetType>	query(java.lang.Class<TargetType> clazz) queries for all instances of a class.
<TargetType> ObjectSet<TargetType>	query(Predicate<TargetType> predicate) Native Query Interface.
<TargetType> ObjectSet<TargetType>	query(Predicate<TargetType> predicate, java.util.Comparator<TargetType> comparator) Native Query Interface.
<TargetType> ObjectSet<TargetType>	query(Predicate<TargetType> predicate, QueryComparator<TargetType> comparator) Native Query Interface.
<T> ObjectSet<T>	queryByExample(java.lang.Object template) Query-By-Example interface to retrieve objects.
void	rollback() rolls back the running transaction.
void	store(java.lang.Object obj) newly stores objects or updates stored objects.

Method Detail

activate

void activate(java.lang.Object obj,
            int depth)
              throws Db4oIOException,
                     DatabaseClosedException

activates all members on a stored object to the specified depth.

See "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 maximumActivationDepth() and minimumActivationDepth() in the ObjectClass interface.

A successful call to activate triggers Activating and Activated callbacks, which can be used for cascaded activation.

Parameters:

obj - the object to be activated.

depth - the member depth to which activate is to cascade.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

See Also:

Why activation?, Using callbacks

close

boolean close()
              throws Db4oIOException

closes the ObjectContainer.

A call to close() automatically performs a 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.

Returns:

success - true denotes that the last used instance of this container and the database file were closed.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

commit

void commit()
            throws Db4oIOException,
                   DatabaseClosedException,
                   DatabaseReadOnlyException

commits the running transaction.

Transactions are back-to-back. A call to commit will starts a new transaction immedidately.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

DatabaseReadOnlyException - database was configured as read-only.

deactivate

void deactivate(java.lang.Object obj,
              int depth)
                throws DatabaseClosedException

deactivates a stored object by setting all members to NULL.
Primitive types will be set to their default values. Calls to this method save memory. The method has no effect, if the passed object is not stored in the ObjectContainer.

deactivate() triggers Deactivating and Deactivated callbacks.

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.

Parameters:

obj - the object to be deactivated.

depth - the member depth to which deactivate is to cascade.

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

See Also:

Using callbacks, Why activation?

delete

void delete(java.lang.Object obj)
            throws Db4oIOException,
                   DatabaseClosedException,
                   DatabaseReadOnlyException

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 configured for the class or for 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 Deleting and Deleted callbacks, which can be also used for cascaded deletes.

Parameters:

obj - the object to be deleted from the ObjectContainer.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

DatabaseReadOnlyException - database was configured as read-only.

See Also:

ObjectClass.cascadeOnDelete(boolean), ObjectField.cascadeOnDelete(boolean), Using callbacks

ext

ExtObjectContainer ext()

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.

Returns:

this, casted to ExtObjectContainer

queryByExample

<T> ObjectSet<T> queryByExample(java.lang.Object template)
                            throws Db4oIOException,
                                   DatabaseClosedException

Query-By-Example interface to retrieve objects.

queryByExample() creates an ObjectSet containing all objects in the ObjectContainer that match the passed template object.

Calling queryByExample(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 ObjectSet are instantiated and activated to the preconfigured depth of 5. The activation depth may be configured globally or 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 queryByExample() can respond to the Activating callback method.

Parameters:

template - object to be used as an example to find all matching objects.

Returns:

ObjectSet containing all found objects.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

See Also:

Why activation?, Using callbacks

query

Query query()
            throws DatabaseClosedException

creates a new S.O.D.A. Query.

Use queryByExample(Object) for simple Query-By-Example.

Native queries are the recommended main db4o query interface.

Returns:

a new Query object

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

query

<TargetType> ObjectSet<TargetType> query(java.lang.Class<TargetType> clazz)
                            throws Db4oIOException,
                                   DatabaseClosedException

queries for all instances of a class.

Parameters:

clazz - the class to query for.

Returns:

the ObjectSet returned by the query.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

query

<TargetType> ObjectSet<TargetType> query(Predicate<TargetType> predicate)
                            throws Db4oIOException,
                                   DatabaseClosedException

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:

// 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");
}
});

Summing up the above:
In order to run a Native Query, you can extend the Predicate class for all other language dialects

A class that extends Predicate is required to implement the #match() method, following the native query conventions:
- The name of the method is "#match()".
- The method must be public.
- The method returns a boolean.
- The method takes one parameter.
- The 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.

Parameters:

predicate - the Predicate containing the native query expression.

Returns:

the ObjectSet returned by the query.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

query

<TargetType> ObjectSet<TargetType> query(Predicate<TargetType> predicate,
                                       QueryComparator<TargetType> comparator)
                            throws Db4oIOException,
                                   DatabaseClosedException

Native Query Interface. Queries as with query(com.db4o.query.Predicate), but will sort the resulting ObjectSet according to the given QueryComparator.

Parameters:

predicate - the Predicate containing the native query expression.

comparator - the QueryComparator specifying the sort order of the result

Returns:

the ObjectSet returned by the query.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

query

<TargetType> ObjectSet<TargetType> query(Predicate<TargetType> predicate,
                                       java.util.Comparator<TargetType> comparator)
                            throws Db4oIOException,
                                   DatabaseClosedException

Native Query Interface. Queries as with query(com.db4o.query.Predicate), but will sort the resulting ObjectSet according to the given Comparator.

Parameters:

predicate - the Predicate containing the native query expression.

comparator - the java.util.Comparator specifying the sort order of the result

Returns:

the ObjectSet returned by the query.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

rollback

void rollback()
              throws Db4oIOException,
                     DatabaseClosedException,
                     DatabaseReadOnlyException

rolls back the running transaction.

Modified application objects im memory are not restored. Use combined calls to deactivate() and activate() to reload an objects member values.

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

DatabaseReadOnlyException - database was configured as read-only.

store

void store(java.lang.Object obj)
           throws DatabaseClosedException,
                  DatabaseReadOnlyException

newly stores objects or updates stored objects.

An object not yet stored in the ObjectContainer will be stored when it is passed to store(). 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 store() unless a deep global or class-specific update depth was configured or cascaded updates were defined in the class or in one of the member fields. Depending if the passed object is newly stored or updated, Creating/Created or Updating/Updated callback method is triggered. Callbacks might also be used for cascaded updates.

Parameters:

obj - the object to be stored or updated.

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

DatabaseReadOnlyException - database was configured as read-only.

See Also:

ExtObjectContainer#set(object, depth), Configuration.updateDepth(int), ObjectClass.updateDepth(int), ObjectClass.cascadeOnUpdate(boolean), ObjectField.cascadeOnUpdate(boolean), Using callbacks