/* 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;
/**
* A {@code SelectionKey} represents the relationship between a channel and a
* selector for which the channel is registered.
* <h3>Operation set</h3>
* An operation set is represented by an integer value. The bits of an operation
* set represent categories of operations for a key's channel: Accepting socket
* connections ({@code OP_ACCEPT}), connecting with a socket ({@code OP_CONNECT}),
* reading ({@code OP_READ}) and writing ({@code OP_WRITE}).
* <h4>Interest set</h4>
* The interest set is an operation set that defines the operations that a
* {@link SelectableChannel channel} is interested in performing.
* <h4>Ready set</h4>
* The ready set is an operation set that shows the operations that a
* {@code channel} is ready to execute.
*/
public abstract class SelectionKey {
/**
* Interest set mask bit for socket-accept operations.
*/
public static final int OP_ACCEPT = 16;
/**
* Interest set mask bit for socket-connect operations.
*/
public static final int OP_CONNECT = 8;
/**
* Interesting operation mask bit for read operations.
*/
public static final int OP_READ = 1;
/**
* Interest set mask bit for write operations.
*/
public static final int OP_WRITE = 4;
private volatile Object attachment = null;
/**
* Constructs a new {@code SelectionKey}.
*/
protected SelectionKey() {
}
/**
* Attaches an object to this key. It is acceptable to attach {@code null},
* this discards the old attachment.
*
* @param anObject
* the object to attach, or {@code null} to discard the current
* attachment.
* @return the last attached object or {@code null} if no object has been
* attached.
*/
public final Object attach(Object anObject) {
Object oldAttachment = attachment;
attachment = anObject;
return oldAttachment;
}
/**
* Gets the attached object.
*
* @return the attached object or {@code null} if no object has been
* attached.
*/
public final Object attachment() {
return attachment;
}
/**
* Cancels this key.
* <p>
* A key that has been canceled is no longer valid. Calling this method on
* an already canceled key does nothing.
* <p>
* Calling this method is safe at any time. The call might block until
* another ongoing call to a method of this selector has finished. The
* reason is that it is synchronizing on the key set of the selector. After
* this call finishes, the key will have been added to the selectors
* canceled-keys set and will not be included in any future selects of this
* selector.
*/
public abstract void cancel();
/**
* Gets the channel of this key.
*
* @return the channel of this key.
*/
public abstract SelectableChannel channel();
/**
* Gets this key's {@link SelectionKey interest set}. The returned set has
* only those bits set that are valid for this key's channel.
*
* @return the interest set of this key.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public abstract int interestOps();
/**
* Sets the {@link SelectionKey interest set} for this key.
*
* @param operations
* the new interest set.
* @return this key.
* @throws IllegalArgumentException
* if a bit in {@code operations} is not in the set of
* {@link SelectableChannel#validOps() valid operations} of this
* key's channel.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public abstract SelectionKey interestOps(int operations);
/**
* Indicates whether this key's channel is interested in the accept
* operation and is ready to accept new connections. A call to this method
* is equal to executing {@code (readyOps() & OP_ACCEPT) == OP_ACCEPT}.
*
* @return {@code true} if the channel is interested in the accept operation
* and is ready to accept new connections, {@code false} otherwise.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public final boolean isAcceptable() {
return (readyOps() & OP_ACCEPT) == OP_ACCEPT;
}
/**
* Indicates whether this key's channel is interested in the connect
* operation and is ready to connect. A call to this method is equal to
* executing {@code (readyOps() & OP_CONNECT) == OP_CONNECT}.
*
* @return {@code true} if the channel is interested in the connect
* operation and is ready to connect, {@code false} otherwise.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public final boolean isConnectable() {
return (readyOps() & OP_CONNECT) == OP_CONNECT;
}
/**
* Indicates whether this key's channel is interested in the read operation
* and is ready to read. A call to this method is equal to executing
* {@code (readyOps() & OP_READ) == OP_READ}.
*
* @return {@code true} if the channel is interested in the read operation
* and is ready to read, {@code false} otherwise.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public final boolean isReadable() {
return (readyOps() & OP_READ) == OP_READ;
}
/**
* Indicates whether this key is valid. A key is valid as long as it has not
* been canceled.
*
* @return {@code true} if this key has not been canceled, {@code false}
* otherwise.
*/
public abstract boolean isValid();
/**
* Indicates whether this key's channel is interested in the write operation
* and is ready to write. A call to this method is equal to executing
* {@code (readyOps() & OP_WRITE) == OP_WRITE}.
*
* @return {@code true} if the channel is interested in the write operation
* and is ready to write, {@code false} otherwise.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public final boolean isWritable() {
return (readyOps() & OP_WRITE) == OP_WRITE;
}
/**
* Gets the set of operations that are ready. The returned set has only
* those bits set that are valid for this key's channel.
*
* @return the operations for which this key's channel is ready.
* @throws CancelledKeyException
* if the key has already been canceled.
*/
public abstract int readyOps();
/**
* Gets the selector for which this key's channel is registered.
*
* @return the related selector.
*/
public abstract Selector selector();
}