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 17 package java.nio.channels; 18 19 import java.io.Closeable; 20 import java.io.IOException; 21 import java.nio.channels.spi.SelectorProvider; 22 import java.util.Set; 23 24 /** 25 * A controller for the selection of {@link SelectableChannel} objects. 26 * Selectable channels can be registered with a selector and get a 27 * {@link SelectionKey} that represents the registration. The keys are also 28 * added to the selector's key set. Selection keys can be canceled so that the 29 * corresponding channel is no longer registered with the selector. 30 * <p> 31 * By invoking the {@code select} method, the key set is checked and all keys 32 * that have been canceled since last select operation are moved to the set of 33 * canceled keys. During the select operation, the channels registered with this 34 * selector are checked to see whether they are ready for operation according to 35 * their {@link SelectionKey interest set}. 36 */ 37 public abstract class Selector implements Closeable { 38 39 /** 40 * Returns a selector returned by {@link SelectorProvider#provider}'s 41 * {@link SelectorProvider#openSelector} method. 42 * 43 * @throws IOException 44 * if an I/O error occurs. 45 */ 46 public static Selector open() throws IOException { 47 return SelectorProvider.provider().openSelector(); 48 } 49 50 /** 51 * Constructs a new {@code Selector}. 52 */ 53 protected Selector() { 54 } 55 56 /** 57 * Closes this selector. Ongoing calls to the {@code select} methods of this 58 * selector will get interrupted. This interruption behaves as if the 59 * {@link #wakeup()} method of this selector is called. After this, all keys 60 * that are still valid are invalidated and their channels are unregistered. 61 * All resources held by this selector are released. 62 * <p> 63 * Any further attempt of using this selector after this method has been 64 * called (except calling {@link #close()} or {@link #wakeup()}) results in 65 * a {@link ClosedSelectorException} being thrown. 66 * 67 * @throws IOException 68 * if an I/O error occurs. 69 */ 70 public abstract void close() throws IOException; 71 72 /** 73 * Indicates whether this selector is open. 74 * 75 * @return {@code true} if this selector is not closed, {@code false} 76 * otherwise. 77 */ 78 public abstract boolean isOpen(); 79 80 /** 81 * Gets the set of registered keys. The set is immutable and is not thread- 82 * safe. 83 * 84 * @return the set of registered keys. 85 */ 86 public abstract Set<SelectionKey> keys(); 87 88 /** 89 * Gets the provider of this selector. 90 * 91 * @return the provider of this selector. 92 */ 93 public abstract SelectorProvider provider(); 94 95 /** 96 * Detects if any of the registered channels is ready for I/O operations 97 * according to its {@link SelectionKey interest set}. This method does not 98 * return until at least one channel is ready, {@link #wakeup()} is 99 * invoked or the calling thread is interrupted. 100 * 101 * @return the number of channels that are ready for operation. 102 * @throws IOException 103 * if an I/O error occurs. 104 * @throws ClosedSelectorException 105 * if the selector is closed. 106 */ 107 public abstract int select() throws IOException; 108 109 /** 110 * Detects if any of the registered channels is ready for I/O operations 111 * according to its {@link SelectionKey interest set}. This method does not 112 * return until at least one channel is ready, {@link #wakeup()} is invoked, 113 * the calling thread is interrupted or the specified {@code timeout} 114 * expires. 115 * 116 * @param timeout 117 * the non-negative timeout in millisecond; 0 will block forever 118 * if no channels get ready. 119 * @return the number of channels that are ready for operation. 120 * @throws ClosedSelectorException 121 * if the selector is closed. 122 * @throws IllegalArgumentException 123 * if the given timeout argument is less than zero. 124 * @throws IOException 125 * if an I/O error occurs. 126 */ 127 public abstract int select(long timeout) throws IOException; 128 129 /** 130 * Gets the selection keys whose channels are ready for operation. The set 131 * is not thread-safe and no keys may be added to it. Removing keys is 132 * allowed. 133 * 134 * @return the selection keys whose channels are ready for operation. 135 * @throws ClosedSelectorException 136 * if the selector is closed. 137 */ 138 public abstract Set<SelectionKey> selectedKeys(); 139 140 /** 141 * Detects if any of the registered channels is ready for I/O operations 142 * according to its {@link SelectionKey interest set}. This operation will 143 * return immediately. 144 * 145 * @return the number of channels that are ready for operation, 0 if none is 146 * ready. 147 * @throws IOException 148 * if an I/O error occurrs. 149 * @throws ClosedSelectorException 150 * if the selector is closed. 151 */ 152 public abstract int selectNow() throws IOException; 153 154 /** 155 * Forces blocked {@code select} operations to return immediately. 156 * <p> 157 * If no {@code select} operation is blocked when {@code wakeup()} is called 158 * then the next {@code select} operation will return immediately. This can 159 * be undone by a call to {@code selectNow()}; after calling 160 * {@code selectNow()}, a subsequent call of {@code select} can block 161 * again. 162 * 163 * @return this selector. 164 * @throws ClosedSelectorException 165 * if the selector is closed. 166 */ 167 public abstract Selector wakeup(); 168 } 169
