com.sun.sgs.nio.channels
Class MembershipKey

java.lang.Object
  com.sun.sgs.nio.channels.MembershipKey

public abstract class MembershipKey
extends Object

A token representing the membership of an Internet Protocol (IP) multicast group.

A membership key may represent a membership to receive all datagrams sent to the group, or it may be source-specific, meaning that it represents a membership that receives only datagrams from a specific source address. Whether or not a membership key is source-specific may be determined by invoking its getSourceAddress() method.

A membership key is valid upon creation and remains valid until the membership is dropped by invoking the drop() method, or the channel is closed. The validity of the membership key may be tested by invoking its isValid() method.

Where a membership key is not source specific and the underlying operation system supports source filtering, then the block(java.net.InetAddress) and unblock(java.net.InetAddress) methods can be used to block or unblock multicast packets from particular source addresses.

See Also:

MulticastChannel

Method Summary

abstract MembershipKey	block(InetAddress source) Block multicast packets from the given source address.
abstract void	drop() Drop membership.
abstract MulticastChannel	getChannel() Returns the channel for which this membership key was created.
abstract InetAddress	getGroup() Returns the multicast group for which this membership key was created.
abstract NetworkInterface	getNetworkInterface() Returns the network interface for which this membership key was created.
abstract InetAddress	getSourceAddress() Returns the source address if this membership key is source specific, or null if this membership is not source specific.
abstract boolean	isValid() Tells whether or not this membership is valid.
abstract MembershipKey	unblock(InetAddress source) Unblock multicast packets from the given source address that was previously blocked using the block(java.net.InetAddress) method.

Methods inherited from class java.lang.Object

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

Method Detail

isValid

public abstract boolean isValid()

Tells whether or not this membership is valid.

A multicast group membership is valid upon creation and remains valid until the membership is dropped by invoking the drop() method, or the channel is closed.

Returns:

true if this membership key is valid, false otherwise

drop

public abstract void drop()
                   throws IOException

Drop membership.

If the membership key represents a membership to receive all datagrams then the membership is dropped and the channel will no longer receive any datagrams sent to the group. If the membership key is source specific then the channel will no longer receive datagrams sent to the group from that source address.

After membership is dropped it may still be possible to receive datagams sent to the group. This can arise when datagrams are waiting to be received in the socket's receive buffer.

Upon return, this membership object will be invalid. If the multicast group membership is already invalid then invoking this method has no effect. Once a multicast group membership is invalid, it remains invalid forever.

Throws:

IOException - if an I/O error occurs

block

public abstract MembershipKey block(InetAddress source)
                             throws IOException

Block multicast packets from the given source address.

If this membership key is not source-specific, and the underlying operating system supports source filtering, then this method blocks multicast packets from the given source address. If the given source address is already blocked then this method has no effect. After a source address is blocked it may still be possible to receive datagams from that source. This can arise when datagrams are waiting to be received in the socket's receive buffer.

Parameters:

source - the source address to block

Returns:

this membership key

Throws:

IllegalArgumentException - if the source parameter is not a unicast address or is not the same address type as the multicast group

IllegalStateException - i this membership key is source specific or is no longer valid

UnsupportedOperationException - if the underlying operating system does not support source filtering

IOException - if an I/O error occurs

unblock

public abstract MembershipKey unblock(InetAddress source)
                               throws IOException

Unblock multicast packets from the given source address that was previously blocked using the block(java.net.InetAddress) method.

Parameters:

source - a list of source addresses to unblock

Returns:

this membership key

Throws:

IllegalStateException - if the given source address is not currently blocked or the membership key is no longer valid

IOException - if an I/O error occurs

getChannel

public abstract MulticastChannel getChannel()

Returns the channel for which this membership key was created. This method will continue to return the channel even after the membership is dropped.

Returns:

the channel

getGroup

public abstract InetAddress getGroup()

Returns the multicast group for which this membership key was created. This method will continue to return the group even after the membership is dropped.

Returns:

the multicast group

getNetworkInterface

public abstract NetworkInterface getNetworkInterface()

Returns the network interface for which this membership key was created. This method will continue to return the network interface even after the membership is dropped or the channel is closed.

Returns:

the network interface

getSourceAddress

public abstract InetAddress getSourceAddress()

Returns the source address if this membership key is source specific, or null if this membership is not source specific.

Returns:

the source address if this membership key is source specific, otherwise null