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 /** 20 * A {@code SelectionKey} represents the relationship between a channel and a 21 * selector for which the channel is registered. 22 * <h3>Operation set</h3> 23 * An operation set is represented by an integer value. The bits of an operation 24 * set represent categories of operations for a key's channel: Accepting socket 25 * connections ({@code OP_ACCEPT}), connecting with a socket ({@code OP_CONNECT}), 26 * reading ({@code OP_READ}) and writing ({@code OP_WRITE}). 27 * <h4>Interest set</h4> 28 * The interest set is an operation set that defines the operations that a 29 * {@link SelectableChannel channel} is interested in performing. 30 * <h4>Ready set</h4> 31 * The ready set is an operation set that shows the operations that a 32 * {@code channel} is ready to execute. 33 */ 34 public abstract class SelectionKey { 35 36 /** 37 * Interest set mask bit for socket-accept operations. 38 */ 39 public static final int OP_ACCEPT = 16; 40 41 /** 42 * Interest set mask bit for socket-connect operations. 43 */ 44 public static final int OP_CONNECT = 8; 45 46 /** 47 * Interesting operation mask bit for read operations. 48 */ 49 public static final int OP_READ = 1; 50 51 /** 52 * Interest set mask bit for write operations. 53 */ 54 public static final int OP_WRITE = 4; 55 56 private volatile Object attachment = null; 57 58 /** 59 * Constructs a new {@code SelectionKey}. 60 */ 61 protected SelectionKey() { 62 } 63 64 /** 65 * Attaches an object to this key. It is acceptable to attach {@code null}, 66 * this discards the old attachment. 67 * 68 * @param anObject 69 * the object to attach, or {@code null} to discard the current 70 * attachment. 71 * @return the last attached object or {@code null} if no object has been 72 * attached. 73 */ 74 public final Object attach(Object anObject) { 75 Object oldAttachment = attachment; 76 attachment = anObject; 77 return oldAttachment; 78 } 79 80 /** 81 * Gets the attached object. 82 * 83 * @return the attached object or {@code null} if no object has been 84 * attached. 85 */ 86 public final Object attachment() { 87 return attachment; 88 } 89 90 /** 91 * Cancels this key. 92 * <p> 93 * A key that has been canceled is no longer valid. Calling this method on 94 * an already canceled key does nothing. 95 * <p> 96 * Calling this method is safe at any time. The call might block until 97 * another ongoing call to a method of this selector has finished. The 98 * reason is that it is synchronizing on the key set of the selector. After 99 * this call finishes, the key will have been added to the selectors 100 * canceled-keys set and will not be included in any future selects of this 101 * selector. 102 */ 103 public abstract void cancel(); 104 105 /** 106 * Gets the channel of this key. 107 * 108 * @return the channel of this key. 109 */ 110 public abstract SelectableChannel channel(); 111 112 /** 113 * Gets this key's {@link SelectionKey interest set}. The returned set has 114 * only those bits set that are valid for this key's channel. 115 * 116 * @return the interest set of this key. 117 * @throws CancelledKeyException 118 * if the key has already been canceled. 119 */ 120 public abstract int interestOps(); 121 122 /** 123 * Sets the {@link SelectionKey interest set} for this key. 124 * 125 * @param operations 126 * the new interest set. 127 * @return this key. 128 * @throws IllegalArgumentException 129 * if a bit in {@code operations} is not in the set of 130 * {@link SelectableChannel#validOps() valid operations} of this 131 * key's channel. 132 * @throws CancelledKeyException 133 * if the key has already been canceled. 134 */ 135 public abstract SelectionKey interestOps(int operations); 136 137 /** 138 * Indicates whether this key's channel is interested in the accept 139 * operation and is ready to accept new connections. A call to this method 140 * is equal to executing {@code (readyOps() & OP_ACCEPT) == OP_ACCEPT}. 141 * 142 * @return {@code true} if the channel is interested in the accept operation 143 * and is ready to accept new connections, {@code false} otherwise. 144 * @throws CancelledKeyException 145 * if the key has already been canceled. 146 */ 147 public final boolean isAcceptable() { 148 return (readyOps() & OP_ACCEPT) == OP_ACCEPT; 149 } 150 151 /** 152 * Indicates whether this key's channel is interested in the connect 153 * operation and is ready to connect. A call to this method is equal to 154 * executing {@code (readyOps() & OP_CONNECT) == OP_CONNECT}. 155 * 156 * @return {@code true} if the channel is interested in the connect 157 * operation and is ready to connect, {@code false} otherwise. 158 * @throws CancelledKeyException 159 * if the key has already been canceled. 160 */ 161 public final boolean isConnectable() { 162 return (readyOps() & OP_CONNECT) == OP_CONNECT; 163 } 164 165 /** 166 * Indicates whether this key's channel is interested in the read operation 167 * and is ready to read. A call to this method is equal to executing 168 * {@code (readyOps() & OP_READ) == OP_READ}. 169 * 170 * @return {@code true} if the channel is interested in the read operation 171 * and is ready to read, {@code false} otherwise. 172 * @throws CancelledKeyException 173 * if the key has already been canceled. 174 */ 175 public final boolean isReadable() { 176 return (readyOps() & OP_READ) == OP_READ; 177 } 178 179 /** 180 * Indicates whether this key is valid. A key is valid as long as it has not 181 * been canceled. 182 * 183 * @return {@code true} if this key has not been canceled, {@code false} 184 * otherwise. 185 */ 186 public abstract boolean isValid(); 187 188 /** 189 * Indicates whether this key's channel is interested in the write operation 190 * and is ready to write. A call to this method is equal to executing 191 * {@code (readyOps() & OP_WRITE) == OP_WRITE}. 192 * 193 * @return {@code true} if the channel is interested in the write operation 194 * and is ready to write, {@code false} otherwise. 195 * @throws CancelledKeyException 196 * if the key has already been canceled. 197 */ 198 public final boolean isWritable() { 199 return (readyOps() & OP_WRITE) == OP_WRITE; 200 } 201 202 /** 203 * Gets the set of operations that are ready. The returned set has only 204 * those bits set that are valid for this key's channel. 205 * 206 * @return the operations for which this key's channel is ready. 207 * @throws CancelledKeyException 208 * if the key has already been canceled. 209 */ 210 public abstract int readyOps(); 211 212 /** 213 * Gets the selector for which this key's channel is registered. 214 * 215 * @return the related selector. 216 */ 217 public abstract Selector selector(); 218 } 219
