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 17package 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 */ 34public 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 super(); 63 } 64 65 /** 66 * Attaches an object to this key. It is acceptable to attach {@code null}, 67 * this discards the old attachment. 68 * 69 * @param anObject 70 * the object to attach, or {@code null} to discard the current 71 * attachment. 72 * @return the last attached object or {@code null} if no object has been 73 * attached. 74 */ 75 public final Object attach(Object anObject) { 76 Object oldAttachment = attachment; 77 attachment = anObject; 78 return oldAttachment; 79 } 80 81 /** 82 * Gets the attached object. 83 * 84 * @return the attached object or {@code null} if no object has been 85 * attached. 86 */ 87 public final Object attachment() { 88 return attachment; 89 } 90 91 /** 92 * Cancels this key. 93 * <p> 94 * A key that has been canceled is no longer valid. Calling this method on 95 * an already canceled key does nothing. 96 * <p> 97 * Calling this method is safe at any time. The call might block until 98 * another ongoing call to a method of this selector has finished. The 99 * reason is that it is synchronizing on the key set of the selector. After 100 * this call finishes, the key will have been added to the selectors 101 * canceled-keys set and will not be included in any future selects of this 102 * selector. 103 */ 104 public abstract void cancel(); 105 106 /** 107 * Gets the channel of this key. 108 * 109 * @return the channel of this key. 110 */ 111 public abstract SelectableChannel channel(); 112 113 /** 114 * Gets this key's {@link SelectionKey interest set}. The returned set has 115 * only those bits set that are valid for this key's channel. 116 * 117 * @return the interest set of this key. 118 * @throws CancelledKeyException 119 * if the key has already been canceled. 120 */ 121 public abstract int interestOps(); 122 123 /** 124 * Sets the {@link SelectionKey interest set} for this key. 125 * 126 * @param operations 127 * the new interest set. 128 * @return this key. 129 * @throws IllegalArgumentException 130 * if a bit in {@code operations} is not in the set of 131 * {@link SelectableChannel#validOps() valid operations} of this 132 * key's channel. 133 * @throws CancelledKeyException 134 * if the key has already been canceled. 135 */ 136 public abstract SelectionKey interestOps(int operations); 137 138 /** 139 * Indicates whether this key's channel is interested in the accept 140 * operation and is ready to accept new connections. A call to this method 141 * is equal to executing {@code (readyOps() & OP_ACCEPT) == OP_ACCEPT}. 142 * 143 * @return {@code true} if the channel is interested in the accept operation 144 * and is ready to accept new connections, {@code false} otherwise. 145 * @throws CancelledKeyException 146 * if the key has already been canceled. 147 */ 148 public final boolean isAcceptable() { 149 return (readyOps() & OP_ACCEPT) == OP_ACCEPT; 150 } 151 152 /** 153 * Indicates whether this key's channel is interested in the connect 154 * operation and is ready to connect. A call to this method is equal to 155 * executing {@code (readyOps() & OP_CONNECT) == OP_CONNECT}. 156 * 157 * @return {@code true} if the channel is interested in the connect 158 * operation and is ready to connect, {@code false} otherwise. 159 * @throws CancelledKeyException 160 * if the key has already been canceled. 161 */ 162 public final boolean isConnectable() { 163 return (readyOps() & OP_CONNECT) == OP_CONNECT; 164 } 165 166 /** 167 * Indicates whether this key's channel is interested in the read operation 168 * and is ready to read. A call to this method is equal to executing 169 * {@code (readyOps() & OP_READ) == OP_READ}. 170 * 171 * @return {@code true} if the channel is interested in the read operation 172 * and is ready to read, {@code false} otherwise. 173 * @throws CancelledKeyException 174 * if the key has already been canceled. 175 */ 176 public final boolean isReadable() { 177 return (readyOps() & OP_READ) == OP_READ; 178 } 179 180 /** 181 * Indicates whether this key is valid. A key is valid as long as it has not 182 * been canceled. 183 * 184 * @return {@code true} if this key has not been canceled, {@code false} 185 * otherwise. 186 */ 187 public abstract boolean isValid(); 188 189 /** 190 * Indicates whether this key's channel is interested in the write operation 191 * and is ready to write. A call to this method is equal to executing 192 * {@code (readyOps() & OP_WRITE) == OP_WRITE}. 193 * 194 * @return {@code true} if the channel is interested in the write operation 195 * and is ready to write, {@code false} otherwise. 196 * @throws CancelledKeyException 197 * if the key has already been canceled. 198 */ 199 public final boolean isWritable() { 200 return (readyOps() & OP_WRITE) == OP_WRITE; 201 } 202 203 /** 204 * Gets the set of operations that are ready. The returned set has only 205 * those bits set that are valid for this key's channel. 206 * 207 * @return the operations for which this key's channel is ready. 208 * @throws CancelledKeyException 209 * if the key has already been canceled. 210 */ 211 public abstract int readyOps(); 212 213 /** 214 * Gets the selector for which this key's channel is registered. 215 * 216 * @return the related selector. 217 */ 218 public abstract Selector selector(); 219} 220