Package 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
    The Activatable interface must be implemented by classes in order to support transparent activation/persistence.

    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 reference documentation.

    The basic idea for Transparent Activation is:
    Objects have an activation depth of 0, so 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 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) {
          this.next = next;
      }
   
      public Item next() {
          return next;
      }
      public void setNext(Item itemToBeSet) {
          this.next = itemToBeSet;
      }
      // ...
 }
    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 {
     private Item next;
     private transient Activator activator;
 
     public void bind(Activator activator) {
         if (this.activator == activator) {
              return;
         }
         if (activator != null && null != this.activator) {
              throw new IllegalStateException("Object can only be bound to one activator");
         }
         this.activator = activator;
     }
     public void activate(ActivationPurpose activationPurpose) {
         if(null!=activator){
              activator.activate(activationPurpose);
         }
     }
     // ...
 }
    The first action in every method body of an activatable object should be a call to the corresponding Activator's activate() method with the given purpose. If the method is reading the purpose should be ActivationPurpose.READ, for writing ActivationPurpose.WRITE. 
    
 public class Item implements Activatable {
     private Item next;
     private transient Activator activator;

     public void bind(Activator activator) {
         if (this.activator == activator) {
              return;
         }
         if (activator != null && null != this.activator) {
              throw new IllegalStateException("Object can only be bound to one activator");
         }
         this.activator = activator;
     }
     public void activate(ActivationPurpose activationPurpose) {
         if(null!=activator){
              activator.activate(activationPurpose);
         }
     }
     public Item next() {
         activate(ActivationPurpose.READ);
         return next;
     }
     public void setNext(Item itemToBeSet) {
         activate(ActivationPurpose.Write);
         this.next = itemToBeSet;
     }
     // ...
 }
    You always need to call activate() before any data access in the object. Otherwise transparent activation / persistence will not work. Since this process is error prone we recommend to use the enhancer tools shipped with db4o. 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 or TransparentPersistenceSupport has to be registered with the db4o configuration.

    
 EmbeddedConfiguration config = ... // your configuration
 configuration.common().add(new TransparentActivationSupport());
    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 Detail

      • bind

        void bind​(Activator activator)
        Called by db4o after the object instantiation. This method is called to bind the object to the current activator

        The recommended implementation of this method is to store the passed Activator in a transient field of the object.
        Parameters:
        activator - the Activator instance to bind