com.db4o.ta

Interface Activatable

All Known Subinterfaces:

ActivatableCollection<T>, ActivatableList<T>, ActivatableMap<K,V>, ActivatableSet<E>

All Known Implementing Classes:

ActivatableArrayList, ActivatableBase, ActivatableHashMap, ActivatableHashSet, ActivatableHashtable, ActivatableLinkedList, ActivatableStack, ActivatableTreeSet, ArrayList4, ArrayMap4

public interface Activatable

Activatable must be implemented by classes in order to support Transparent Activation.

The Activatable interface may be added to persistent classes by hand or by using the db4o enhancer. For further information on the enhancer see the chapter "Enhancement" in the db4o tutorial.

The basic idea for Transparent Activation is as follows:
Objects have an activation depth of 0, i.e. by default they are not activated at all. Whenever a method is called on such an object, the first thing to do before actually executing the method body is to activate the object to level 1, i.e. populating its direct members.

To illustrate this approach, we will use the following simple class.

public class Item {
private Item _next;

public Item(Item next) {
_next = next;
}

public Item next() {
return _next;
}
}

The basic sequence of actions to get the above scheme to work is the following:

- Whenever an object is instantiated from db4o, the database registers an activator for this object. To enable this, the object has to implement the Activatable interface and provide the according bind(Activator) method. The default implementation of the bind method will simply store the given activator reference for later use.

public class Item implements Activatable {
transient Activator _activator;

public void bind(Activator activator) {
if (null != _activator) {
throw new IllegalStateException();
}
_activator = activator;
}

// ...
}

- The first action in every method body of an activatable object should be a call to the corresponding Activator's activate() method. (Note that this is not enforced by any interface, it is rather a convention, and other implementations are possible.)

public class Item implements Activatable {
public void activate() {
if (_activator == null) return;
_activator.activate();
}

public Item next() {
activate();
return _next;
}
}

- The activate() method will check whether the object is already activated. If this is not the case, it will request the container to activate the object to level 1 and set the activated flag accordingly.

To instruct db4o to actually use these hooks (i.e. to register the database when instantiating an object), TransparentActivationSupport has to be registered with the db4o configuration.

Configuration config = ...
config.add(new TransparentActivationSupport());

Java: If you implement this interface manually and intend to pass this class through the db4o bytecode instrumentation process, make sure you also implement the ActivatableInstrumented marker interface.

Method Summary

Methods

Modifier and Type	Method and Description
void	activate(ActivationPurpose purpose) should be called by every reading field access of an object.
void	bind(Activator activator) called by db4o upon instantiation.

Method Detail

bind

void bind(Activator activator)

called by db4o upon instantiation.

The recommended implementation of this method is to store the passed Activator in a transient field of the object.

Parameters:

activator - the Activator

activate

void activate(ActivationPurpose purpose)

should be called by every reading field access of an object.

The recommended implementation of this method is to call Activator.activate(ActivationPurpose) on the Activator that was previously passed to bind(Activator).

Parameters:

purpose - TODO