ca.mcgill.cs.postina
Interface PostinaNetworkLayer

All Known Implementing Classes:

ScribeNetworkLayer

public interface PostinaNetworkLayer

The main interface representing the functionalities of Postina.

Version:

Oct 22, 2007

Author:

Dominik Zindel

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

Method Detail

addClientListener

void addClientListener(PostinaClientListener listener)

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

Parameters:

listener - The listener registering.

addMsgListener

void addMsgListener(PostinaMsgListener listener)

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

Parameters:

listener - The PostinaMsgListener registering as a listener.

broadcast

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

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

Parameters:

content - The serializable that has to be broadcasted.

Throws:

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

connect

PostinaID connect()
                  throws PostinaJoinFailedException,
                         PostinaAlreadyConnectedException

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

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

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

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.

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

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

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.

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

void disconnect()
                throws PostinaNotConnectedException

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

Throws:

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

getID

PostinaID getID()
                throws PostinaNotConnectedException

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

Returns:

The PostinaID of the current client.

Throws:

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

getNextMessage

PostinaMessage getNextMessage()
                              throws PostinaNoQueueException,
                                     PostinaNotConnectedException

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

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

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

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.

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

boolean isConnected()

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

Returns:

true if we are connected.

publish

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

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.

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

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

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

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.

removeClientListener

void removeClientListener(PostinaClientListener listener)

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

Parameters:

listener - The listener unregistering.

removeMsgListener

void removeMsgListener(PostinaMsgListener listener)

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.

Parameters:

listener - The PostinaMsgListener unregistering.

send

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

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.

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

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

Throws:

PostinaNotConnectedException

subscribe

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

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

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

void subscribe(PostinaTopic topic)
               throws PostinaNotConnectedException

Subscribes the current client to a PostinaTopic.

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

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

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

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

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

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

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

void subscribeOther(PostinaTopic topic,
                    PostinaID client)
                    throws PostinaNotConnectedException

Subscribes the client specified by the PostinaID to a PostinaTopic.

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

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

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

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

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

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

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

void unsubscribe(PostinaTopic topic)
                 throws PostinaNotConnectedException

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.

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

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

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

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

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

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

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

void unsubscribeOther(PostinaTopic topic,
                      PostinaID client)
                      throws PostinaNotConnectedException

Unsubscribes the client specified by the PostinaID to a PostinaTopic.

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

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

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

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.