spread
Class SpreadConnection

java.lang.Object
  |
  +--spread.SpreadConnection

public class SpreadConnection

extends java.lang.Object

A SpreadConnection object is used to establish a connection to a spread daemon. To connect to a spread daemon, first create a new SpreadConnection object, and then call connect(InetAddress, int, String, boolean, boolean):

 SpreadConnection connection = new SpreadConnection();
 connection.connect(null, 0, "name", false, false);
 

The only methods that can be called before connect(InetAddress, int, String, boolean, boolean) are the add (add(BasicMessageListener), add(AdvancedMessageListener)) and remove (remove(BasicMessageListener), remove(AdvancedMessageListener)) methods. If any other methods are called, a SpreadException is thrown, except for getPrivateGroup(), which returns null.

To disconnect from the daemon, call disconnect():

 connection.disconnect();
 

To send a message on this connection, call multicast(SpreadMessage):

 connection.multicast(message);
 

To receive a message sent to this connection, call receive():

 SpreadMessage message = connection.receive();
 

Constructor Summary

SpreadConnection()
Initializes a new SpreadConnection object.

Method Summary

void	add(AdvancedMessageListener listener) Adds the AdvancedMessageListener to this connection.
void	add(BasicMessageListener listener) Adds the BasicMessageListener to this connection.
void	connect(java.net.InetAddress address, int port, java.lang.String privateName, boolean priority, boolean groupMembership) Establishes a connection to a spread daemon.
void	disconnect() Disconnects the connection to the daemon.
SpreadGroup	getPrivateGroup() Gets the private group for this connection.
void	multicast(SpreadMessage message) Multicasts a message.
void	multicast(SpreadMessage[] messages) Multicasts an array of messages.
boolean	poll() Returns true if there are any messages waiting on this connection.
SpreadMessage	receive() Receives the next message waiting on this connection.
SpreadMessage[]	receive(int numMessages) Receives numMessages messages on the connection and returns them in an array.
void	remove(AdvancedMessageListener listener) Removes the AdvancedMessageListener from this connection.
void	remove(BasicMessageListener listener) Removes the BasicMessageListener from this connection.

Methods inherited from class java.lang.Object

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

Constructor Detail

SpreadConnection

public SpreadConnection()

Initializes a new SpreadConnection object. To connect to a daemon with this object, use connect(InetAddress, int, String, boolean, boolean).

See Also:

connect(InetAddress, int, String, boolean, boolean)

Method Detail

connect

public void connect(java.net.InetAddress address,
                    int port,
                    java.lang.String privateName,
                    boolean priority,
                    boolean groupMembership)
             throws SpreadException

Establishes a connection to a spread daemon. Groups can be joined, and messages can be sent or received once the connection has been established.

Parameters:

address - the daemon's address, or null to connect to the localhost

port - the daemon's port, or 0 for the default port (4803)

privateName - the private name to use for this connection

priority - if true, this is a priority connection

groupMembership - if true, membership messages will be received on this connection

Throws:

SpreadException - if the connection cannot be established

See Also:

disconnect()

disconnect

public void disconnect()
                throws SpreadException

Disconnects the connection to the daemon. Nothing else should be done with this connection after disconnecting it.

Throws:

SpreadException - if there is no connection or there is an error disconnecting

See Also:

connect(InetAddress, int, String, boolean, boolean)

getPrivateGroup

public SpreadGroup getPrivateGroup()

Gets the private group for this connection.

Returns:

the SpreadGroup representing this connection's private group, or null if there is no connection

receive

public SpreadMessage receive()
                      throws SpreadException

Receives the next message waiting on this connection. If there are no messages waiting, the call will block until a message is ready to be received.

Returns:

the message that has just been received

Throws:

SpreadException - if there is no connection or there is any error reading a new message

receive

public SpreadMessage[] receive(int numMessages)
                        throws SpreadException

Receives numMessages messages on the connection and returns them in an array. If there are not numMessages messages waiting, the call will block until there are enough messages available.

Parameters:

numMessages - the number of messages to receive

Returns:

an array of messages

Throws:

SpreadException - if there is no connection or if there is any error reading the messages

poll

public boolean poll()
             throws SpreadException

Returns true if there are any messages waiting on this connection.

Returns:

true if there is at least one message that can be received

Throws:

SpreadException - if there is no connection or if there is an error checking for messages

add

public void add(BasicMessageListener listener)

Adds the BasicMessageListener to this connection. If there are no other listeners, this call will start a thread to listen for new messages. From the time this function is called until this listener is removed, BasicMessageListener.messageReceived(SpreadMessage) will be called every time a message is received.

Parameters:

listener - a BasicMessageListener to add to this connection

See Also:

remove(BasicMessageListener)

add

public void add(AdvancedMessageListener listener)

Adds the AdvancedMessageListener to this connection. If there are no other listeners, this call will start a thread to listen for new messages. From the time this function is called until this listener is removed, AdvancedMessageListener.regularMessageReceived(SpreadMessage) will be called every time a regular message is received, and AdvancedMessageListener.membershipMessageReceived(SpreadMessage) will be called every time a membership message is received.

Parameters:

listener - an AdvancedMessageListener to add to this connection

See Also:

remove(AdvancedMessageListener)

remove

public void remove(BasicMessageListener listener)

Removes the BasicMessageListener from this connection. If this is the only listener on this connection, the listener thread will be stopped.

Parameters:

listener - the listener to remove

See Also:

add(BasicMessageListener)

remove

public void remove(AdvancedMessageListener listener)

Removes the AdvancedMessageListener from this connection. If this is the only listener on this connection, the listener thread will be stopped.

Parameters:

listener - the listener to remove

See Also:

add(AdvancedMessageListener)

multicast

public void multicast(SpreadMessage message)
               throws SpreadException

Multicasts a message. The message will be sent to all the groups specified in the message.

Parameters:

message - the message to multicast

Throws:

SpreadException - if there is no connection or if there is any error sending the message

multicast

public void multicast(SpreadMessage[] messages)
               throws SpreadException

Multicasts an array of messages. Each message will be sent to all the groups specified in the message.

Parameters:

messages - the messages to multicast

Throws:

SpreadException - if there is no connection or if there is any error sending the messages