1 /*

     2  * Copyright 2007-2008 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.nio.channels;

    27 

    28 import java.net.InetAddress;

    29 import java.net.NetworkInterface;

    30 import java.io.IOException;

    31 import java.net.ProtocolFamily;             // javadoc

    32 import java.net.StandardProtocolFamily;     // javadoc

    33 import java.net.StandardSocketOption;       // javadoc

    34 

    35 /**

    36  * A network channel that supports Internet Protocol (IP) multicasting.

    37  *

    38  * <p> IP multicasting is the transmission of IP datagrams to members of

    39  * a <em>group</em> that is zero or more hosts identified by a single destination

    40  * address.

    41  *

    42  * <p> In the case of a channel to an {@link StandardProtocolFamily#INET IPv4} socket,

    43  * the underlying operating system supports <a href="http://www.ietf.org/rfc/rfc2236.txt">

    44  * <i>RFC&nbsp;2236: Internet Group Management Protocol, Version 2 (IGMPv2)</i></a>.

    45  * It may optionally support source filtering as specified by <a

    46  * href="http://www.ietf.org/rfc/rfc3376.txt"> <i>RFC&nbsp;3376: Internet Group

    47  * Management Protocol, Version 3 (IGMPv3)</i></a>.

    48  * For channels to an {@link StandardProtocolFamily#INET6 IPv6} socket, the equivalent

    49  * standards are <a href="http://www.ietf.org/rfc/rfc2710.txt"> <i>RFC&nbsp;2710:

    50  * Multicast Listener Discovery (MLD) for IPv6</i></a> and <a

    51  * href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC&nbsp;3810: Multicast Listener

    52  * Discovery Version 2 (MLDv2) for IPv6</i></a>.

    53  *

    54  * <p> The {@link #join(InetAddress,NetworkInterface)} method is used to

    55  * join a group and receive all multicast datagrams sent to the group. A channel

    56  * may join several multicast groups and may join the same group on several

    57  * {@link NetworkInterface interfaces}. Membership is dropped by invoking the {@link

    58  * MembershipKey#drop drop} method on the returned {@link MembershipKey}. If the

    59  * underlying platform supports source filtering then the {@link MembershipKey#block

    60  * block} and {@link MembershipKey#unblock unblock} methods can be used to block or

    61  * unblock multicast datagrams from particular source addresses.

    62  *

    63  * <p> The {@link #join(InetAddress,NetworkInterface,InetAddress)} method

    64  * is used to begin receiving datagrams sent to a group whose source address matches

    65  * a given source address. This method throws {@link UnsupportedOperationException}

    66  * if the underlying platform does not support source filtering.  Membership is

    67  * <em>cumulative</em> and this method may be invoked again with the same group

    68  * and interface to allow receiving datagrams from other source addresses. The

    69  * method returns a {@link MembershipKey} that represents membership to receive

    70  * datagrams from the given source address. Invoking the key's {@link

    71  * MembershipKey#drop drop} method drops membership so that datagrams from the

    72  * source address can no longer be received.

    73  *

    74  * <h4>Platform dependencies</h4>

    75  *

    76  * The multicast implementation is intended to map directly to the native

    77  * multicasting facility. Consequently, the following items should be considered

    78  * when developing an application that receives IP multicast datagrams:

    79  *

    80  * <ol>

    81  *

    82  * <li><p> The creation of the channel should specify the {@link ProtocolFamily}

    83  * that corresponds to the address type of the multicast groups that the channel

    84  * will join. There is no guarantee that a channel to a socket in one protocol

    85  * family can join and receive multicast datagrams when the address of the

    86  * multicast group corresponds to another protocol family. For example, it is

    87  * implementation specific if a channel to an {@link StandardProtocolFamily#INET6 IPv6}

    88  * socket can join an {@link StandardProtocolFamily#INET IPv4} multicast group and receive

    89  * multicast datagrams sent to the group. </p></li>

    90  *

    91  * <li><p> The channel's socket should be bound to the {@link

    92  * InetAddress#isAnyLocalAddress wildcard} address. If the socket is bound to

    93  * a specific address, rather than the wildcard address then it is implementation

    94  * specific if multicast datagrams are received by the socket. </p></li>

    95  *

    96  * <li><p> The {@link StandardSocketOption#SO_REUSEADDR SO_REUSEADDR} option should be

    97  * enabled prior to {@link NetworkChannel#bind binding} the socket. This is

    98  * required to allow multiple members of the group to bind to the same

    99  * address. </p></li>

   100  *

   101  * </ol>

   102  *

   103  * <p> <b>Usage Example:</b>

   104  * <pre>

   105  *     // join multicast group on this interface, and also use this

   106  *     // interface for outgoing multicast datagrams

   107  *     NetworkInterface ni = NetworkInterface.getByName("hme0");

   108  *

   109  *     DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)

   110  *         .setOption(StandardSocketOption.SO_REUSEADDR, true)

   111  *         .bind(new InetSocketAddress(5000))

   112  *         .setOption(StandardSocketOption.IP_MULTICAST_IF, ni);

   113  *

   114  *     InetAddress group = InetAddress.getByName("225.4.5.6");

   115  *

   116  *     MembershipKey key = dc.join(group, ni);

   117  * </pre>

   118  *

   119  * @since 1.7

   120  */

   121 

   122 public interface MulticastChannel

   123     extends NetworkChannel

   124 {

   125     /**

   126      * Joins a multicast group to begin receiving all datagrams sent to the group,

   127      * returning a membership key.

   128      *

   129      * <p> If this channel is currently a member of the group on the given

   130      * interface to receive all datagrams then the membership key, representing

   131      * that membership, is returned. Otherwise this channel joins the group and

   132      * the resulting new membership key is returned. The resulting membership key

   133      * is not {@link MembershipKey#getSourceAddress source-specific}.

   134      *

   135      * <p> A multicast channel may join several multicast groups, including

   136      * the same group on more than one interface. An implementation may impose a

   137      * limit on the number of groups that may be joined at the same time.

   138      *

   139      * @param   group

   140      *          The multicast address to join

   141      * @param   interf

   142      *          The network interface on which to join the group

   143      *

   144      * @return  The membership key

   145      *

   146      * @throws  IllegalArgumentException

   147      *          If the group parameter is not a {@link InetAddress#isMulticastAddress

   148      *          multicast} address, or the group parameter is an address type

   149      *          that is not supported by this channel

   150      * @throws  IllegalStateException

   151      *          If the channel already has source-specific membership of the

   152      *          group on the interface

   153      * @throws  ClosedChannelException

   154      *          If this channel is closed

   155      * @throws  IOException

   156      *          If an I/O error occurs

   157      * @throws  SecurityException

   158      *          If a security manager is set, and its

   159      *          {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}

   160      *          method denies access to the multiast group

   161      */

   162     MembershipKey join(InetAddress group, NetworkInterface interf)

   163         throws IOException;

   164 

   165     /**

   166      * Joins a multicast group to begin receiving datagrams sent to the group

   167      * from a given source address.

   168      *

   169      * <p> If this channel is currently a member of the group on the given

   170      * interface to receive datagrams from the given source address then the

   171      * membership key, representing that membership, is returned. Otherwise this

   172      * channel joins the group and the resulting new membership key is returned.

   173      * The resulting membership key is {@link MembershipKey#getSourceAddress

   174      * source-specific}.

   175      *

   176      * <p> Membership is <em>cumulative</em> and this method may be invoked

   177      * again with the same group and interface to allow receiving datagrams sent

   178      * by other source addresses to the group.

   179      *

   180      * @param   group

   181      *          The multicast address to join

   182      * @param   interf

   183      *          The network interface on which to join the group

   184      * @param   source

   185      *          The source address

   186      *

   187      * @return  The membership key

   188      *

   189      * @throws  IllegalArgumentException

   190      *          If the group parameter is not a {@link

   191      *          InetAddress#isMulticastAddress multicast} address, the

   192      *          source parameter is not a unicast address, the group

   193      *          parameter is an address type that is not supported by this channel,

   194      *          or the source parameter is not the same address type as the group

   195      * @throws  IllegalStateException

   196      *          If the channel is currently a member of the group on the given

   197      *          interface to receive all datagrams

   198      * @throws  UnsupportedOperationException

   199      *          If the underlying operation system does not support source filtering

   200      * @throws  ClosedChannelException

   201      *          If this channel is closed

   202      * @throws  IOException

   203      *          If an I/O error occurs

   204      * @throws  SecurityException

   205      *          If a security manager is set, and its

   206      *          {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}

   207      *          method denies access to the multiast group

   208      */

   209     MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source)

   210         throws IOException;

   211 }