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