[Gzz-commits] gzz/lava/gzz/storm IndexedPool.java impl/Abstra...

[Benja Fallenstein]

CVSROOT:        /cvsroot/gzz
Module name:    gzz
Changes by:     Benja Fallenstein <address@hidden>      02/12/30 09:19:14

Modified files:
        lava/gzz/storm : IndexedPool.java 
        lava/gzz/storm/impl: AbstractPool.java 

Log message:
        Doc

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/gzz/lava/gzz/storm/IndexedPool.java.diff?tr1=1.9&tr2=1.10&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/gzz/lava/gzz/storm/impl/AbstractPool.java.diff?tr1=1.6&tr2=1.7&r1=text&r2=text

Patches:
Index: gzz/lava/gzz/storm/IndexedPool.java
diff -u gzz/lava/gzz/storm/IndexedPool.java:1.9 
gzz/lava/gzz/storm/IndexedPool.java:1.10
--- gzz/lava/gzz/storm/IndexedPool.java:1.9     Mon Dec 30 08:48:23 2002
+++ gzz/lava/gzz/storm/IndexedPool.java Mon Dec 30 09:19:13 2002
@@ -35,16 +35,58 @@
  *  but also for safety: whoever has a pointer to a StormPool
  *  is allowed to read, add and delete blocks, but not to
  *  mess up the pool by bringing it into an inconsistent state.
- *  An evil Index implementation would be capable of that.
+ *  An evil index implementation would be capable of that
+ *  (even though we try to limit damage).
  *  <p>
- *  XXX Explain how this works.
+ *  The internal model for every index is as follows:
+ *  <ul>
+ *  <li>Every block is deterministically mapped to a set of
+ *      <code>Mapping</code>s; a <code>Mapping</code>
+ *      has a key and a value, both of which are <code>String</code>s,
+ *      and is associated with a <code>BlockId</code>.</li>
+ *  <li><code>Mapping</code>s for blocks currently in the pool
+ *      can be looked up through the <code>DB</code> interface,
+ *      given the <code>Mapping</code>'s key.</li>
+ *  </ul>
+ *  An <code>IndexType</code> object provides a method
+ *  for retrieving the <code>Mapping</code>s associated
+ *  with a block, as well as a method for creating
+ *  a public interface representing an index (an index type-specific
+ *  interface that provides the lookups an index implements;
+ *  for example, the pointer index type provides
+ *  a <code>getPointer(String pointerURI)</code> method).
+ *  The block processor and the front-end are completely decoupled;
+ *  their only way to communicate is through the <code>DB</code>.
+ *  (In fact, even there their communication is indirect,
+ *  since the <code>IndexType.getMappings(Block)</code> method
+ *  doesn't know about the <code>DB</code> object; it merely
+ *  returns a <code>Set</code> of <code>Mapping</code>s
+ *  which is put into the <code>DB</code> by the <code>IndexedPool</code>.)
+ *  <p>
+ *  The <code>DB</code> is not shared between index types.
+ *  An <code>IndexType</code> has a unique URI, which is used
+ *  to tell the different index types' <code>DB</code>s apart.
+ *  One <code>IndexType</code> URI should always be bound
+ *  to one single interpretation of <code>Mapping</code> keys
+ *  and values, to ensure interoperability on a network:
+ *  all clients on a network should ideally agree what
+ *  a given key means for a given index type, so that they
+ *  will only produce relevant mappings for that key.
+ *  (Of course, all <code>IndexType</code>s must be robust
+ *  in the face of illegal data in the <code>DB</code>,
+ *  since there can always be malfunctioning or malicious nodes
+ *  on the network.)
+ *  <p>
+ *  Implementation node: Keys for distributed hashtables
+ *  can be simple concatenations of <code>IndexType</code> URIs
+ *  with <code>Mapping</code> keys.
  */
 public interface IndexedPool extends StormPool {
 
     final class Mapping {
-       public final Block block;
+       public final BlockId block;
        public final byte[] key, value;
-       public Mapping(Block b, byte[] k, byte[] v) { 
+       public Mapping(BlockId b, byte[] k, byte[] v) { 
            block=b; key=k; value=v; 
        }
     }
@@ -64,12 +106,12 @@
         *  @return The set of <code>IndexedPool.Mapping</code>s
         *          this index wants to extract from this block.
         *          The <code>block</code> field of each
-        *          returned <code>Mapping</code> must contain
+        *          returned <code>Mapping</code> must contain the id of
         *          the block passed to this method; if this
         *          isn't satisfied, an exception will be thrown.
         *          (XXX specify which and where...)
         */
-       Set process(Block b);
+       Set getMappings(Block b);
 
        /** A factory method for the public interface
         *  of this type of index.
Index: gzz/lava/gzz/storm/impl/AbstractPool.java
diff -u gzz/lava/gzz/storm/impl/AbstractPool.java:1.6 
gzz/lava/gzz/storm/impl/AbstractPool.java:1.7
--- gzz/lava/gzz/storm/impl/AbstractPool.java:1.6       Mon Dec 30 08:48:23 2002
+++ gzz/lava/gzz/storm/impl/AbstractPool.java   Mon Dec 30 09:19:14 2002
@@ -37,7 +37,8 @@
      *  the given index type URI.
      *  The implementing pool has to make sure
      *  that this is updated when blocks are added
-     *  or removed.
+     *  or removed (given that there's a corresponding
+     *  index type in <code>indexTypes</code>).
      */
     protected abstract DB getDB(String typeURI);