/* 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() {
}
/**
* 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();
}