Source code: com/ubermq/chord/ChordNode.java
1 package com.ubermq.chord;
2
3 /**
4 * Defines a node in the Chord system. Every node has an identifier
5 * in the identifier space, a successor node, and a finger table
6 * for efficient routing.
7 */
8 public interface ChordNode
9 {
10 /**
11 * Returns the identifier for this node.
12 *
13 * @return the node identifier on the identifier circle.
14 */
15 public ChordIdentifier identifier();
16
17 /**
18 * Closes the node's resources.
19 */
20 public void close();
21
22 ////// JOINING
23
24 /**
25 * Joins the node to the specified infrastructure. This causes the node
26 * to perform any logic that is required to inform itself or
27 * other nodes in the infrastructure about its presence.
28 *
29 * @param i the infrastructure that the node is joining
30 * @param m the size of the finger table
31 */
32 public void join(ChordInfrastructure i);
33
34 /**
35 * Leaves the infrastructure, by notifying the immediate predecessor that
36 * we are going away.
37 */
38 public void leave(ChordInfrastructure i);
39
40 /**
41 * Instructs the node that the specified node may be its predecessor.
42 *
43 * @param n a node, which is likely the predecessor for this node.
44 */
45 public void notify(ChordNode n);
46
47 /**
48 * Instructs the node that the specified node is leaving the infrastructure.
49 * This may be received by an existing predecessor or successor
50 * node. <P>
51 */
52 public void notifyGoingAway(ChordNode n);
53
54 ////// FINGER TABLE
55
56 /**
57 * Returns the finger table for this node. The finger table is
58 * a set of nodes, such that the <i>i</i><super>th</super> entry
59 * contains the identity of the first node that succeeds this node by at least
60 * 2 <super>i-1</super> on the identifier circle.
61 *
62 * @return a ChordNode[] containing the fingers for this node.
63 */
64 public ChordNode[] fingers();
65
66 /**
67 * Returns the element of the finger table
68 * that most closely precedes the given identifier.
69 *
70 * @return a ChordNode representing the closest finger to the identifier.
71 */
72 public ChordNode closestPrecedingFinger(ChordIdentifier id);
73
74 ////// NEIGHBORS
75
76 /**
77 * Returns the predecessor of this node, defined as the node
78 * n such that <code>n.successor() == this</code>.
79 *
80 * @return this node's predecessor.
81 */
82 public ChordNode predecessor();
83
84 /**
85 * Returns the successor of this node.
86 *
87 * @return a ChordNode that is the direct successor of this node.
88 */
89 public ChordNode successor();
90
91 ////// QUERY/STORE OPERATIONS
92
93 /**
94 * Queries the node for the object indexed at the specified key.
95 * If the key is not found, the method returns null.
96 */
97 public Object query(Object key);
98
99 /**
100 * Stores the specified object at the given key, on this node.
101 * The node may refuse the key if the hash value is not consistent.
102 *
103 * @throws IllegalStateException if the node is read-only
104 * @throws IllegalArgumentException if storing the key-value pair
105 * would break the chord invariants.
106 */
107 public void store(Object key, Object value);
108
109 ////// INFORMATIONAL
110
111 /**
112 * Returns an in-depth HTML description of this chord node.
113 * The information returned could include the set of keys
114 * stored here, etc.<P>
115 *
116 * It is anticipated that this method may be costly to invoke.
117 * Please do not use it for debugging purposes.
118 *
119 * @return HTML formatted descriptive text.
120 */
121 public String toHtml();
122 }