com.db4o
Interface ObjectContainer

public interface ObjectContainer

storage and query interface.

The ObjectContainer interface provides all methods to store, retrieve and delete objects and to check or change object state.

close() closes the ObjectContainer.

commit() forces an instantaneous write of all possibly cached objects to the storage medium.

Method Summary

void	activate(java.lang.Object object) instantiates all members on a deactivated stored object.
void	activate(java.lang.Object object, int depth) activates all members on a stored object to the specified depth.
void	close() closes the ObjectContainer and writes all cached data.
void	commit() writes all cached objects to the storage medium instantaneously.
void	deactivate(java.lang.Object object) deactivates a stored object by setting all members to NULL.
void	delete(java.lang.Object object) deletes a stored object permanently.
ObjectSet	get(java.lang.Object template) Query-By-Example interface to retrieve objects.
boolean	isActive(java.lang.Object object) tests if an object is activated.
boolean	isStored(java.lang.Object object) tests if an object is stored in the ObjectContainer.
void	set(java.lang.Object object) newly stores objects or updates stored objects.
java.lang.String[]	storedClasses() returns a String array of the classnames of all stored classes.

Method Detail

activate

public void activate(java.lang.Object object)

instantiates all members on a deactivated stored object.
See activate(Object, depth) for further details.
activate(object) calls activate(object,1) internally.

Parameters:

Object - the object to be activated.

See Also:

Why activation?

activate

public void activate(java.lang.Object object,
                     int depth)

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

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.

See Also:

Why activation?,
Using callbacks

close

public void close()

closes the ObjectContainer and writes all cached data.
Subsequent calls to ObjectContainer methods will result in exceptions.

commit

public void commit()

writes all cached objects to the storage medium instantaneously.
This method is typically used for long running sessions, where a shutdown of the computer could result in a loss of data.

deactivate

public void deactivate(java.lang.Object object)

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 the callback method objectOnDeactivate.

Parameters:

Object - the object to be deactivated.

delete

public void delete(java.lang.Object object)

deletes a stored object permanently.

Note that this method has to be called for every single object independantly. Delete does not recurse on object members. Simple and array member types are destroyed.

Object members of the passed object remain untouched.

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 used for cascaded delete.

Parameters:

object - the object to be deleted from the ObjectContainer.

See Also:

Using callbacks

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 of all objects found.

See Also:

Why activation?,
Using callbacks

isActive

public boolean isActive(java.lang.Object object)

tests if an object is activated.
isActive returns false if an object is not stored within the ObjectContainer.

Parameters:

object - to be tested

Returns:

true if the passed object is active.

isStored

public boolean isStored(java.lang.Object object)

tests if an object is stored in the ObjectContainer.

Returns:

true if the passed object is stored.

set

public void set(java.lang.Object object)

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 class-specific update depth was configured.

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

Parameters:

Object - the object to be stored or updated.

See Also:

ObjectClass.#updateDepth(),
Using callbacks

storedClasses

public java.lang.String[] storedClasses()

returns a String array of the classnames of all stored classes.

Returns:

String[] classnames of all stored classes