001: /* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com
002:
003: This file is part of the db4o open source object database.
004:
005: db4o is free software; you can redistribute it and/or modify it under
006: the terms of version 2 of the GNU General Public License as published
007: by the Free Software Foundation and as clarified by db4objects' GPL
008: interpretation policy, available at
009: http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
010: Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
011: Suite 350, San Mateo, CA 94403, USA.
012:
013: db4o is distributed in the hope that it will be useful, but WITHOUT ANY
014: WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: for more details.
017:
018: You should have received a copy of the GNU General Public License along
019: with this program; if not, write to the Free Software Foundation, Inc.,
020: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
021: package com.db4o.ta;
022:
023: import com.db4o.activation.Activator;
024:
025: /**
026: * The basic idea for this initial TA implementation is very simple:
027: * Objects have an activation depth of 0, i.e. by default they are
028: * not activated at all. Whenever a method is called on such an object,
029: * the first thing to do before actually executing the method body is
030: * to activate the object to level 1, i.e. populating its direct
031: * members.
032: *
033: * To illustrate this approach, we will use the following simple class.
034: *
035: * public class Item {
036: * private Item _next;
037: *
038: * public Item(Item next) {
039: * _next = next;
040: * }
041: *
042: * public Item next() {
043: * return _next;
044: * }
045: * }
046: *
047: * The basic sequence of actions to get the above scheme to work is the
048: * following:
049: *
050: * - Whenever an object is instantiated from db4o, the database registers
051: * an activator for this object. To enable this, the object has to implement
052: * the Activatable interface and provide the according bind(Activator)
053: * method. The default implementation of the bind method will simply store
054: * the given activator reference for later use.
055: *
056: * public class Item implements Activatable {
057: * transient Activator _activator;
058: *
059: * public void bind(Activator activator) {
060: * if (null != _activator) {
061: * throw new IllegalStateException();
062: * }
063: * _activator = activator;
064: * }
065: *
066: * // ...
067: * }
068: *
069: * - The first action in every method body of an activatable object should
070: * be a call to the corresponding Activator's activate() method. (Note that
071: * this is not enforced by any interface, it is rather a convention, and
072: * other implementations are possible.)
073: *
074: * public class Item implements Activatable {
075: * public void activate() {
076: * if (_activator == null) return;
077: * _activator.activate();
078: * }
079: *
080: * public Item next() {
081: * activate();
082: * return _next;
083: * }
084: * }
085: *
086: * - The activate() method will check whether the object is already activated.
087: * If this is not the case, it will request the container to activate the
088: * object to level 1 and set the activated flag accordingly.
089: *
090: * To instruct db4o to actually use these hooks (i.e. to register the
091: * database when instantiating an object), TransparentActivationSupport
092: * has to be registered with the db4o configuration.
093: *
094: * Configuration config = ...
095: * config.add(new TransparentActivationSupport());
096: *
097: * This basic implementation may still be subject to changes. For example,
098: * the "one activator per object" policy could be dropped in favor of a
099: * (probably Map based) per-container registry of activatable objects, or
100: * by reusing existing db4o internal metadata (like ObjectReference) for
101: * TA purposes.
102: */
103: public interface Activatable {
104: void bind(Activator activator);
105:
106: void activate();
107: }
|