db4o 2.5

com.db4o
Interface ObjectContainer

All Known Subinterfaces:
ExtClient, ExtObjectContainer

public interface ObjectContainer

storage and query interface.

The ObjectContainer interface provides methods to store, retrieve and delete objects and to commit and rollback transactions.

See Also:
ExtObjectContainer for extended functionality.

Method Summary
 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.
 ObjectSet get(java.lang.Object template)
          Query-By-Example interface to retrieve objects.
 Query query()
          factory method to create a new Query object.
 void rollback()
          rolls back the running transaction.
 void set(java.lang.Object obj)
          newly stores objects or updates stored objects.
 

Method Detail

activate

public void activate(java.lang.Object obj,
                     int depth)
activates all members on a stored object to the specified depth.

Examples: ../com/db4o/samples/activate.

This method serves to traverse the graph of persistent objects. All members of an object can be activated in turn with subsequent calls.

Only objects in DEACTIVATED state are modified. Object members at the specified depth are instantiated in DEACTIVATED state.

Duplicate activate() calls on the same object have no effect. Passing an object that is not stored in the ObjectContainer has no effect.

The activation depth of individual classes can be overruled with the methods maximumActivationDepth() and minimumActivationDepth() in the ObjectClass interface.

A successful activate() triggers the callback method objectOnActivate which can be used for cascaded activation.

Parameters:
Object - the object to be activated.
depth - the member depth to which activate is to cascade.
See Also:
Why activation?,
Using callbacks

close

public boolean close()
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.

Subsequent calls to a closed ObjectContainer methods will result in exceptions.

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

commit

public void commit()
commits the running transaction.

deactivate

public void deactivate(java.lang.Object obj,
                       int depth)
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 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.

Parameters:
Object - the object to be deactivated.
depth - the member depth to which deactivate is to cascade.
See Also:
Using callbacks, Why activation?

delete

public void delete(java.lang.Object obj)
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 the callback method objectOnDelete which can be also used for cascaded deletes.

Parameters:
object - the object to be deleted from the ObjectContainer.
See Also:
ObjectClass#cascadeOnDelete, ObjectField#cascadeOnDelete, Using callbacks

ext

public 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

get

public ObjectSet get(java.lang.Object template)
Query-By-Example interface to retrieve objects.

get() creates an 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 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 get() can respond to the callback method objectOnActivate.

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

Returns:
ObjectSet containing all found objects.

See Also:
Why activation?,
Using callbacks

query

public Query query()
factory method to create a new Query object.

Use get(Object template) for simple Query-By-Example.

Returns:
a new Query object

rollback

public void rollback()
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.

set

public void set(java.lang.Object obj)
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 global or class-specific update depth was configured or cascaded updates were defined in the class or in one of the member fields.

Examples: ../com/db4o/samples/update.

Depending if the passed object is newly stored or updated, the callback method objectOnNew or objectOnUpdate is triggered. objectOnUpdate might also be used for cascaded updates.

Parameters:
Object - the object to be stored or updated.
See Also:
Configuration#updateDepth(), ObjectClass#updateDepth(), ObjectClass#cascadeOnUpdate(), ObjectField#cascadeOnUpdate(),
Using callbacks

db4o 2.5