| /* Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package java.nio.channels; |
| |
| import java.io.IOException; |
| import java.nio.channels.spi.AbstractInterruptibleChannel; |
| import java.nio.channels.spi.SelectorProvider; |
| |
| /** |
| * A channel that can be used with a {@link Selector}. The channel must be |
| * registered with a selector by calling one of the {@code register} methods, |
| * which return a {@link SelectionKey} object. In order to deregister a channel |
| * from a selector, its selection key must be canceled. This can be done |
| * explicitly by calling the {@link SelectionKey#cancel()} method but it is also |
| * done implicitly when the channel or the selector is closed. |
| * <p> |
| * A channel may be registered with several selectors at the same time but only |
| * once for any given selector. |
| */ |
| public abstract class SelectableChannel extends AbstractInterruptibleChannel |
| implements Channel { |
| |
| /** |
| * Constructs a new {@code SelectableChannel}. |
| */ |
| protected SelectableChannel() { |
| super(); |
| } |
| |
| /** |
| * Gets the blocking lock which synchronizes the {@code configureBlocking} |
| * and {@code register} methods. |
| * |
| * @return the blocking object as lock. |
| */ |
| public abstract Object blockingLock(); |
| |
| /** |
| * Sets the blocking mode of this channel. A call to this method blocks if |
| * other calls to this method or to a {@code register} method are executing. |
| * The new blocking mode is valid for calls to other methods that are |
| * invoked after the call to this method. If other methods are already |
| * executing when this method is called, they still have the old mode and |
| * the call to this method might block depending on the implementation. |
| * |
| * @param block |
| * {@code true} for setting this channel's mode to blocking, |
| * {@code false} to set it to non-blocking. |
| * @return this channel. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IllegalBlockingModeException |
| * if {@code block} is {@code true} and this channel has been |
| * registered with at least one selector. |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public abstract SelectableChannel configureBlocking(boolean block) |
| throws IOException; |
| |
| /** |
| * Indicates whether this channel is in blocking mode. |
| * |
| * @return {@code true} if this channel is blocking, undefined if this |
| * channel is closed. |
| */ |
| public abstract boolean isBlocking(); |
| |
| /** |
| * Indicates whether this channel is registered with at least one selector. |
| * |
| * @return {@code true} if this channel is registered, {@code false} |
| * otherwise. |
| */ |
| public abstract boolean isRegistered(); |
| |
| /** |
| * Gets this channel's selection key for the specified selector. |
| * |
| * @param sel |
| * the selector with which this channel has been registered. |
| * @return the selection key for the channel or {@code null} if this channel |
| * has not been registered with {@code sel}. |
| */ |
| public abstract SelectionKey keyFor(Selector sel); |
| |
| /** |
| * Gets the provider of this channel. |
| * |
| * @return the provider of this channel. |
| */ |
| public abstract SelectorProvider provider(); |
| |
| /** |
| * Registers this channel with the specified selector for the specified |
| * interest set. If the channel is already registered with the selector, the |
| * corresponding selection key is returned but the |
| * {@link SelectionKey interest set} is updated to {@code operations}. The |
| * returned key is canceled if the channel is closed while registering is in |
| * progress. |
| * <p> |
| * Calling this method is valid at any time. If another thread executes this |
| * method or the {@code configureBlocking(boolean} method then this call is |
| * blocked until the other call finishes. After that, it will synchronize on |
| * the key set of the selector and thus may again block if other threads |
| * also hold locks on the key set of the same selector. |
| * <p> |
| * Calling this method is equivalent to calling |
| * {@code register(selector, operations, null)}. |
| * |
| * @param selector |
| * the selector with which to register this channel. |
| * @param operations |
| * this channel's {@link SelectionKey interest set}. |
| * @return the selection key for this registration. |
| * @throws ClosedChannelException |
| * if the channel is closed. |
| * @throws IllegalBlockingModeException |
| * if the channel is in blocking mode. |
| * @throws IllegalSelectorException |
| * if this channel does not have the same provider as the given |
| * selector. |
| * @throws CancelledKeyException |
| * if this channel is registered but its key has been canceled. |
| * @throws IllegalArgumentException |
| * if the operation given is not supported by this channel. |
| */ |
| public final SelectionKey register(Selector selector, int operations) |
| throws ClosedChannelException { |
| return register(selector, operations, null); |
| } |
| |
| /** |
| * Registers this channel with the specified selector for the specified |
| * interest set and an object to attach. If the channel is already |
| * registered with the selector, the corresponding selection key is returned |
| * but its {@link SelectionKey interest set} is updated to {@code ops} and |
| * the attached object is updated to {@code att}. The returned key is |
| * canceled if the channel is closed while registering is in progress. |
| * <p> |
| * Calling this method is valid at any time. If another thread executes this |
| * method or the {@code configureBlocking(boolean)} method then this call is |
| * blocked until the other call finishes. After that, it will synchronize on |
| * the key set of the selector and thus may again block if other threads |
| * also hold locks on the key set of the same selector. |
| * |
| * @param sel |
| * the selector with which to register this channel. |
| * @param ops |
| * this channel's {@link SelectionKey interest set}. |
| * @param att |
| * the object to attach, can be {@code null}. |
| * @return the selection key for this registration. |
| * @throws ClosedChannelException |
| * if this channel is closed. |
| * @throws IllegalArgumentException |
| * if {@code ops} is not supported by this channel. |
| * @throws IllegalBlockingModeException |
| * if this channel is in blocking mode. |
| * @throws IllegalSelectorException |
| * if this channel does not have the same provider as the given |
| * selector. |
| * @throws CancelledKeyException |
| * if this channel is registered but its key has been canceled. |
| */ |
| public abstract SelectionKey register(Selector sel, int ops, Object att) |
| throws ClosedChannelException; |
| |
| /** |
| * Gets the set of valid {@link SelectionKey operations} of this channel. |
| * Instances of a concrete channel class always return the same value. |
| * |
| * @return the set of operations that this channel supports. |
| */ |
| public abstract int validOps(); |
| } |
