| /* 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.SelectorProvider; |
| import java.util.Set; |
| |
| /** |
| * A controller for the selection of {@link SelectableChannel} objects. |
| * Selectable channels can be registered with a selector and get a |
| * {@link SelectionKey} that represents the registration. The keys are also |
| * added to the selector's key set. Selection keys can be canceled so that the |
| * corresponding channel is no longer registered with the selector. |
| * <p> |
| * By invoking the {@code select} method, the key set is checked and all keys |
| * that have been canceled since last select operation are moved to the set of |
| * canceled keys. During the select operation, the channels registered with this |
| * selector are checked to see whether they are ready for operation according to |
| * their {@link SelectionKey interest set}. |
| */ |
| public abstract class Selector { |
| |
| /** |
| * Returns a selector returned by {@link SelectorProvider#provider}'s |
| * {@link SelectorProvider#openSelector} method. |
| * |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public static Selector open() throws IOException { |
| return SelectorProvider.provider().openSelector(); |
| } |
| |
| /** |
| * Constructs a new {@code Selector}. |
| */ |
| protected Selector() { |
| super(); |
| } |
| |
| /** |
| * Closes this selector. Ongoing calls to the {@code select} methods of this |
| * selector will get interrupted. This interruption behaves as if the |
| * {@link #wakeup()} method of this selector is called. After this, all keys |
| * that are still valid are invalidated and their channels are unregistered. |
| * All resources held by this selector are released. |
| * <p> |
| * Any further attempt of using this selector after this method has been |
| * called (except calling {@link #close()} or {@link #wakeup()}) results in |
| * a {@link ClosedSelectorException} being thrown. |
| * |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public abstract void close() throws IOException; |
| |
| /** |
| * Indicates whether this selector is open. |
| * |
| * @return {@code true} if this selector is not closed, {@code false} |
| * otherwise. |
| */ |
| public abstract boolean isOpen(); |
| |
| /** |
| * Gets the set of registered keys. The set is immutable and is not thread- |
| * safe. |
| * |
| * @return the set of registered keys. |
| */ |
| public abstract Set<SelectionKey> keys(); |
| |
| /** |
| * Gets the provider of this selector. |
| * |
| * @return the provider of this selector. |
| */ |
| public abstract SelectorProvider provider(); |
| |
| /** |
| * Detects if any of the registered channels is ready for I/O operations |
| * according to its {@link SelectionKey interest set}. This method does not |
| * return until at least one channel is ready, {@link #wakeup()} is |
| * invoked or the calling thread is interrupted. |
| * |
| * @return the number of channels that are ready for operation. |
| * @throws IOException |
| * if an I/O error occurs. |
| * @throws ClosedSelectorException |
| * if the selector is closed. |
| */ |
| public abstract int select() throws IOException; |
| |
| /** |
| * Detects if any of the registered channels is ready for I/O operations |
| * according to its {@link SelectionKey interest set}. This method does not |
| * return until at least one channel is ready, {@link #wakeup()} is invoked, |
| * the calling thread is interrupted or the specified {@code timeout} |
| * expires. |
| * |
| * @param timeout |
| * the non-negative timeout in millisecond; 0 will block forever |
| * if no channels get ready. |
| * @return the number of channels that are ready for operation. |
| * @throws ClosedSelectorException |
| * if the selector is closed. |
| * @throws IllegalArgumentException |
| * if the given timeout argument is less than zero. |
| * @throws IOException |
| * if an I/O error occurs. |
| */ |
| public abstract int select(long timeout) throws IOException; |
| |
| /** |
| * Gets the selection keys whose channels are ready for operation. The set |
| * is not thread-safe and no keys may be added to it. Removing keys is |
| * allowed. |
| * |
| * @return the selection keys whose channels are ready for operation. |
| * @throws ClosedSelectorException |
| * if the selector is closed. |
| */ |
| public abstract Set<SelectionKey> selectedKeys(); |
| |
| /** |
| * Detects if any of the registered channels is ready for I/O operations |
| * according to its {@link SelectionKey interest set}. This operation will |
| * return immediately. |
| * |
| * @return the number of channels that are ready for operation, 0 if none is |
| * ready. |
| * @throws IOException |
| * if an I/O error occurrs. |
| * @throws ClosedSelectorException |
| * if the selector is closed. |
| */ |
| public abstract int selectNow() throws IOException; |
| |
| /** |
| * Forces blocked {@code select} operations to return immediately. |
| * <p> |
| * If no {@code select} operation is blocked when {@code wakeup()} is called |
| * then the next {@code select} operation will return immediately. This can |
| * be undone by a call to {@code selectNow()}; after calling |
| * {@code selectNow()}, a subsequent call of {@code select} can block |
| * again. |
| * |
| * @return this selector. |
| * @throws ClosedSelectorException |
| * if the selector is closed. |
| */ |
| public abstract Selector wakeup(); |
| } |