public final class AsyncMulticastSocket extends AbstractAsyncDatagramSocket
AsyncMulticastSocket
uses the selector thread to
process process a DatagramChannel
.
This prevents the calling thread from blocking while sending
data or blocking the socket while processing input. Incoming
DatagramPacket
s and socket closure
events are sent to the registered listener via the
DatagramListener
interface.
This class extends AsyncDatagramSocket
to support
Internet Protocol (IP) multicasting. IP multicasting transmits
IP datagrams to UDP sockets that are
joined
to a group. A multicast group is identified by a single
destination address.
In the case of a channel to an
IPv4
socket, the
underlying operating system supports
RFC 2236: Internet Group Management Protocol, Version 2 (IGMPv2).
It may optionally support source filtering as specified by
RFC 3376: Internet Group Management Protocol, Version 3 (IGMPv3).
For channels to an
IPv6
socket, the
equivalent standards are
RFC 2710: Multicast Listener Discovery (MLD) for IPv6
and
RFC 3810: Multicast Listener Discovery Version 2 (MLDv2) for IPv6.
The
join(InetAddress,NetworkInterface)
method is used to join a group and receive all multicast
datagrams sent to the group. A channel may join several
multicast groups and may join the same group on several
interfaces. Membership is dropped by invoking the
drop
method on the returned
MembershipKey
. If the underlying platform supports
source filtering then the
block
and
unblock
methods can
be used to block or unblock multicast datagrams from
particular source addresses.
The
join(InetAddress,NetworkInterface,InetAddress)
method is used to begin receiving datagrams sent to a group
whose source address matches a given source address. This
method throws UnsupportedOperationException
if the
underlying platform does not support source filtering.
Membership is cumulative and this method may be
invoked again with the same group and interface to allow
receiving datagrams from other source addresses. The method
returns a MembershipKey
that represents membership to
receive datagrams from the given source address. Invoking the
key drop
method drops membership
so that datagrams from the source address can no longer be
received.
ProtocolFamily
that corresponds to the
address type of the multicast groups that the channel will
join. There is no guarantee that a channel to a socket in
one protocol family can join and receive multicast
datagrams when the address of the multicast group
corresponds to another protocol family. For example, it is
implementation-specific if a channel to an
IPv6
socket
can join an
IPv4
multicast group and receive multicast datagrams sent to
the group.
wildcard
address. If the socket is bound to a specific address,
rather than the wildcard address then it is
implementation-specific if multicast datagrams are
received by the socket.
SO_REUSEADDR
option should be enabled prior to
binding
the socket. This is required to allow multiple members of
the group to bind to the same address.
eBus v. 4.5.1 introduced AsyncMulticastSocket.MulticastBuilder
class which
is now the preferred way to create an
AsyncMulticastSocket
instance.
// Assuming this object is a DatagramListener, create a
// multicast, asynchronous datagram socket, and join a
// multicast group on this interface.
NetworkInterface ni = NetworkInterface.getByName("hme0");
InetAddress group = InetAddress.getByName("225.4.5.6");
AsyncMulticastSocket multiSocket = (AsyncMulticastSocket.builder()).listener(this).build();
multiSocket.open(5_000, StandardProtocolFamily.INET, ni);
MembershipKey key = multiSocket.join(group, ni);
Modifier and Type | Class and Description |
---|---|
static class |
AsyncMulticastSocket.MulticastBuilder
Constructs an
AsyncMulticastSocket instance based
on the parameters set via this builder's API. |
AbstractAsyncDatagramSocket.AbstractDatagramBuilder<B extends AbstractAsyncDatagramSocket.AbstractDatagramBuilder<?>>
AsyncChannel.BufferMode, AsyncChannel.ChannelBuilder<B extends AsyncChannel.ChannelBuilder<?>>, AsyncChannel.ConnectState
mBoundFlag, mListener, mOpenFlag, sLogger
LOCALHOST, mChannel, mInputBuffer, mLocalAddress, mOutputBuffer, mOutputLock, mRemoteAddress, mSelectorThread
Modifier and Type | Method and Description |
---|---|
static AsyncMulticastSocket.MulticastBuilder |
builder()
Returns the builder used to open new
AsyncMulticastSocket instances. |
java.nio.channels.MembershipKey |
join(java.net.InetAddress group,
java.net.NetworkInterface nif)
Joins a multicast group to begin receiving all datagrams
sent to the group, returning a membership key.
|
java.nio.channels.MembershipKey |
join(java.net.InetAddress group,
java.net.NetworkInterface nif,
java.net.InetAddress source)
Joins a multicast group to begin receiving all datagrams
sent to the group from a specified address, returning a
membership key.
|
void |
open(int bindPort,
java.net.ProtocolFamily family,
java.net.NetworkInterface netIf)
Opens a multicast UDP socket, bound to the given port
(using a
wildcard
address, protocol family, and network interface. |
void |
open(java.net.SocketAddress bindAddr,
java.net.ProtocolFamily family,
java.net.NetworkInterface netIf)
Opens a multicast UDP socket, bound to the given address,
using the specified protocol family, and network
interface.
|
void |
send(byte[] b,
int off,
int len,
java.net.SocketAddress group)
Sends the given bytes as a single UDP packet directly to
the socket's peer.
|
void |
send(byte[] b,
java.net.SocketAddress group)
Sends the given bytes as a single UDP packet directly to
the socket's peer.
|
void |
send(DatagramBufferWriter writer)
When it is time to send the UDP packet generated by
writer , BufferWriter.fill(ByteBuffer) is
called, passing in the outbound buffer. |
void |
send(int b,
java.net.SocketAddress group)
Sends the given byte in a UDP datagram directly to the
socket's peer.
|
close, closeNow, datagramSocket, doClose, doRead, doSend, isBound, isOpen, opened, write
createSelector, defaultSelectorName, getOption, inputBufferSize, isSelector, localSocketAddress, outputBufferSize, remoteSocketAddress, selectorNames, setOption, supportedOptions
public void send(int b, java.net.SocketAddress group) throws java.io.IOException
send
in class AbstractAsyncDatagramSocket
b
- sends this single byte to the socket's peer.group
- send the datagram to this multicast group.java.lang.IllegalArgumentException
- if group
is null
or is not a multicast
address.java.nio.channels.ClosedChannelException
- if this datagram socket is closed.java.io.IOException
- if the buffer was only partially transmitted or an
underlying I/O error occurs.public void send(byte[] b, java.net.SocketAddress group) throws java.io.IOException
send
in class AbstractAsyncDatagramSocket
b
- fill the UDP packet with this data.group
- send the datagram to this multicast group.java.lang.IllegalArgumentException
- if either b
or group
is null
or
group
is not a multicast address.java.lang.IndexOutOfBoundsException
- if b.length
exceeds the outbound buffer size
(which is set to the maximum allowed datagram size).java.nio.channels.ClosedChannelException
- if this datagram socket is closed.java.io.IOException
- if the buffer was only partially transmitted or an
underlying I/O error occurs.public void send(byte[] b, int off, int len, java.net.SocketAddress group) throws java.io.IOException
send
in class AbstractAsyncDatagramSocket
b
- send len
bytes from this array starting
at off
offset.group
- send the datagram to this multicast group.off
- offset into b
.len
- send this many bytes from b
.java.lang.IllegalArgumentException
- if either b
or group
is null
or
group
is not a multicast address.java.lang.IndexOutOfBoundsException
- if off
or off+len
exceeds b
bounds
or len
exceeds the maximum allowed datagram size.java.nio.channels.ClosedChannelException
- if this datagram socket is closed.java.io.IOException
- if the buffer was only partially transmitted or an
underlying I/O error occurs.public void send(DatagramBufferWriter writer) throws java.io.IOException
writer
, BufferWriter.fill(ByteBuffer)
is
called, passing in the outbound buffer. Upon completion,
the UDP packet is sent to the socket's peer. This method
depends on this datagram socket being connected.send
in class AbstractAsyncDatagramSocket
writer
- fills the outbound buffer with the UDP
packet contents.java.lang.IllegalArgumentException
- if either writer
or group
is null
or group
is not a multicast address.java.nio.channels.ClosedChannelException
- if this datagram socket is closed.java.io.IOException
- if the buffer was only partially transmitted or an
underlying I/O error occurs.public static AsyncMulticastSocket.MulticastBuilder builder()
AsyncMulticastSocket
instances.AsyncMulticastSocket
builder.public void open(int bindPort, java.net.ProtocolFamily family, java.net.NetworkInterface netIf) throws java.io.IOException
wildcard
address, protocol family, and network interface.bindPort
- bind the local end of the datagram socket
to this port using a wildcard address.family
- the datagram socket uses this protocol.netIf
- the multicast network interface. This is the
same network interface passed to
join(InetAddress, NetworkInterface)
.java.lang.UnsupportedOperationException
- if multicast datagram sockets for the given family
is not supported.java.lang.IllegalArgumentException
- if bindPort
is an invalid IP port or netIf
is null
.java.io.IOException
- if this multicast datagram socket is already open or an
I/O error occurs.join(InetAddress, NetworkInterface)
,
join(InetAddress, NetworkInterface, InetAddress)
public void open(java.net.SocketAddress bindAddr, java.net.ProtocolFamily family, java.net.NetworkInterface netIf) throws java.io.IOException
bindAddr
- bind the local end of the datagram socket
to this address.family
- the datagram socket uses this protocol.netIf
- the multicast network interface. This is the
same network interface passed to
join(InetAddress, NetworkInterface)
.java.lang.UnsupportedOperationException
- if multicast datagram sockets for the given family
is not supported.java.lang.IllegalArgumentException
- if bindAddr
, family
, or netIf
is
null
or if netIf
does not support
multicast.java.io.IOException
- if this multicast datagram socket is already open or an
I/O error occurs.join(InetAddress, NetworkInterface)
,
join(InetAddress, NetworkInterface, InetAddress)
public java.nio.channels.MembershipKey join(java.net.InetAddress group, java.net.NetworkInterface nif) throws java.io.IOException
If this channel previously joined the multicast group,
then returns the same membership key used for the previous
join. Otherwise, this channel joins the group, returning
the resulting new membership key. This membership key is
not source-specific
.
A multicast channel may join several groups, including the same group on more than one interface. An implementation may impose a limit on the number of groups that may be joined at one time.
group
- join this multicast group address.nif
- the multicast group network interface.java.lang.IllegalArgumentException
- if the group parameter is not a
multicast
address, or the group parameter is an address type that is
not supported by this channel.java.lang.IllegalStateException
- if the channel already has source-specific membership of
the group on the interface.java.lang.UnsupportedOperationException
- if the socket is not an Internet Protocol socket.java.nio.channels.ClosedChannelException
- if this channel is closed.java.io.IOException
- if an I/O error occurs.java.lang.SecurityException
- if a security manager is set and
checkMulticast
method denies access to the multicast group.public java.nio.channels.MembershipKey join(java.net.InetAddress group, java.net.NetworkInterface nif, java.net.InetAddress source) throws java.io.IOException
If this channel previously joined the multicast group,
then returns the same membership key used for the previous
join. Otherwise, this channel joins the group, returning
the resulting new membership key. This membership key is
not source-specific
.
A multicast channel may join several groups, including the same group on more than one interface. An implementation may impose a limit on the number of groups that may be
group
- join this multicast group address.nif
- the multicast group network interface.source
- accept datagram posted from this address
only.java.lang.IllegalArgumentException
- if the group parameter is not a
multicast
address, the group parameter is an address type that is
not supported by this channel, or the source address
does not have the same address type as the group.java.lang.IllegalStateException
- if the channel already has source-specific membership of
the group on the interface.java.lang.UnsupportedOperationException
- if the socket is not an Internet Protocol socket or
source-filtering is not supported.java.nio.channels.ClosedChannelException
- if this channel is closed.java.io.IOException
- if an I/O error occurs.java.lang.SecurityException
- if a security manager is set and
checkMulticast
method denies access to the multicast group.Copyright © 2001 - 2024. Charles W. Rapp. All rights reserved.