Source code: com/ubermq/chord/ChordInfrastructure.java
1 package com.ubermq.chord;
2
3 /**
4 * The chord infrastructure is the single entry-point into a Chord
5 * system for clients. This provides global query and store operations.
6 * <P>
7 *
8 * Chord requires clients to know about at least one node in order to
9 * connect to the infrastructure. The one node may be discovered via
10 * broadcast, or well-known. The infrastructure interface also provides
11 * a way for clients to identify this entry point node.<P>
12 *
13 * Individual implementations need to define how this node is initially
14 * discovered and how entry into the infrastructure is accomplished.<P>
15 *
16 * This interface also provides a way for nodes to join and leave
17 * the infrastructure.<P>
18 */
19 import java.rmi.*;
20
21 public interface ChordInfrastructure
22 {
23 /**
24 * Queries the infrastructure for the value associated with a key.
25 * Since a query operation is computationally and network intensive,
26 * it is assumed that nodes have some expectation that the given key
27 * resides somewhere in the infrastructure.<P>
28 *
29 * If the key does not have a value associated with it,
30 * or a value cannot be determined, null is returned.
31 *
32 * @param key the key to query.
33 * @return the object stored with the key, or null if no value is
34 * found.
35 *
36 * @throws RemoteException if the network is unavailable.
37 */
38 public Object query(Object key)
39 throws RemoteException;
40
41 /**
42 * Stores the given value at the specified key, somewhere in the
43 * chord infrastructure. In the absence of concurrent modification,
44 * it is true that:<p>
45 *
46 * <code>
47 * given i.store(key, v), then
48 * v == i.query(key);
49 * </code>
50 * <P>
51 *
52 * By design, clients should not need to be aware of physically
53 * where the information associated with the key is stored.
54 *
55 * @param key the key at which the value is stored
56 * @param value the value to store
57 * @throws RemoteException if the infrastructure is unavailable.
58 */
59 public void store(Object key, Object value)
60 throws RemoteException;
61
62 /**
63 * Closes the interface to the infrastructure and any related
64 * resources.
65 */
66 public void close();
67
68 /**
69 * The local entry point node that was used to gain access
70 * to the infrastructure.
71 *
72 * @return a local chord node entry point.
73 */
74 public ChordNode entryPoint();
75
76 /**
77 * Returns the Service URL of the entry point used to gain access
78 * to the infrastructure.
79 *
80 * @return the url of the entry point.
81 */
82 public java.net.URI getEntryPointURI();
83
84 /**
85 * Returns the node that follows the specified identifier
86 * on the identifier circle. This node is known as the
87 * <i>successor</i>, and is in charge of storing keys
88 * for the given identifier.
89 *
90 * @param id an identifier
91 * @return the successor node.
92 */
93 public ChordNode findSuccessor(ChordIdentifier id);
94
95 /**
96 * Returns the node that precedes the specified identifier
97 * on the identifier circle.
98 *
99 * @param id an identifier
100 * @return the predecessor node.
101 */
102 public ChordNode findPredecessor(ChordIdentifier id);
103
104 }