/***************************************************************************
* *
* Chord.java *
* ------------------- *
* date : 15.08.2004 *
* 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 java.util.Set;
import de.uniba.wiai.lspi.chord.data.ID;
import de.uniba.wiai.lspi.chord.data.URL;
/**
* 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).
*
* @author Sven Kaffille, Karsten Loesing
* @version 1.0.5
*/
public interface Chord {
/**
* 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;
/**
* 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.
*
* @param key
* Key, under which the new item is stored.
* @param object
* Object for storage in the network.
* @throws NullPointerException
* If key or object is <code>null</code>.
* @throws ServiceException
* Thrown if insertion failed. The effect of the insertion
* operation is undefined if this exception occurs.
*/
public abstract void insert(Key key, Serializable object)
throws ServiceException;
/**
* Attempts to find all objects with given key.
*
* @param key
* Key for which objects shall be retrieved.
* @return All objects stored under given key. Set of {@link Serializable}
* @throws NullPointerException
* If <code>key</code> is <code>null</code>.
* @throws ServiceException
* Is thrown if retrieval failed, e.g. due to a communication
* failure. However, the network is left in a stable state.
*/
public abstract Set<Serializable> retrieve(Key key) throws ServiceException;
/**
* Removes the given object stored under given key from the network.
*
* @param key
* Key under which the object currently is stored.
* @param object
* Object to remove from the network.
* @throws NullPointerException
* If key or object is <code>null</code>.
* @throws ServiceException
* Thrown if deletion failed. The effect of the delete operation
* is undefined if this exception occurs.
*/
public abstract void remove(Key key, Serializable object)
throws ServiceException;
}