1/*
2 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.nio.channels;
27
28import java.net.InetAddress;
29import java.net.NetworkInterface;
30import java.io.IOException;
31
32/**
33 * A token representing the membership of an Internet Protocol (IP) multicast
34 * group.
35 *
36 * <p> A membership key may represent a membership to receive all datagrams sent
37 * to the group, or it may be <em>source-specific</em>, meaning that it
38 * represents a membership that receives only datagrams from a specific source
39 * address. Whether or not a membership key is source-specific may be determined
40 * by invoking its {@link #sourceAddress() sourceAddress} method.
41 *
42 * <p> A membership key is valid upon creation and remains valid until the
43 * membership is dropped by invoking the {@link #drop() drop} method, or
44 * the channel is closed. The validity of the membership key may be tested
45 * by invoking its {@link #isValid() isValid} method.
46 *
47 * <p> Where a membership key is not source-specific and the underlying operation
48 * system supports source filtering, then the {@link #block block} and {@link
49 * #unblock unblock} methods can be used to block or unblock multicast datagrams
50 * from particular source addresses.
51 *
52 * @see MulticastChannel
53 *
54 * @since 1.7
55 */
56public abstract class MembershipKey {
57
58    /**
59     * Initializes a new instance of this class.
60     */
61    protected MembershipKey() {
62    }
63
64    /**
65     * Tells whether or not this membership is valid.
66     *
67     * <p> A multicast group membership is valid upon creation and remains
68     * valid until the membership is dropped by invoking the {@link #drop() drop}
69     * method, or the channel is closed.
70     *
71     * @return  {@code true} if this membership key is valid, {@code false}
72     *          otherwise
73     */
74    public abstract boolean isValid();
75
76    /**
77     * Drop membership.
78     *
79     * <p> If the membership key represents a membership to receive all datagrams
80     * then the membership is dropped and the channel will no longer receive any
81     * datagrams sent to the group. If the membership key is source-specific
82     * then the channel will no longer receive datagrams sent to the group from
83     * that source address.
84     *
85     * <p> After membership is dropped it may still be possible to receive
86     * datagrams sent to the group. This can arise when datagrams are waiting to
87     * be received in the socket's receive buffer. After membership is dropped
88     * then the channel may {@link MulticastChannel#join join} the group again
89     * in which case a new membership key is returned.
90     *
91     * <p> Upon return, this membership object will be {@link #isValid() invalid}.
92     * If the multicast group membership is already invalid then invoking this
93     * method has no effect. Once a multicast group membership is invalid,
94     * it remains invalid forever.
95     */
96    public abstract void drop();
97
98    /**
99     * Block multicast datagrams from the given source address.
100     *
101     * <p> If this membership key is not source-specific, and the underlying
102     * operating system supports source filtering, then this method blocks
103     * multicast datagrams from the given source address. If the given source
104     * address is already blocked then this method has no effect.
105     * After a source address is blocked it may still be possible to receive
106     * datagrams from that source. This can arise when datagrams are waiting to
107     * be received in the socket's receive buffer.
108     *
109     * @param   source
110     *          The source address to block
111     *
112     * @return  This membership key
113     *
114     * @throws  IllegalArgumentException
115     *          If the {@code source} parameter is not a unicast address or
116     *          is not the same address type as the multicast group
117     * @throws  IllegalStateException
118     *          If this membership key is source-specific or is no longer valid
119     * @throws  UnsupportedOperationException
120     *          If the underlying operating system does not support source
121     *          filtering
122     * @throws  IOException
123     *          If an I/O error occurs
124     */
125    public abstract MembershipKey block(InetAddress source) throws IOException;
126
127    /**
128     * Unblock multicast datagrams from the given source address that was
129     * previously blocked using the {@link #block(InetAddress) block} method.
130     *
131     * @param   source
132     *          The source address to unblock
133     *
134     * @return  This membership key
135     *
136     * @throws  IllegalStateException
137     *          If the given source address is not currently blocked or the
138     *          membership key is no longer valid
139     */
140    public abstract MembershipKey unblock(InetAddress source);
141
142    /**
143     * Returns the channel for which this membership key was created. This
144     * method will continue to return the channel even after the membership
145     * becomes {@link #isValid invalid}.
146     *
147     * @return  the channel
148     */
149    public abstract MulticastChannel channel();
150
151    /**
152     * Returns the multicast group for which this membership key was created.
153     * This method will continue to return the group even after the membership
154     * becomes {@link #isValid invalid}.
155     *
156     * @return  the multicast group
157     */
158    public abstract InetAddress group();
159
160    /**
161     * Returns the network interface for which this membership key was created.
162     * This method will continue to return the network interface even after the
163     * membership becomes {@link #isValid invalid}.
164     *
165     * @return  the network interface
166     */
167    public abstract NetworkInterface networkInterface();
168
169    /**
170     * Returns the source address if this membership key is source-specific,
171     * or {@code null} if this membership is not source-specific.
172     *
173     * @return  The source address if this membership key is source-specific,
174     *          otherwise {@code null}
175     */
176    public abstract InetAddress sourceAddress();
177}
178