35 |
* but also for safety: whoever has a pointer to a StormPool |
* but also for safety: whoever has a pointer to a StormPool |
36 |
* is allowed to read, add and delete blocks, but not to |
* is allowed to read, add and delete blocks, but not to |
37 |
* mess up the pool by bringing it into an inconsistent state. |
* mess up the pool by bringing it into an inconsistent state. |
38 |
* An evil Index implementation would be capable of that. |
* An evil index implementation would be capable of that |
39 |
|
* (even though we try to limit damage). |
40 |
* <p> |
* <p> |
41 |
* XXX Explain how this works. |
* The internal model for every index is as follows: |
42 |
|
* <ul> |
43 |
|
* <li>Every block is deterministically mapped to a set of |
44 |
|
* <code>Mapping</code>s; a <code>Mapping</code> |
45 |
|
* has a key and a value, both of which are <code>String</code>s, |
46 |
|
* and is associated with a <code>BlockId</code>.</li> |
47 |
|
* <li><code>Mapping</code>s for blocks currently in the pool |
48 |
|
* can be looked up through the <code>DB</code> interface, |
49 |
|
* given the <code>Mapping</code>'s key.</li> |
50 |
|
* </ul> |
51 |
|
* An <code>IndexType</code> object provides a method |
52 |
|
* for retrieving the <code>Mapping</code>s associated |
53 |
|
* with a block, as well as a method for creating |
54 |
|
* a public interface representing an index (an index type-specific |
55 |
|
* interface that provides the lookups an index implements; |
56 |
|
* for example, the pointer index type provides |
57 |
|
* a <code>getPointer(String pointerURI)</code> method). |
58 |
|
* The block processor and the front-end are completely decoupled; |
59 |
|
* their only way to communicate is through the <code>DB</code>. |
60 |
|
* (In fact, even there their communication is indirect, |
61 |
|
* since the <code>IndexType.getMappings(Block)</code> method |
62 |
|
* doesn't know about the <code>DB</code> object; it merely |
63 |
|
* returns a <code>Set</code> of <code>Mapping</code>s |
64 |
|
* which is put into the <code>DB</code> by the <code>IndexedPool</code>.) |
65 |
|
* <p> |
66 |
|
* The <code>DB</code> is not shared between index types. |
67 |
|
* An <code>IndexType</code> has a unique URI, which is used |
68 |
|
* to tell the different index types' <code>DB</code>s apart. |
69 |
|
* One <code>IndexType</code> URI should always be bound |
70 |
|
* to one single interpretation of <code>Mapping</code> keys |
71 |
|
* and values, to ensure interoperability on a network: |
72 |
|
* all clients on a network should ideally agree what |
73 |
|
* a given key means for a given index type, so that they |
74 |
|
* will only produce relevant mappings for that key. |
75 |
|
* (Of course, all <code>IndexType</code>s must be robust |
76 |
|
* in the face of illegal data in the <code>DB</code>, |
77 |
|
* since there can always be malfunctioning or malicious nodes |
78 |
|
* on the network.) |
79 |
|
* <p> |
80 |
|
* Implementation node: Keys for distributed hashtables |
81 |
|
* can be simple concatenations of <code>IndexType</code> URIs |
82 |
|
* with <code>Mapping</code> keys. |
83 |
*/ |
*/ |
84 |
public interface IndexedPool extends StormPool { |
public interface IndexedPool extends StormPool { |
85 |
|
|
86 |
final class Mapping { |
final class Mapping { |
87 |
public final Block block; |
public final BlockId block; |
88 |
public final byte[] key, value; |
public final byte[] key, value; |
89 |
public Mapping(Block b, byte[] k, byte[] v) { |
public Mapping(BlockId b, byte[] k, byte[] v) { |
90 |
block=b; key=k; value=v; |
block=b; key=k; value=v; |
91 |
} |
} |
92 |
} |
} |
106 |
* @return The set of <code>IndexedPool.Mapping</code>s |
* @return The set of <code>IndexedPool.Mapping</code>s |
107 |
* this index wants to extract from this block. |
* this index wants to extract from this block. |
108 |
* The <code>block</code> field of each |
* The <code>block</code> field of each |
109 |
* returned <code>Mapping</code> must contain |
* returned <code>Mapping</code> must contain the id of |
110 |
* the block passed to this method; if this |
* the block passed to this method; if this |
111 |
* isn't satisfied, an exception will be thrown. |
* isn't satisfied, an exception will be thrown. |
112 |
* (XXX specify which and where...) |
* (XXX specify which and where...) |
113 |
*/ |
*/ |
114 |
Set process(Block b); |
Set getMappings(Block b); |
115 |
|
|
116 |
/** A factory method for the public interface |
/** A factory method for the public interface |
117 |
* of this type of index. |
* of this type of index. |