net.sf.neem
Class MulticastChannel

java.lang.Object
  net.sf.neem.MulticastChannel

All Implemented Interfaces:

java.io.Closeable, java.nio.channels.Channel, java.nio.channels.InterruptibleChannel, java.nio.channels.ReadableByteChannel, java.nio.channels.WritableByteChannel

public class MulticastChannel
extends java.lang.Object
implements java.nio.channels.InterruptibleChannel, java.nio.channels.ReadableByteChannel, java.nio.channels.WritableByteChannel

Channel interface to a NeEM epidemic multicast group. This interface is thread and aliasing safe, and thus can be used by multiple threads and all buffers used as parameters can immediatly be reused by the application.

After creating the channel, it must be connected to at least one previously known peer in the desired group. Such peer must be determined by the application. A good strategy is to maintain a list of known peers and connect to them all to cope with transient failures.

Constructor Summary

MulticastChannel(java.net.InetSocketAddress local)
Creates a new instance of a multicast channel.

MulticastChannel(java.net.InetSocketAddress local, java.net.InetSocketAddress pub, java.util.UUID id)
Creates a new instance of a multicast channel.

Method Summary

void	close() Close the channel.
void	connect(java.net.InetSocketAddress peer) Add an address of a remote peer.
java.net.InetSocketAddress	getLocalSocketAddress() Get the address of the local socket.
boolean	getLoopbackMode() Query local loopback mode status.
java.net.InetSocketAddress	getPeerSocketAddress() Get the address that is being advertised to peers.
ProtocolMBean	getProtocolMBean() Obtain a reference to a JMX compliant management bean.
boolean	getTruncateMode() Query local message truncate mode.
boolean	isOpen() True if the channel has not yet been (explicitly or implicitly) closed.
int	read(java.nio.ByteBuffer msg) Receive a message.
void	setLoopbackMode(boolean mode) Disable/enable local loopback mode.
void	setTruncateMode(boolean mode) Disable/enable local message truncate mode.
int	write(java.nio.ByteBuffer msg) Send a message to members of the group.

Methods inherited from class java.lang.Object

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

Constructor Detail

MulticastChannel

public MulticastChannel(java.net.InetSocketAddress local)
                 throws java.io.IOException

Creates a new instance of a multicast channel. Note that the bind address will be used to bind both listening and connecting sockets. The bind port will be used only for the listening socket.

Parameters:

local - the local address to bind to

Throws:

java.io.IOException

MulticastChannel

public MulticastChannel(java.net.InetSocketAddress local,
                        java.net.InetSocketAddress pub,
                        java.util.UUID id)
                 throws java.io.IOException

Creates a new instance of a multicast channel.

Parameters:

local - the local address to bind to

pub - public address to advertise to peers

Throws:

java.io.IOException

Method Detail

isOpen

public boolean isOpen()

True if the channel has not yet been (explicitly or implicitly) closed.

Specified by:

isOpen in interface java.nio.channels.Channel

Returns:

false if the channel has been closed

close

public void close()

Close the channel. This will wakeup all threads blocked on read(ByteBuffer).

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.nio.channels.Channel

Specified by:

close in interface java.nio.channels.InterruptibleChannel

write

public int write(java.nio.ByteBuffer msg)
          throws java.nio.channels.ClosedChannelException

Send a message to members of the group. On return, there are no remaining bytes in the supplied buffer.

Specified by:

write in interface java.nio.channels.WritableByteChannel

Parameters:

msg - bytes to be sent

Returns:

the number of bytes written

Throws:

java.nio.channels.ClosedChannelException - the channel has already been closed

read

public int read(java.nio.ByteBuffer msg)
         throws java.nio.channels.ClosedChannelException,
                java.nio.channels.ClosedByInterruptException,
                java.nio.channels.AsynchronousCloseException,
                BufferTooSmallException

Receive a message. If the truncate mode is not set (the default), the buffer should be large enough to handle incoming messages. Otherwise, a BufferTooSmallException will be thrown and the message will be left untouched in the queue. If the truncate mode is set, the remainder of the message will be silently discarded.

Specified by:

read in interface java.nio.channels.ReadableByteChannel

Parameters:

msg - a byte buffer to be filled with the received message

Returns:

the number of bytes read

Throws:

java.nio.channels.ClosedChannelException - the channel was previously closed

java.nio.channels.ClosedByInterruptException - the waiting thread has been interrupted

java.nio.channels.AsynchronousCloseException - the channel has been closed while waiting

BufferTooSmallException - the buffer is too small for the next incoming message and the channel is configured to not truncate messages

getPeerSocketAddress

public java.net.InetSocketAddress getPeerSocketAddress()

Get the address that is being advertised to peers. This might not be the real socket address that was bound.

Returns:

the address being advertised to peers

getLocalSocketAddress

public java.net.InetSocketAddress getLocalSocketAddress()

Get the address of the local socket. This might not be the address that is being advertised to peers.

Returns:

the local socket address

connect

public void connect(java.net.InetSocketAddress peer)

Add an address of a remote peer. This is used to add the address of peers that act as rendezvous points when joining the group. Any peer can be used, as the protocol is fully symmetrical. This can be called a number of times to more quickly build a local neighborhood.

Parameters:

peer - The address of the peer.

getLoopbackMode

public boolean getLoopbackMode()

Query local loopback mode status. When false, messages multicast locally will be delivered back to the sender.

Returns:

if true then loopback mode is disabled

setLoopbackMode

public void setLoopbackMode(boolean mode)

Disable/enable local loopback mode. When false, messages multicast locally will be delivered back to the sender.

Parameters:

mode - true to disable loopback mode

setTruncateMode

public void setTruncateMode(boolean mode)

Disable/enable local message truncate mode. When false and the buffer supplied to read is too small, an exception is thrown and the message is left untouched. When true, the remainder of the datagram is discarded.

Parameters:

mode - true to enable truncate mode

getTruncateMode

public boolean getTruncateMode()

Query local message truncate mode. When false and the buffer supplied to read is too small, an exception is thrown and the message is left untouched. When true, the remainder of the datagram is discarded.

Returns:

true if truncate mode is enabled

getProtocolMBean

public ProtocolMBean getProtocolMBean()

Obtain a reference to a JMX compliant management bean. This can be used to fine tune several protocol parameters.

Returns:

the management bean