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).

Version:

1.0.5 modified, 0.99b

Author:

Sven Kaffille, Karsten Loesing, bojanm, francesco

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.
URL	getURL() Returns the URL of the local node; is null if no network has been created or joined.
void	initialJoin(Floor floor, URL bootstrapURL)
void	initialJoin(Floor floor, URL localURL, URL bootstrapURL)
void	insert(java.lang.String res, java.io.Serializable object) Inserts a new data object into the network stored under the given key.
void	join(Floor floor, URL bootstrapURL) Joins an existing chord network and announces its presence to the other nodes.
void	join(Floor floor, 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(java.lang.String res, java.io.Serializable object) Removes the given object stored under given key from the network.
java.util.Set<java.io.Serializable>	retrieve(java.lang.String res) Attempts to find all objects with given key.
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 java.lang.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:

java.lang.NullPointerException - If given URL reference has value null.

java.lang.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:

java.lang.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.

join

void join(Floor floor,
          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:

java.lang.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.

initialJoin

void initialJoin(Floor floor,
                 URL bootstrapURL)
                 throws ServiceException

Throws:

ServiceException

join

void join(Floor floor,
          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:

java.lang.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.

initialJoin

void initialJoin(Floor floor,
                 URL localURL,
                 URL bootstrapURL)
                 throws ServiceException

Throws:

ServiceException

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(java.lang.String res,
            java.io.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:

res - Res, under which the new item is stored.

object - Object for storage in the network.

Throws:

java.lang.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

java.util.Set<java.io.Serializable> retrieve(java.lang.String res)
                                             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:

java.lang.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(java.lang.String res,
            java.io.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:

java.lang.NullPointerException - If key or object is null.

ServiceException - Thrown if deletion failed. The effect of the delete operation is undefined if this exception occurs.