ca.mcgill.cs.postina.scribe
Class ScribeNetworkLayer

java.lang.Object
  ca.mcgill.cs.postina.scribe.ScribeNetworkLayer

All Implemented Interfaces:

PostinaClientListener, PostinaMsgListener, PostinaNetworkLayer

public class ScribeNetworkLayer
extends java.lang.Object
implements PostinaNetworkLayer, PostinaMsgListener, PostinaClientListener

Version:

Oct 22, 2007

Author:

Dominik Zindel

Field Summary

protected static PostinaTopic	BROADCAST_TOPIC The string representing the topic to which all nodes have to subscribe to enable broadcasting.
private java.util.LinkedList<PostinaClientListener>	clientListenersToNetworkLayer
protected rice.environment.Environment	env The environment in Pastry.
private boolean	isConnected The boolean indicates if the node is connected to the network.
private static org.apache.log4j.Logger	logger
private java.util.Collection<PostinaMessage>	messageQueue The message queue where incoming PostinaMessages can be placed.
private java.util.ArrayList<PostinaMsgListener>	msgListenersToNetworkLayer The list of PostinaMsgListeners registered to the application.
protected rice.pastry.transport.TLPastryNode	node The representation of the node in the Pastry network.
protected PostinaID	nodeID The PostinaID uniquely identifying the node.
protected rice.pastry.commonapi.PastryIdFactory	pastryIdFactory The PastryIdFactory is used to create the Id of the TLPastryNode representing this application in the P2P-network.
protected ScribeApplication	scribeApp The ScribeApplication keeps a reference to the ScribeApplication that is, it is the linking point to the P2P-network.
private java.util.Hashtable<java.lang.String,PostinaTopic>	topics The Hashtable topics maps the string representation of topics to the corresponding PostinaTopic.

Constructor Summary

ScribeNetworkLayer()
The default constructor to prepare the application.

Method Summary

void	addClientListener(PostinaClientListener listener) This method registers a listener to changes in the client structure.
void	addMsgListener(PostinaMsgListener listener) Registers a listener to messages being delivered.
void	broadcast(java.io.Serializable content) This method broadcasts a serializable, that is it all clients in the network will receive this message.
void	clientLeft(PostinaID clientID) The method clientLeft is called when a client has left or is supposed to have left the network.
PostinaID	connect() Connects to the P2P-network and initializes the node.
PostinaID	connect(java.net.InetAddress bindAddress, int bindport, java.util.Collection<java.net.InetSocketAddress> bootAddresses) This method is an alternative to the other connect method to specify all configuration parameters as an argument, which is especially important for the localBindAddress.
PostinaID	connect(int bindport, java.util.Collection<java.net.InetSocketAddress> bootAddresses) Connects to the P2P-network and initializes the node.
void	disconnect() Disconnects the node from the P2P-network.
PostinaID	getID() Gets the PostinaID of the current client.
PostinaMessage	getNextMessage() Gets the next message in the queue.
PostinaTopic	getTopic(java.lang.String topicName) Gets the PostinaTopic for a given string name of a topic.
boolean	isConnected() This method checks if the node is connected to the network.
void	publish(PostinaTopic topic, java.io.Serializable content) Publishes a message to a PostinaTopic.
void	publish(java.lang.String topicName, java.io.Serializable content) Publishes a message to the topic identified by a string.
void	receiveMessage(PostinaMessage msg) receiveMessage is called to inform applications about a new PostinaMessage.
void	removeClientListener(PostinaClientListener listener) This method unregisters a listener to changes in the client structure.
void	removeMsgListener(PostinaMsgListener listener) Removes a listener, that is this listener will not be informed about any future messages.
void	send(PostinaID destination, java.io.Serializable content) Sends a message directly to the client identified by the PostinaID.
void	sendReliable(PostinaID destination, java.io.Serializable content)
void	subscribe(java.util.Collection<PostinaTopic> topics) Subscribes the current client to the Collection of PostinaTopics.
void	subscribe(PostinaTopic topic) Subscribes the current client to a PostinaTopic.
void	subscribe(java.lang.String topicName) Subscribes the current client to the topic identified by a string.
void	subscribeOther(java.util.Collection<PostinaTopic> topics, PostinaID client) Subscribes the client specified by the PostinaID to a Collection of PostinaTopics.
void	subscribeOther(PostinaTopic topic, PostinaID client) Subscribes the client specified by the PostinaID to a PostinaTopic.
void	subscribeOther(java.lang.String topicName, PostinaID client) Subscribes the client specified by the PostinaID to the topic identified by the string.
void	unsubscribe(java.util.Collection<PostinaTopic> topics) Unsubscribes the current client from the Collection of PostinaTopics.
void	unsubscribe(PostinaTopic topic) Unsubscribes the current client from the PostinaTopic.
void	unsubscribe(java.lang.String topicName) Unsubscribes the current client from the topic identified by the given string.
void	unsubscribeOther(java.util.Collection<PostinaTopic> topics, PostinaID client) Unsubscribes the client specified by the PostinaID from a Collectionof PostinaTopics.
void	unsubscribeOther(PostinaTopic topic, PostinaID client) Unsubscribes the client specified by the PostinaID to a PostinaTopic.
void	unsubscribeOther(java.lang.String topicName, PostinaID client) Unsubscribes the client specified by the PostinaID from the topic identified by the string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BROADCAST_TOPIC

protected static PostinaTopic BROADCAST_TOPIC

The string representing the topic to which all nodes have to subscribe to enable broadcasting.

logger

private static final org.apache.log4j.Logger logger

clientListenersToNetworkLayer

private final java.util.LinkedList<PostinaClientListener> clientListenersToNetworkLayer

env

protected rice.environment.Environment env

The environment in Pastry. Refer to lesson 0.b of the FreePastry Tutorial for more details: http://www.freepastry.org/FreePastry/tutorial/tut_environment.html#lesson0b

isConnected

private boolean isConnected

The boolean indicates if the node is connected to the network.

messageQueue

private final java.util.Collection<PostinaMessage> messageQueue

The message queue where incoming PostinaMessages can be placed. If there are any listeners registered, the queue is deactivated.

msgListenersToNetworkLayer

private final java.util.ArrayList<PostinaMsgListener> msgListenersToNetworkLayer

The list of PostinaMsgListeners registered to the application.

node

protected rice.pastry.transport.TLPastryNode node

The representation of the node in the Pastry network.

nodeID

protected PostinaID nodeID

The PostinaID uniquely identifying the node.

pastryIdFactory

protected rice.pastry.commonapi.PastryIdFactory pastryIdFactory

The PastryIdFactory is used to create the Id of the TLPastryNode representing this application in the P2P-network.

scribeApp

protected ScribeApplication scribeApp

The ScribeApplication keeps a reference to the ScribeApplication that is, it is the linking point to the P2P-network.

topics

private final java.util.Hashtable<java.lang.String,PostinaTopic> topics

The Hashtable topics maps the string representation of topics to the corresponding PostinaTopic. The first time a topic is used, it is added to the hashtable. On further uses, the topic is taken from the hashtable. This avoids unnecessary creations of PostinaTopics.

Constructor Detail

ScribeNetworkLayer

public ScribeNetworkLayer()

The default constructor to prepare the application.

Method Detail

addClientListener

public void addClientListener(PostinaClientListener listener)

Description copied from interface: PostinaNetworkLayer

This method registers a listener to changes in the client structure. Currently it is used only to inform about clients leaving the network.

Specified by:

addClientListener in interface PostinaNetworkLayer

Parameters:

listener - The listener registering.

addMsgListener

public void addMsgListener(PostinaMsgListener listener)

Description copied from interface: PostinaNetworkLayer

Registers a listener to messages being delivered. This deactivates the message queue as messages will always be delivered to the registered listeners.

Specified by:

addMsgListener in interface PostinaNetworkLayer

Parameters:

listener - The PostinaMsgListener registering as a listener.

broadcast

public void broadcast(java.io.Serializable content)
               throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

This method broadcasts a serializable, that is it all clients in the network will receive this message.

Specified by:

broadcast in interface PostinaNetworkLayer

Parameters:

content - The serializable that has to be broadcasted.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

clientLeft

public void clientLeft(PostinaID clientID)

Description copied from interface: PostinaClientListener

The method clientLeft is called when a client has left or is supposed to have left the network. A client is declared dead when a certain number (specified in the properties) of messages is lost.

Specified by:

clientLeft in interface PostinaClientListener

Parameters:

clientID - The unique identifier of the client that has quit the network.

connect

public PostinaID connect()
                  throws PostinaJoinFailedException,
                         PostinaAlreadyConnectedException

Description copied from interface: PostinaNetworkLayer

Connects to the P2P-network and initializes the node. All parameters (bootstrap-nodes, local bindport, bindaddress) are read from the properties. Passes values to connect(bindport,bootAddresses).

Specified by:

connect in interface PostinaNetworkLayer

Returns:

The newly created PostinaID of the node.

Throws:

PostinaJoinFailedException

PostinaAlreadyConnectedException - If a connected client tries to connect a second time, an exception is thrown.

connect

public PostinaID connect(java.net.InetAddress bindAddress,
                         int bindport,
                         java.util.Collection<java.net.InetSocketAddress> bootAddresses)
                  throws PostinaJoinFailedException,
                         PostinaAlreadyConnectedException

Description copied from interface: PostinaNetworkLayer

This method is an alternative to the other connect method to specify all configuration parameters as an argument, which is especially important for the localBindAddress. This is useful when the application is run on a computer having multiple network interfaces (i.e. multiple network addresses), especially for servers. It is the responsibility of the application using Postina that the chosen interface is visible to other clients, otherwise Postina will not work.

Specified by:

connect in interface PostinaNetworkLayer

Parameters:

bindAddress - The InetAddress to which the node should bind locally.

bindport - The port (integer value) the node should bind to locally.

bootAddresses - A Collection of InetSocketAddresses (i.e. IP:Port) indicating bootstrap nodes

Returns:

The newly created PostinaID of the node.

Throws:

PostinaJoinFailedException - thrown when process of connecting is interrupted unexpectedly.

PostinaAlreadyConnectedException - If a connected client tries to connect a second time, an exception is thrown.

connect

public PostinaID connect(int bindport,
                         java.util.Collection<java.net.InetSocketAddress> bootAddresses)
                  throws PostinaJoinFailedException,
                         PostinaAlreadyConnectedException

Description copied from interface: PostinaNetworkLayer

Connects to the P2P-network and initializes the node. The local bindAddress is read from the properties if exists or requested from the OS otherwise. Note that this may take a while.

Specified by:

connect in interface PostinaNetworkLayer

Parameters:

bindport - The port (integer value) the node should bind to locally.

bootAddresses - A Collection of InetSocketAddresses (i.e. IP:Port) indicating bootstrap nodes

Returns:

The newly created PostinaID of the node.

Throws:

PostinaJoinFailedException - thrown when process of connecting is interrupted unexpectedly.

PostinaAlreadyConnectedException - If a connected client tries to connect a second time, an exception is thrown.

disconnect

public void disconnect()
                throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Disconnects the node from the P2P-network. The node is actually destroyed and all clean up is done.

Specified by:

disconnect in interface PostinaNetworkLayer

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

getID

public PostinaID getID()
                throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Gets the PostinaID of the current client. Once the connection is established, this is the only possibility for an application to get the PostinaID.

Specified by:

getID in interface PostinaNetworkLayer

Returns:

The PostinaID of the current client.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

getNextMessage

public PostinaMessage getNextMessage()
                              throws PostinaNoQueueException,
                                     PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Gets the next message in the queue. If there is a listener registered, the queue is deactivated and an PostinaNoQueueException is thrown.

Specified by:

getNextMessage in interface PostinaNetworkLayer

Returns:

The PostinaMessage representing the message that has been published or sent by another client.

Throws:

PostinaNoQueueException - If there are any listeneres registered to the client, the queue is deactivated and requests to get next message in the queue cause an PostinaNoQueueException exception to be thrown.

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

getTopic

public PostinaTopic getTopic(java.lang.String topicName)
                      throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Gets the PostinaTopic for a given string name of a topic. This is the only way for an application to get an PostinaTopic. The PostinaTopic is used when issuing (un)subscriptions and publications.

Specified by:

getTopic in interface PostinaNetworkLayer

Parameters:

topicName - The string name of the topic.

Returns:

The PostinaTopic representing the given topic.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

isConnected

public boolean isConnected()

Description copied from interface: PostinaNetworkLayer

This method checks if the node is connected to the network.

Specified by:

isConnected in interface PostinaNetworkLayer

Returns:

true if we are connected.

publish

public void publish(PostinaTopic topic,
                    java.io.Serializable content)
             throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Publishes a message to a PostinaTopic. All clients subscribed to this topic will get the message. Note that any Serializable can be published, but subscribers will receive an PostinaMessage containing the submitted Serializable.

Specified by:

publish in interface PostinaNetworkLayer

Parameters:

topic - The PostinaTopic to which the Serializable will be published.

content - The Serializable to be published.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

publish

public void publish(java.lang.String topicName,
                    java.io.Serializable content)
             throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Publishes a message to the topic identified by a string. This is syntactic sugar for publish(PostinaTopic, Serializable).

Specified by:

publish in interface PostinaNetworkLayer

Parameters:

topicName - The string identifying the topic to which the message should be published.

content - The Serializable to be published.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

receiveMessage

public void receiveMessage(PostinaMessage msg)

Description copied from interface: PostinaMsgListener

receiveMessage is called to inform applications about a new PostinaMessage. The same method is used for private (i.e. direct) messages as well as publications.

Specified by:

receiveMessage in interface PostinaMsgListener

Parameters:

msg - The PostinaMessage that has just arrived and has to be passed to the application.

removeClientListener

public void removeClientListener(PostinaClientListener listener)

Description copied from interface: PostinaNetworkLayer

This method unregisters a listener to changes in the client structure.

Specified by:

removeClientListener in interface PostinaNetworkLayer

Parameters:

listener - The listener unregistering.

removeMsgListener

public void removeMsgListener(PostinaMsgListener listener)

Description copied from interface: PostinaNetworkLayer

Removes a listener, that is this listener will not be informed about any future messages. If the last listener is removed, the queue is activated.

Specified by:

removeMsgListener in interface PostinaNetworkLayer

Parameters:

listener - The PostinaMsgListener unregistering.

send

public void send(PostinaID destination,
                 java.io.Serializable content)
          throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Sends a message directly to the client identified by the PostinaID. Only the client specified receives this private message. Note that the message will be delivered as a PostinaMessage.

Specified by:

send in interface PostinaNetworkLayer

Parameters:

destination - The PostinaID uniquely identifying the client which should receive the private message.

content - The Serializable representing the message to be sent.

Throws:

PostinaNotConnectedException

sendReliable

public void sendReliable(PostinaID destination,
                         java.io.Serializable content)
                  throws PostinaNotConnectedException

Specified by:

sendReliable in interface PostinaNetworkLayer

Throws:

PostinaNotConnectedException

subscribe

public void subscribe(java.util.Collection<PostinaTopic> topics)
               throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Subscribes the current client to the Collection of PostinaTopics. This is more efficient than issuing several separate subscriptions.

Specified by:

subscribe in interface PostinaNetworkLayer

Parameters:

topics - The Collection of PostinaTopics to which the current client subscribes.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

subscribe

public void subscribe(PostinaTopic topic)
               throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Subscribes the current client to a PostinaTopic.

Specified by:

subscribe in interface PostinaNetworkLayer

Parameters:

topic - The PostinaTopic to which the client should be subscribed.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

subscribe

public void subscribe(java.lang.String topicName)
               throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Subscribes the current client to the topic identified by a string. This is syntactic sugar for subscribe(PostinaTopic).

Specified by:

subscribe in interface PostinaNetworkLayer

Parameters:

topicName - The string identifying the topic to which the current client subscribes.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

subscribeOther

public void subscribeOther(java.util.Collection<PostinaTopic> topics,
                           PostinaID client)
                    throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Subscribes the client specified by the PostinaID to a Collection of PostinaTopics. This is more efficient than issuing several separate subscriptions.

Specified by:

subscribeOther in interface PostinaNetworkLayer

Parameters:

topics - The Collection of PostinaTopics to which the client should subscribe.

client - The PostinaID identifying the client which should be subscribed to the given PostinaTopics.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

subscribeOther

public void subscribeOther(PostinaTopic topic,
                           PostinaID client)
                    throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Subscribes the client specified by the PostinaID to a PostinaTopic.

Specified by:

subscribeOther in interface PostinaNetworkLayer

Parameters:

topic - The PostinaTopic to which the client should be subscribed.

client - The PostinaID identifying the client which should be subscribed to the given PostinaTopic

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

subscribeOther

public void subscribeOther(java.lang.String topicName,
                           PostinaID client)
                    throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Subscribes the client specified by the PostinaID to the topic identified by the string. This is only syntactic sugar for subscribeOther(PostinaTopic, PostinaID).

Specified by:

subscribeOther in interface PostinaNetworkLayer

Parameters:

topicName - The string identifying the topic to which the given client should subscribe.

client - The PostinaID identifying the client which should be subscribed to the given topic.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

unsubscribe

public void unsubscribe(java.util.Collection<PostinaTopic> topics)
                 throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Unsubscribes the current client from the Collection of PostinaTopics. This is more efficient than issuing several separate subscriptions.

Specified by:

unsubscribe in interface PostinaNetworkLayer

Parameters:

topics - The Collection of PostinaTopics from which the current client should be unsubscribed.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

unsubscribe

public void unsubscribe(PostinaTopic topic)
                 throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Unsubscribes the current client from the PostinaTopic. The client will not get any future publications to this topic. Note that a subscription is not confirmed as there is no positive feedback. However, a PostinaSubscribeFailedException is thrown when the subscription fails.

Specified by:

unsubscribe in interface PostinaNetworkLayer

Parameters:

topic - The PostinaTopic from which the client does have to unsubscribe.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

unsubscribe

public void unsubscribe(java.lang.String topicName)
                 throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Unsubscribes the current client from the topic identified by the given string. This is syntactic sugar for unsubscribe(PostinaTopic).

Specified by:

unsubscribe in interface PostinaNetworkLayer

Parameters:

topicName - The string identifying the topic from which the client should unsubscribe.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

unsubscribeOther

public void unsubscribeOther(java.util.Collection<PostinaTopic> topics,
                             PostinaID client)
                      throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Unsubscribes the client specified by the PostinaID from a Collectionof PostinaTopics. This is more efficient than issuing several separate unsubscriptions.

Specified by:

unsubscribeOther in interface PostinaNetworkLayer

Parameters:

topics - The Collection of PostinaTopics from which the client should be unsubscribed.

client - The PostinaID identifying the client which should be unsubscribed from the given PostinaTopics.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

unsubscribeOther

public void unsubscribeOther(PostinaTopic topic,
                             PostinaID client)
                      throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Unsubscribes the client specified by the PostinaID to a PostinaTopic.

Specified by:

unsubscribeOther in interface PostinaNetworkLayer

Parameters:

topic - The PostinaTopic from which the client should be unsubscribed.

client - The PostinaID identifying the client which should be unsubscribed from the given PostinaTopic

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.

unsubscribeOther

public void unsubscribeOther(java.lang.String topicName,
                             PostinaID client)
                      throws PostinaNotConnectedException

Description copied from interface: PostinaNetworkLayer

Unsubscribes the client specified by the PostinaID from the topic identified by the string. This is only syntactic sugar for unsubscribeOther(PostinaTopic, PostinaID).

Specified by:

unsubscribeOther in interface PostinaNetworkLayer

Parameters:

topicName - The string identifying the topic from which the given client should unsubscribe.

client - The PostinaID identifying the client which should be unsubscribed from the given topic.

Throws:

PostinaNotConnectedException - If the node is not connected to the network, an exception is thrown.