/***************************************************************************
* *
* AsynChord.java *
* ------------------- *
* date : 15.10.2005 *
* copyright : (C) 2004-2008 Distributed and *
* Mobile Systems Group *
* Lehrstuhl fuer Praktische Informatik *
* Universitaet Bamberg *
* http://www.uni-bamberg.de/pi/ *
* email : sven.kaffille@uni-bamberg.de *
* karsten.loesing@uni-bamberg.de *
* *
* *
***************************************************************************/
/***************************************************************************
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
* A copy of the license can be found in the license.txt file supplied *
* with this software or at: http://www.gnu.org/copyleft/gpl.html *
* *
***************************************************************************/
package de.uniba.wiai.lspi.chord.service;
import java.io.Serializable;
import de.uniba.wiai.lspi.chord.data.ID;
import de.uniba.wiai.lspi.chord.data.URL;
/**
* <p>
* Interface to Chord distributed hash table for asynchronous method
* invocations.
* </p>
* <p>
* The methods
* <ul>
* <li>{@link #insert(Key, Serializable, ChordCallback)}</li>
* <li>{@link #remove(Key, Serializable, ChordCallback)}</li>
* <li>{@link #retrieve(Key, ChordCallback)}</li>
* </ul>
* perform the requested operation (insert, remove, or retrieve) and delegate
* the invocation result to the provided {@link ChordCallback callback} object.
* </p>
* <p>
* The methods
* <ul>
* <li>{@link #insertAsync(Key, Serializable)}</li>
* <li>{@link #removeAsync(Key, Serializable)}</li>
* <li>{@link #retrieveAsync(Key)}</li>
* </ul>
* 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 {@link ChordFuture}.
* </p>
*
* @author sven
* @version 1.0.5
*/
public interface AsynChord {
/**
* Returns the {@link URL} of the local node; is <code>null</code> if no network has been
* created or joined.
*
* @return {@link URL} of local node.
*/
public abstract URL getURL();
/**
* Sets the {@link URL} of the local node to the given value; only available
* before creating or joining a network.
*
* @param nodeURL
* New {@link URL} of local node.
* @throws NullPointerException
* If given URL reference has value <code>null</code>.
* @throws IllegalStateException
* If network has already been created or joined.
*/
public abstract void setURL(URL nodeURL) throws IllegalStateException;
/**
* Returns the {@link ID} of the local node; is <code>null</code> if no network has been
* created or joined.
*
* @return {@link ID} of local node.
*/
public abstract ID getID();
/**
* Sets the {@link ID} of the local node to the given value; only available
* before creating or joining a network.
*
* @param nodeID
* New {@link ID} of local node.
* @throws NullPointerException
* If given ID reference has value <code>null</code>.
* @throws IllegalStateException
* If network has already been created or joined.
*/
public abstract void setID(ID nodeID) throws IllegalStateException;
/**
* 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 {@link #setURL}.
* 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.
*/
public abstract void create() 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 {@link URL}.
*
* @param localURL
* {@link URL} on which this node accepts incoming requests from
* other chord nodes. The {@link ID} of this node is generated by
* applying a hash function on the node {@link URL}.
* @throws NullPointerException
* If <code>localURL</code> is <code>null</code>.
* @throws ServiceException
* Is thrown if creating the local chord node fails, e.g. due to
* unability of creating the endpoint for incoming messages.
*/
public abstract void create(URL localURL) throws ServiceException;
/**
* Creates a new chord network which is not connected to any other node.
*
* @param localURL
* {@link URL} on which this node accepts incoming requests from
* other chord nodes.
* @param localID
* {@link ID} of this node.
* @throws NullPointerException
* If <code>localURL</code> or <code>localID</code> is
* <code>null</code>.
* @throws ServiceException
* Is thrown if creating the local chord node fails, e.g. due to
* unability of creating the endpoint for incoming messages.
*/
public abstract void create(URL localURL, ID localID)
throws ServiceException;
/**
* Joins an existing chord network and announces its presence to the other
* nodes. Assumes that at least the node {@link URL} has been set before by
* {@link #setURL}. If no {@link ID} has been set before, it is generated
* by applying a hash function on the node {@link URL}.
*
* @param bootstrapURL
* {@link URL} of one existing node which is used as bootstrap
* node.
* @throws NullPointerException
* If <code>bootstrapURL</code> is <code>null</code>.
* @throws 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.
*/
public abstract void join(URL bootstrapURL) throws ServiceException;
/**
* Joins an existing chord network and announces its presence to the other
* nodes. The node {@link ID} is generated by applying a hash function on
* the node {@link URL}.
*
* @param localURL
* The local node is made available under this {@link URL}.
* @param bootstrapURL
* {@link URL} of one existing node which is used as bootstrap
* node.
* @throws NullPointerException
* If <code>localURL</code> or <code>bootstrapURL</code> is
* <code>null</code>.
* @throws 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.
*/
public abstract void join(URL localURL, URL bootstrapURL)
throws ServiceException;
/**
* Joins an existing chord network and announces its presence to the other
* nodes.
*
* @param localURL
* The local node is made available under this {@link URL}.
* @param localID
* {@link ID} of this node.
* @param bootstrapURL
* {@link URL} of one existing node which is used as bootstrap
* node.
* @throws NullPointerException
* If <code>localURL</code>, <code>localID</code>, or
* <code>bootstrapURL</code> is <code>null</code>.
* @throws 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.
*/
public abstract void join(URL localURL, ID localID, URL bootstrapURL)
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.
*/
public abstract void leave() throws ServiceException;
/**
* Asynchronous method to retrieve the entries associated with
* <code>key</code>. Implementations of this method must return
* immediately and the result of the retrieval must be passed to the
* provided <code>callback</code> instance.
*
* @param key
* The key for which the associated entries should be retrieved.
*
* @param callback
* The {@link ChordCallback} to which to pass the retrieval
* result.
*/
public void retrieve(Key key, ChordCallback callback);
/**
* Asynchronous method to insert <code>entry</code> under the provided
* <code>key</code>. Implementations of this method must return
* immediately and the completion of the insertion must be reported to the
* provided <code>callback</code> instance.
*
* @param key
* The {@link Key} to associate with <code>entry</code>
* @param entry
* The entry to insert.
* @param callback
* The {@link ChordCallback} to which to pass the retrieval
* result.
*/
public void insert(Key key, Serializable entry, ChordCallback callback);
/**
* Asynchronous method to remove <code>entry</code> under the provided
* <code>key</code>. Implementations of this method must return
* immediately and the completion of the removal must be reported to the
* provided <code>callback</code> instance.
*
* @param key
* The {@link Key} associated with <code>entry</code>
* @param entry
* The entry to insert.
* @param callback
* The {@link ChordCallback} to which to pass the retrieval
* result.
*/
public void remove(Key key, Serializable entry, ChordCallback callback);
/**
* Asynchronous method to retrieve the entries associated with
* <code>key</code>. Implementations of this method must return
* immediately and return an implementation of {@link ChordRetrievalFuture},
* which can be used later on to retrieve the retrieved results.
*
* @param key
* The {@link Key} for that the associated entries should be
* retrieved.
* @return {@link ChordRetrievalFuture} that represents the result of the
* retrieve method.
*/
public ChordRetrievalFuture retrieveAsync(Key key);
/**
* Asynchronous method to insert <code>entry</code> with <code>key</code>.
* Implementations of this method must return immediately and return an
* implementation of {@link ChordFuture}, which can be used later on to
* determine completion of the insertion.
*
* @param key
* The {@link Key} with which <code>entry</code> will be
* associated.
* @param entry
* The entry to insert.
* @return {@link ChordFuture}, which can be used later on to determine
* completion of the insertion.
*/
public ChordFuture insertAsync(Key key, Serializable entry);
/**
* Asynchronous method to remove <code>entry</code> with <code>key</code>.
* Implementations of this method must return immediately and return an
* implementation of {@link ChordFuture}, which can be used later on to
* determine completion of the removal.
*
* @param key
* The {@link Key} with which <code>entry</code> is associated.
* @param entry
* The entry to remove.
* @return {@link ChordFuture}, which can be used later on to determine
* completion of the removal.
*/
public ChordFuture removeAsync(Key key, Serializable entry);
}