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
or implicitly joined with a special form of the URL connect string as described
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 22.214.171.124 to 126.96.36.199, inclusive. The address 188.8.131.52 is reserved and should not be used. IPv6 multicast addresses use the address block with the prefix ff00::/8.
UDPMulticastConnection is returned from
Connector.open() in response to a request to open a
multicast:// URL connection string. If the connection string
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
setDisableLoopback(boolean). The initial value is
false as defined by RFC 1112.
MulticastConnectiondepends on the level of support from the underlying implementation. RFC 1112 describes 3 levels of Multicast conformance:
join(java.lang.String)MUST throw UnsupportedOperationException.
The syntax for the
UDPMulticastConnection URL is provided by 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
If the URI does not conform to this syntax or if the address is not a valid multicast address,
IllegalArgumentException is thrown.
Note that the syntax described for the
UDPMulticastConnection URL connection
string and the "multicast://" prefix is only used for the
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
Examples of multicast host group addresses:
|Modifier and Type||Method and Description|
Get the default time-to-live for multicast packets sent on this
Get the setting for local loopback of multicast datagrams.
Query whether the multicast stack supports joining a multicast group.
Join the multicast host group specified by
Leave a multicast host group specified by
Receive a multicast datagram.
Send a datagram to a multicast group.
Disable/Enable local loopback of multicast datagrams.
Set the default time-to-live (TTL) for multicast packets sent on this
getAccessPoint, getMaximumLength, getNominalLength, newDatagram, newDatagram, newDatagram, newDatagram
int getTimeToLive() throws java.io.IOException
java.io.IOException- if an I/O exception occurs while getting the default time-to-live value
boolean isDisableLoopback() throws java.io.IOException
java.io.IOException- if an error occurs while getting the value
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
java.io.IOException- if there is an error joining
java.lang.UnsupportedOperationException- is thrown if joining a multicast group is not supported
java.lang.IllegalArgumentException- if the address is not a valid multicast group address
java.lang.SecurityException- if the caller is not permitted to join the group.
void leave(java.lang.String group) throws java.io.IOException
joinfor the format of the group address. If the group was not previously joined, an IOException is thrown.
group- the multicast group address as defined by the BNF rule
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
Datagramobject is filled with the data received, starting at the location determined by the
offsetstate variable, and the data is ready to be read using the methods of the
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
Datagram object. Use method
Datagram.reset to change the pointer before reading if
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.
void send(Datagram dgram) throws java.io.IOException
Datagramobject includes the information indicating the data to be sent, its length, and the address of the receiver. The method sends
lengthbytes starting at the current
offsetare internal state variables of the
As per RFC 1112, the source address of the datagram is the address of the current host.
dgram- A datagram.
java.io.IOException- If an I/O error occurs; for example if the Datagram's length exceeds the maximum size.
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
trueto disable the local loopback mode
java.io.IOException- if an error occurs while setting the value
void setTimeToLive(int ttl) throws java.io.IOException
UDPMulticastConnectionin 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-live
java.io.IOException- if an I/O exception occurs while setting the default time-to-live value
Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.