public interface UDPMulticastConnection extends UDPDatagramConnection
The protocol is transaction oriented, and
delivery and duplicate protection are not guaranteed. The
UDPMulticastConnection
can join a multicast group to enable
receiveing of all datagrams that are sent to that group.
The connection is either explicitly joined by calling the join
method
or implicitly joined with a special form of the URL connect string as described
below.
Calling leave
or closing the connection leaves the
multicast host group.
A multicast host group is specified by a class D IPv4 address or a multicast IPv6 address as defined in RFC4291 and by a port number. Class D IPv4 addresses are in the range 224.0.0.0 to 239.255.255.255, inclusive. The address 224.0.0.0 is reserved and should not be used. IPv6 multicast addresses use the address block with the prefix ff00::/8.
A UDPMulticastConnection
is returned from
Connector.open()
in response to a request to open a
multicast://
URL connection string. If the connection string
omits the port
field in the URL string, then the system will
allocate an available port. The multicast address and the port can be
discovered using the accessor methods within the
UDPMulticastConnection
interface. The mode
parameter of
Connector.open
is not used.
The time-to-live (TTL) can be set for the connection with
setTimeToLive(int)
. The initial value is 1.
The local loopback of multicast datagrams sent by this connection can be
disabled with setDisableLoopback(boolean)
. The initial value is
false
as defined by RFC 1112.
MulticastConnection
depends on the level of support from the underlying implementation. RFC 1112
describes 3 levels of Multicast conformance:
ConnectionNotFoundException
.join(java.lang.String)
MUST throw
UnsupportedOperationException.
The syntax for the UDPMulticastConnection
URL is provided by the
BNF rule
multicast_connection
. The ipaddr
MUST be a well
formatted IPv4 or an IPv6 multicast address surrounded by square brackets
("[", "]").
?join=<host>
is
appended to the connect string as described in the BNF.
If this suffix is used on Level 1 multicast implementations, an
IllegalArgumentException
is thrown.
If the URI does not conform to this syntax or if the address is not a valid multicast address,
an IllegalArgumentException
is thrown.
Note that the syntax described for the UDPMulticastConnection
URL connection
string and the "multicast://" prefix is only used for the Connecor.open
method.
To assign a destination address to a Datagram
to be sent, the
Datagram.setAddress()
method with an address in the form
datagram://<ipaddr>:<port>
must be used.
Note that multicast datagrams can be sent to any multicast address or port,
providing the security policy allows it.
This connection inherits the connection options from UDPDatagramConnection
.
Examples of multicast host group URLs:
multicast://224.2.3.4:1234
multicast://[FF0X::101]:4444
multicast://sip.mcast.net:4711
multicast://:4711?join=224.4.3.2
Modifier and Type | Method and Description |
---|---|
int |
getTimeToLive()
Get the default time-to-live for multicast packets sent on this
UDPMulticastConnection . |
boolean |
isDisableLoopback()
Get the setting for local loopback of multicast datagrams.
|
boolean |
isJoinSupported()
Query whether the multicast stack supports joining a multicast group.
|
void |
join(java.lang.String group)
Join the multicast host group specified by
group . |
void |
leave(java.lang.String group)
Leave a multicast host group specified by
group . |
void |
receive(Datagram dgram)
Receive a multicast datagram.
|
void |
send(Datagram dgram)
Send a datagram to a multicast group.
|
void |
setDisableLoopback(boolean disable)
Disable/Enable local loopback of multicast datagrams.
|
void |
setTimeToLive(int ttl)
Set the default time-to-live (TTL) for multicast packets sent on this
UDPMulticastConnection in order to control the scope of the
multicasts. |
getLocalAddress, getLocalPort
getAccessPoints, getMaximumLength, getNominalLength, newDatagram, newDatagram, newDatagram, newDatagram
close
int getTimeToLive() throws java.io.IOException
UDPMulticastConnection
.java.io.IOException
- if an I/O exception occurs while getting the default
time-to-live valuesetTimeToLive(int)
boolean isDisableLoopback() throws java.io.IOException
java.io.IOException
- if an error occurs while getting the valuesetDisableLoopback(boolean)
boolean isJoinSupported()
This method returns:
void join(java.lang.String group) throws java.io.IOException
group
.
If this group was already joined, this method returns successfully.
If the platform only supports Level 1 multicast as defined in RFC 1112 this method throws an UnsupportedOperationException.
On platforms, where a UDPMulticastConnection
can simultaneously
join more than one multicast host group, this method can be called repeatedly
on the same connection.
Trying to join more groups as supported by the platform results in IOException.
group
- the multicast host group address as defined by the BNF rule
multicast_connection
java.io.IOException
- if there is an error joiningjava.lang.UnsupportedOperationException
- is thrown if joining a multicast group is not supportedjava.lang.IllegalArgumentException
- if the address is not a valid multicast
group addressjava.lang.SecurityException
- if the caller is not permitted to join the group.void leave(java.lang.String group) throws java.io.IOException
group
.
See join
for the format of the group address.
If the group was not previously joined, an IOException is thrown.
The connection will no longer be listening for datagrams in the group
but some buffered datagrams may be received with that group address.group
- the multicast group address as defined by the BNF rule
multicast_connection
java.io.IOException
- if there's an error leaving.java.lang.IllegalArgumentException
- if the group address is not a valid
multicast group address.java.lang.SecurityException
- if the caller is not permitted to leave the group.void receive(Datagram dgram) throws java.io.IOException
Datagram
object is filled with the
data received, starting at the location determined by the
offset
state variable, and the data is ready to be read
using the methods of the DataInput
interface.
This method blocks until a datagram is received. The internal
length
state variable in the Datagram
object is
set to the length of the received datagram. If the received data is
longer than the initial length
state variable of the
internal buffer, data is truncated.
This method does not change the internal read/write state variable
of the Datagram
object. Use method
Datagram.reset
to change the pointer before reading if
necessary.
If the application has permission to receive the datagram, the Datagram is filled with the data and address. If access is not permitted, the datagram is discarded without modifying the Datagram instance and the receive method does not return.
receive
in interface DatagramConnection
dgram
- A datagram.java.lang.NullPointerException
- if dgram
is null
.java.io.IOException
- If an I/O error occurs.java.io.InterruptedIOException
- Timeout or interrupt occurred.void send(Datagram dgram) throws java.io.IOException
Datagram
object includes the
information indicating the data to be sent, its length, and the address
of the receiver. The method sends length
bytes starting at
the current offset
of the Datagram
object,
where length
and offset
are internal state
variables of the Datagram
object.
As per RFC 1112, the source address of the datagram is the address of the current host.
send
in interface DatagramConnection
dgram
- A datagram.java.lang.NullPointerException
- if dgram
is null
.java.io.IOException
- If an I/O error occurs; for example if the Datagram's
length exceeds the maximum size.java.lang.IllegalArgumentException
- if dgram.getAddress()
is null
.java.lang.SecurityException
- if the caller is not permitted to send the datagram.void setDisableLoopback(boolean disable) throws java.io.IOException
Because this option is a hint, applications that want to verify what
loopback mode is set to should call isDisableLoopback()
disable
- true
to disable the local loopback modejava.io.IOException
- if an error occurs while setting the valueisDisableLoopback()
void setTimeToLive(int ttl) throws java.io.IOException
UDPMulticastConnection
in order to control the scope of the
multicasts.
The time-to-live must be in the range 0 <= ttl <= 255
or an IllegalArgumentException will be thrown.
ttl
- the time-to-livejava.io.IOException
- if an I/O exception occurs while setting the default
time-to-live valuegetTimeToLive()
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.