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

All Known Implementing Classes:

ChordImpl

public interface AsynChord

Interface to Chord distributed hash table for asynchronous method invocations.

The methods

• #insert(Key, Serializable, ChordCallback)
• #remove(Key, Serializable, ChordCallback)
• #retrieve(Key, ChordCallback)

perform the requested operation (insert, remove, or retrieve) and delegate the invocation result to the provided callback object.

The methods

• #insertAsync(Key, Serializable)
• #removeAsync(Key, Serializable)
• #retrieveAsync(Key)

perform the requested operation (insert, remove, or retrieve) and the result can be obtained or the completion of the method can be detected with help of the returned instance of ChordFuture.

Version:

1.0.5 modified, 0.99b

Author:

sven, bojanm

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 entry, ChordCallback callback) Asynchronous method to insert entry under the provided key.
ChordFuture	insertAsync(java.lang.String res, java.io.Serializable entry) Asynchronous method to insert entry with 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 entry, ChordCallback callback) Asynchronous method to remove entry under the provided key.
ChordFuture	removeAsync(java.lang.String res, java.io.Serializable entry) Asynchronous method to remove entry with key.
void	retrieve(java.lang.String res, ChordCallback callback) Asynchronous method to retrieve the entries associated with key.
ChordRetrievalFuture	retrieveAsync(java.lang.String res) Asynchronous method to retrieve the entries associated with 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.

retrieve

void retrieve(java.lang.String res,
              ChordCallback callback)

Asynchronous method to retrieve the entries associated with key. Implementations of this method must return immediately and the result of the retrieval must be passed to the provided callback instance.

Parameters:

key - The key for which the associated entries should be retrieved.

callback - The ChordCallback to which to pass the retrieval result.

insert

void insert(java.lang.String res,
            java.io.Serializable entry,
            ChordCallback callback)

Asynchronous method to insert entry under the provided key. Implementations of this method must return immediately and the completion of the insertion must be reported to the provided callback instance.

Parameters:

key - The Key to associate with entry

entry - The entry to insert.

callback - The ChordCallback to which to pass the retrieval result.

remove

void remove(java.lang.String res,
            java.io.Serializable entry,
            ChordCallback callback)

Asynchronous method to remove entry under the provided key. Implementations of this method must return immediately and the completion of the removal must be reported to the provided callback instance.

Parameters:

key - The Key associated with entry

entry - The entry to insert.

callback - The ChordCallback to which to pass the retrieval result.

retrieveAsync

ChordRetrievalFuture retrieveAsync(java.lang.String res)

Asynchronous method to retrieve the entries associated with key. Implementations of this method must return immediately and return an implementation of ChordRetrievalFuture, which can be used later on to retrieve the retrieved results.

Parameters:

key - The Key for that the associated entries should be retrieved.

Returns:

ChordRetrievalFuture that represents the result of the retrieve method.

insertAsync

ChordFuture insertAsync(java.lang.String res,
                        java.io.Serializable entry)

Asynchronous method to insert entry with key. Implementations of this method must return immediately and return an implementation of ChordFuture, which can be used later on to determine completion of the insertion.

Parameters:

key - The Key with which entry will be associated.

entry - The entry to insert.

Returns:

ChordFuture, which can be used later on to determine completion of the insertion.

removeAsync

ChordFuture removeAsync(java.lang.String res,
                        java.io.Serializable entry)

Asynchronous method to remove entry with key. Implementations of this method must return immediately and return an implementation of ChordFuture, which can be used later on to determine completion of the removal.

Parameters:

key - The Key with which entry is associated.

entry - The entry to remove.

Returns:

ChordFuture, which can be used later on to determine completion of the removal.