de.uniba.wiai.lspi.chord.service
Interface Chord

All Known Implementing Classes:
ChordImpl

public interface Chord

Provides all methods necessary for a user application. This includes methods for changing connectivity to the network (create, join, leave) as well as for working with content (insert, retrieve, remove).


Method Summary
 void create()
          Creates a new chord network which is not connected to any other node.
 void create(URL localURL)
          Creates a new chord network which is not connected to any other node.
 void create(URL localURL, ID localID)
          Creates a new chord network which is not connected to any other node.
 ID getID()
          Returns the ID of the local node; is null if no network has been created or joined.
 URL getURL()
          Returns the URL of the local node; is null if no network has been created or joined.
 void insert(Key key, Serializable object)
          Inserts a new data object into the network stored under the given key.
 void join(URL bootstrapURL)
          Joins an existing chord network and announces its presence to the other nodes.
 void join(URL localURL, ID localID, URL bootstrapURL)
          Joins an existing chord network and announces its presence to the other nodes.
 void join(URL localURL, URL bootstrapURL)
          Joins an existing chord network and announces its presence to the other nodes.
 void leave()
          Disconnects from the network.
 void remove(Key key, Serializable object)
          Removes the given object stored under given key from the network.
 Set<Serializable> retrieve(Key key)
          Attempts to find all objects with given key.
 void setID(ID nodeID)
          Sets the ID of the local node to the given value; only available before creating or joining a network.
 void setURL(URL nodeURL)
          Sets the URL of the local node to the given value; only available before creating or joining a network.
 

Method Detail

getURL

URL getURL()
Returns the URL of the local node; is null if no network has been created or joined.

Returns:
URL of local node.

setURL

void setURL(URL nodeURL)
            throws IllegalStateException
Sets the URL of the local node to the given value; only available before creating or joining a network.

Parameters:
nodeURL - New URL of local node.
Throws:
NullPointerException - If given URL reference has value null.
IllegalStateException - If network has already been created or joined.

getID

ID getID()
Returns the ID of the local node; is null if no network has been created or joined.

Returns:
ID of local node.

setID

void setID(ID nodeID)
           throws IllegalStateException
Sets the ID of the local node to the given value; only available before creating or joining a network.

Parameters:
nodeID - New ID of local node.
Throws:
NullPointerException - If given ID reference has value null.
IllegalStateException - If network has already been created or joined.

create

void create()
            throws ServiceException
Creates a new chord network which is not connected to any other node. Assumes that at least the node URL has been set before by setURL(de.uniba.wiai.lspi.chord.data.URL). If no ID has been set before, it is generated by applying a hash function on the node URL.

Throws:
ServiceException - Is thrown if creating the local chord node fails, e.g. due to unability of creating the endpoint for incoming messages. Is also thrown if no URL has been set before.

create

void create(URL localURL)
            throws ServiceException
Creates a new chord network which is not connected to any other node. The node ID is generated by applying a hash function on the node URL.

Parameters:
localURL - URL on which this node accepts incoming requests from other chord nodes. The ID of this node is generated by applying a hash function on the node URL.
Throws:
NullPointerException - If localURL is null.
ServiceException - Is thrown if creating the local chord node fails, e.g. due to unability of creating the endpoint for incoming messages.

create

void create(URL localURL,
            ID localID)
            throws ServiceException
Creates a new chord network which is not connected to any other node.

Parameters:
localURL - URL on which this node accepts incoming requests from other chord nodes.
localID - ID of this node.
Throws:
NullPointerException - If localURL or localID is null.
ServiceException - Is thrown if creating the local chord node fails, e.g. due to unability of creating the endpoint for incoming messages.

join

void join(URL bootstrapURL)
          throws ServiceException
Joins an existing chord network and announces its presence to the other nodes. Assumes that at least the node URL has been set before by setURL(de.uniba.wiai.lspi.chord.data.URL). If no ID has been set before, it is generated by applying a hash function on the node URL.

Parameters:
bootstrapURL - URL of one existing node which is used as bootstrap node.
Throws:
NullPointerException - If bootstrapURL is null.
ServiceException - If joining fails this exception is thrown. This may be due to failure of establishing an endpoint or communication problems when contacting the bootstrap node. Is also thrown if no URL has been set before.

join

void join(URL localURL,
          URL bootstrapURL)
          throws ServiceException
Joins an existing chord network and announces its presence to the other nodes. The node ID is generated by applying a hash function on the node URL.

Parameters:
localURL - The local node is made available under this URL.
bootstrapURL - URL of one existing node which is used as bootstrap node.
Throws:
NullPointerException - If localURL or bootstrapURL is null.
ServiceException - If joining fails this exception is thrown. This may be due to failure of establishing an endpoint or communication problems when contacting the bootstrap node.

join

void join(URL localURL,
          ID localID,
          URL bootstrapURL)
          throws ServiceException
Joins an existing chord network and announces its presence to the other nodes.

Parameters:
localURL - The local node is made available under this URL.
localID - ID of this node.
bootstrapURL - URL of one existing node which is used as bootstrap node.
Throws:
NullPointerException - If localURL, localID, or bootstrapURL is null.
ServiceException - If joining fails this exception is thrown. This may be due to failure of establishing an endpoint or communication problems when contacting the bootstrap node.

leave

void leave()
           throws ServiceException
Disconnects from the network.

Throws:
ServiceException - If properly leaving the network fails this exception is thrown. The network might have been left as if the local node has failed. However, disconnecting from the network is done in every case.

insert

void insert(Key key,
            Serializable object)
            throws ServiceException
Inserts a new data object into the network stored under the given key. If two or more objects with same keys exist, all of them are stored.

Parameters:
key - Key, under which the new item is stored.
object - Object for storage in the network.
Throws:
NullPointerException - If key or object is null.
ServiceException - Thrown if insertion failed. The effect of the insertion operation is undefined if this exception occurs.

retrieve

Set<Serializable> retrieve(Key key)
                           throws ServiceException
Attempts to find all objects with given key.

Parameters:
key - Key for which objects shall be retrieved.
Returns:
All objects stored under given key. Set of Serializable
Throws:
NullPointerException - If key is null.
ServiceException - Is thrown if retrieval failed, e.g. due to a communication failure. However, the network is left in a stable state.

remove

void remove(Key key,
            Serializable object)
            throws ServiceException
Removes the given object stored under given key from the network.

Parameters:
key - Key under which the object currently is stored.
object - Object to remove from the network.
Throws:
NullPointerException - If key or object is null.
ServiceException - Thrown if deletion failed. The effect of the delete operation is undefined if this exception occurs.


Copyright © 2004-2008 Karsten Loesing, Sven Kaffille - Distributed and Mobile Systems Group, Lehrstuhl für Praktische Informatik, Universität Bamberg. All Rights Reserved.