1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package java.nio.channels;
18
19import java.io.IOException;
20import java.nio.channels.spi.AbstractInterruptibleChannel;
21import java.nio.channels.spi.SelectorProvider;
22
23/**
24 * A channel that can be used with a {@link Selector}. The channel must be
25 * registered with a selector by calling one of the {@code register} methods,
26 * which return a {@link SelectionKey} object. In order to deregister a channel
27 * from a selector, its selection key must be canceled. This can be done
28 * explicitly by calling the {@link SelectionKey#cancel()} method but it is also
29 * done implicitly when the channel or the selector is closed.
30 * <p>
31 * A channel may be registered with several selectors at the same time but only
32 * once for any given selector.
33 */
34public abstract class SelectableChannel extends AbstractInterruptibleChannel
35        implements Channel {
36
37    /**
38     * Constructs a new {@code SelectableChannel}.
39     */
40    protected SelectableChannel() {
41    }
42
43    /**
44     * Gets the blocking lock which synchronizes the {@code configureBlocking}
45     * and {@code register} methods.
46     *
47     * @return the blocking object as lock.
48     */
49    public abstract Object blockingLock();
50
51    /**
52     * Sets the blocking mode of this channel. A call to this method blocks if
53     * other calls to this method or to a {@code register} method are executing.
54     * The new blocking mode is valid for calls to other methods that are
55     * invoked after the call to this method. If other methods are already
56     * executing when this method is called, they still have the old mode and
57     * the call to this method might block depending on the implementation.
58     *
59     * @param block
60     *            {@code true} for setting this channel's mode to blocking,
61     *            {@code false} to set it to non-blocking.
62     * @return this channel.
63     * @throws ClosedChannelException
64     *             if this channel is closed.
65     * @throws IllegalBlockingModeException
66     *             if {@code block} is {@code true} and this channel has been
67     *             registered with at least one selector.
68     * @throws IOException
69     *             if an I/O error occurs.
70     */
71    public abstract SelectableChannel configureBlocking(boolean block)
72            throws IOException;
73
74    /**
75     * Indicates whether this channel is in blocking mode.
76     *
77     * @return {@code true} if this channel is blocking, undefined if this
78     *         channel is closed.
79     */
80    public abstract boolean isBlocking();
81
82    /**
83     * Indicates whether this channel is registered with at least one selector.
84     *
85     * @return {@code true} if this channel is registered, {@code false}
86     *         otherwise.
87     */
88    public abstract boolean isRegistered();
89
90    /**
91     * Gets this channel's selection key for the specified selector.
92     *
93     * @param sel
94     *            the selector with which this channel has been registered.
95     * @return the selection key for the channel or {@code null} if this channel
96     *         has not been registered with {@code sel}.
97     */
98    public abstract SelectionKey keyFor(Selector sel);
99
100    /**
101     * Gets the provider of this channel.
102     *
103     * @return the provider of this channel.
104     */
105    public abstract SelectorProvider provider();
106
107    /**
108     * Registers this channel with the specified selector for the specified
109     * interest set. If the channel is already registered with the selector, the
110     * corresponding selection key is returned but the
111     * {@link SelectionKey interest set} is updated to {@code operations}. The
112     * returned key is canceled if the channel is closed while registering is in
113     * progress.
114     * <p>
115     * Calling this method is valid at any time. If another thread executes this
116     * method or the {@code configureBlocking(boolean} method then this call is
117     * blocked until the other call finishes. After that, it will synchronize on
118     * the key set of the selector and thus may again block if other threads
119     * also hold locks on the key set of the same selector.
120     * <p>
121     * Calling this method is equivalent to calling
122     * {@code register(selector, operations, null)}.
123     *
124     * @param selector
125     *            the selector with which to register this channel.
126     * @param operations
127     *            this channel's {@link SelectionKey interest set}.
128     * @return the selection key for this registration.
129     * @throws ClosedChannelException
130     *             if the channel is closed.
131     * @throws IllegalBlockingModeException
132     *             if the channel is in blocking mode.
133     * @throws IllegalSelectorException
134     *             if this channel does not have the same provider as the given
135     *             selector.
136     * @throws CancelledKeyException
137     *             if this channel is registered but its key has been canceled.
138     * @throws IllegalArgumentException
139     *             if the operation given is not supported by this channel.
140     */
141    public final SelectionKey register(Selector selector, int operations)
142            throws ClosedChannelException {
143        return register(selector, operations, null);
144    }
145
146    /**
147     * Registers this channel with the specified selector for the specified
148     * interest set and an object to attach. If the channel is already
149     * registered with the selector, the corresponding selection key is returned
150     * but its {@link SelectionKey interest set} is updated to {@code ops} and
151     * the attached object is updated to {@code att}. The returned key is
152     * canceled if the channel is closed while registering is in progress.
153     * <p>
154     * Calling this method is valid at any time. If another thread executes this
155     * method or the {@code configureBlocking(boolean)} method then this call is
156     * blocked until the other call finishes. After that, it will synchronize on
157     * the key set of the selector and thus may again block if other threads
158     * also hold locks on the key set of the same selector.
159     *
160     * @param sel
161     *            the selector with which to register this channel.
162     * @param ops
163     *            this channel's {@link SelectionKey interest set}.
164     * @param att
165     *            the object to attach, can be {@code null}.
166     * @return the selection key for this registration.
167     * @throws ClosedChannelException
168     *             if this channel is closed.
169     * @throws IllegalArgumentException
170     *             if {@code ops} is not supported by this channel.
171     * @throws IllegalBlockingModeException
172     *             if this channel is in blocking mode.
173     * @throws IllegalSelectorException
174     *             if this channel does not have the same provider as the given
175     *             selector.
176     * @throws CancelledKeyException
177     *             if this channel is registered but its key has been canceled.
178     */
179    public abstract SelectionKey register(Selector sel, int ops, Object att)
180            throws ClosedChannelException;
181
182    /**
183     * Gets the set of valid {@link SelectionKey operations} of this channel.
184     * Instances of a concrete channel class always return the same value.
185     *
186     * @return the set of operations that this channel supports.
187     */
188    public abstract int validOps();
189}
190