org.planx.xmlstore.routing
Class Kademlia

java.lang.Object
  org.planx.xmlstore.routing.Kademlia

All Implemented Interfaces:

DistributedMap

public class Kademlia
extends Object
implements DistributedMap

Maps keys to values in a distributed setting using the Kademlia protocol. Three threads are started: One that listens for incoming routing messages, one that handles timeouts for routing messages, and one that handles hourly refresh/restore.

Author:

Thomas Ambus

Constructor Summary

Kademlia(Identifier id, int udpPort)
Creates a Kademlia DistributedMap with the specified identifier and no persistence.

Kademlia(Identifier id, int udpPort, Configuration config)
Creates a Kademlia DistributedMap with the specified identifier and no persistence.

Kademlia(String name, Identifier defaultId, int udpPort, int contactPort, InetSocketAddress bootstrap, Configuration config)
Creates a Kademlia DistributedMap using the specified name as filename base.

Kademlia(String name, int udpPort, int contactPort, InetSocketAddress bootstrap)
Creates a Kademlia DistributedMap using the specified name as filename base.

Kademlia(String name, int udpPort, int contactPort, InetSocketAddress bootstrap, Configuration config)
Creates a Kademlia DistributedMap using the specified name as filename base.

Method Summary

void	addNeighbourhoodListener(NeighbourhoodListener listener) Adds a NeighbourhoodListener.
void	close() Closes the map.
void	connect(InetSocketAddress bootstrap) Attempts to connect to an existing peer-to-peer network.
boolean	contains(Identifier key) Returns true if the map contains the specified key and false otherwise.
Serializable	get(Identifier key) Returns the value associated with the specified key.
int	getContactPort() Returns the contact port set using the DistributedMap.setContactPort(int) method.
void	put(Identifier key, Serializable value) Associates the specified value with the specified key.
void	remove(Identifier key) Removes the mapping with the specified key.
void	removeNeighbourhoodListener(NeighbourhoodListener listener) Removes a NeighbourhoodListener.
List	responsiblePeers(Identifier key) Returns a List of InetSocketAddresses identifying the peers responsible for the specified key according to the underlying routing algorithm.
void	setContactPort(int port) Sets the contact port of this peer.
String	toString() For debugging purposes, returns the contents of the internal space.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Kademlia

public Kademlia(Identifier id,
                int udpPort)
         throws IOException,
                RoutingException

Creates a Kademlia DistributedMap with the specified identifier and no persistence.

Parameters:

id - The id to use or null to create a random id

udpPort - The UDP port to use for routing messages

Throws:

IOException

RoutingException

Kademlia

public Kademlia(Identifier id,
                int udpPort,
                Configuration config)
         throws IOException,
                RoutingException

Creates a Kademlia DistributedMap with the specified identifier and no persistence.

Parameters:

id - The id to use or null to create a random id

udpPort - The UDP port to use for routing messages

config - Configuration parameters

Throws:

IOException

RoutingException

Kademlia

public Kademlia(String name,
                int udpPort,
                int contactPort,
                InetSocketAddress bootstrap)
         throws IOException,
                RoutingException

Creates a Kademlia DistributedMap using the specified name as filename base. If the id cannot be read from disk a random id is created. The instance is bootstraped to an existing network by specifying the address of a bootstrap node in the network.

Parameters:

name - Filename base or null if persistence should not be used

udpPort - The UDP port to use for routing messages

contactPort - The application specific port (TCP or UDP) used to contact this peer

bootstrap - IP and UDP port of bootstrap node or null if the instance should not attempt to connect

Throws:

IOException

RoutingException

Kademlia

public Kademlia(String name,
                int udpPort,
                int contactPort,
                InetSocketAddress bootstrap,
                Configuration config)
         throws IOException,
                RoutingException

Creates a Kademlia DistributedMap using the specified name as filename base. If the id cannot be read from disk a random id is created. The instance is bootstraped to an existing network by specifying the address of a bootstrap node in the network.

Parameters:

name - Filename base or null if persistence should not be used

udpPort - The UDP port to use for routing messages

contactPort - The application specific port (TCP or UDP) used to contact this peer

bootstrap - IP and UDP port of bootstrap node or null if the instance should not attempt to connect

config - Configuration parameters. If null default parameters are used.

Throws:

IOException

RoutingException

Kademlia

public Kademlia(String name,
                Identifier defaultId,
                int udpPort,
                int contactPort,
                InetSocketAddress bootstrap,
                Configuration config)
         throws IOException,
                RoutingException

Creates a Kademlia DistributedMap using the specified name as filename base. If the id cannot be read from disk the specified defaultId is used. The instance is bootstraped to an existing network by specifying the address of a bootstrap node in the network.

Parameters:

name - Filename base or null if persistence should not be used

defaultId - Default id if it could not be read from disk or null for random default id

udpPort - The UDP port to use for routing messages

contactPort - The application specific port (TCP or UDP) used to contact this peer

bootstrap - IP and UDP port of bootstrap node or null if the instance should not attempt to connect

config - Configuration parameters. If null default parameters are used.

Throws:

RoutingException - If the bootstrap node did not respond

IOException - If an error occurred while reading id or local map from disk or a network error occurred while attempting to connect to the network

Method Detail

connect

public void connect(InetSocketAddress bootstrap)
             throws IOException,
                    RoutingException

Attempts to connect to an existing peer-to-peer network.

Parameters:

bootstrap - The IP and UDP port of a known node in the peer-to-peer network.

Throws:

RoutingException - If the bootstrap node could not be contacted

IOException - If a network error occurred

IllegalStateException - If this object is closed

close

public void close()
           throws IOException

Closes the map. Any subsequent calls to methods are invalid.

Specified by:

close in interface DistributedMap

Throws:

IOException - If an error occurred while writing data to disk

IllegalStateException - If this object is closed

contains

public boolean contains(Identifier key)
                 throws IOException,
                        RoutingException

Returns true if the map contains the specified key and false otherwise.

Specified by:

contains in interface DistributedMap

Parameters:

key - The key to lookup

Returns:

true if a mappings with the key was found and false otherwise.

Throws:

RoutingException - If the lookup operation timed out

IOException - If a network error occurred

IllegalStateException - If this object is closed

get

public Serializable get(Identifier key)
                 throws IOException,
                        RoutingException

Returns the value associated with the specified key. If the value is stored locally no Kademlia lookup is performed. See also DataLookupOperation.

Specified by:

get in interface DistributedMap

Parameters:

key - The key to lookup

Returns:

The value mapped to the key or null if no value is mapped to the key.

Throws:

RoutingException - If the lookup operation timed out

IOException - If a network error occurred

IllegalStateException - If this object is closed

put

public void put(Identifier key,
                Serializable value)
         throws IOException,
                RoutingException

Associates the specified value with the specified key. It is guaranteed that the mapping is stored on K nodes or all nodes if less than this number of nodes exist in the network. See also StoreOperation.

Specified by:

put in interface DistributedMap

Parameters:

key - The key

value - The value associated with the key

Throws:

RoutingException - If the operation timed out

IOException - If a network error occurred

IllegalStateException - If this object is closed

remove

public void remove(Identifier key)
            throws IOException

Removes the mapping with the specified key.

Specified by:

remove in interface DistributedMap

Parameters:

key - The key of the mapping to remove

Throws:

RoutingException - If the operation timed out

IOException - If a network error occurred

IllegalStateException - If this object is closed

getContactPort

public int getContactPort()

Description copied from interface: DistributedMap

Returns the contact port set using the DistributedMap.setContactPort(int) method.

Specified by:

getContactPort in interface DistributedMap

setContactPort

public void setContactPort(int port)

Description copied from interface: DistributedMap

Sets the contact port of this peer. This can be either a TCP or an UDP port. The interpretation is entirely up to the application programmer. The contact port is retrieved by other peers invoking the DistributedMap.responsiblePeers(org.planx.xmlstore.routing.Identifier) method. The behavoir of setting the contact port after bootstrapping is unspecified.

Specified by:

setContactPort in interface DistributedMap

responsiblePeers

public List responsiblePeers(Identifier key)
                      throws IOException,
                             RoutingException

Description copied from interface: DistributedMap

Returns a List of InetSocketAddresses identifying the peers responsible for the specified key according to the underlying routing algorithm. The InetSocketAddresses consist of the IP number of the peer and the contact port specified using the DistributedMap.setContactPort(int) method at the peer. Note that the number of returned peers is not specified - the specific number will be implementation dependent.

Specified by:

responsiblePeers in interface DistributedMap

Throws:

IOException

RoutingException

addNeighbourhoodListener

public void addNeighbourhoodListener(NeighbourhoodListener listener)

Description copied from interface: DistributedMap

Adds a NeighbourhoodListener.

Specified by:

addNeighbourhoodListener in interface DistributedMap

removeNeighbourhoodListener

public void removeNeighbourhoodListener(NeighbourhoodListener listener)

Description copied from interface: DistributedMap

Removes a NeighbourhoodListener.

Specified by:

removeNeighbourhoodListener in interface DistributedMap

toString

public String toString()

For debugging purposes, returns the contents of the internal space.

Overrides:

toString in class Object