SelectionKey


1   /*
2    * @(#)SelectionKey.java    1.24 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.nio.channels;
9   
10  import java.io.IOException  ;
11  
12  
13  /**
14   * A token representing the registration of a {@link SelectableChannel} with a
15   * {@link Selector}.
16   *
17   * <p> A selection key is created each time a channel is registered with a
18   * selector.  A key remains valid until it is <i>cancelled</i> by invoking its
19   * {@link #cancel cancel} method, by closing its channel, or by closing its
20   * selector.  Cancelling a key does not immediately remove it from its
21   * selector; it is instead added to the selector's <a
22   * HREF="Selector.html#ks"><i>cancelled-key set</i></a> for removal during the
23   * next selection operation.  The validity of a key may be tested by invoking
24   * its {@link #isValid isValid} method.
25   *
26   * <a name="opsets">
27   *
28   * <p> A selection key contains two <i>operation sets</i> represented as
29   * integer values.  Each bit of an operation set denotes a category of
30   * selectable operations that are supported by the key's channel.
31   *
32   * <ul>
33   *
34   *   <li><p> The <i>interest set</i> determines which operation categories will
35   *   be tested for readiness the next time one of the selector's selection
36   *   methods is invoked.  The interest set is initialized with the value given
37   *   when the key is created; it may later be changed via the {@link
38   *   #interestOps(int)} method. </p></li>
39   *
40   *   <li><p> The <i>ready set</i> identifies the operation categories for which
41   *   the key's channel has been detected to be ready by the key's selector.
42   *   The ready set is initialized to zero when the key is created; it may later
43   *   be updated by the selector during a selection operation, but it cannot be
44   *   updated directly. </p></li>
45   *
46   * </ul>
47   *
48   * <p> That a selection key's ready set indicates that its channel is ready for
49   * some operation category is a hint, but not a guarantee, that an operation in
50   * such a category may be performed by a thread without causing the thread to
51   * block.  A ready set is most likely to be accurate immediately after the
52   * completion of a selection operation.  It is likely to be made inaccurate by
53   * external events and by I/O operations that are invoked upon the
54   * corresponding channel.
55   *
56   * <p> This class defines all known operation-set bits, but precisely which
57   * bits are supported by a given channel depends upon the type of the channel.
58   * Each subclass of {@link SelectableChannel} defines an {@link
59   * SelectableChannel#validOps() validOps()} method which returns a set
60   * identifying just those operations that are supported by the channel.  An
61   * attempt to set or test an operation-set bit that is not supported by a key's
62   * channel will result in an appropriate run-time exception.
63   *
64   * <p> It is often necessary to associate some application-specific data with a
65   * selection key, for example an object that represents the state of a
66   * higher-level protocol and handles readiness notifications in order to
67   * implement that protocol.  Selection keys therefore support the
68   * <i>attachment</i> of a single arbitrary object to a key.  An object can be
69   * attached via the {@link #attach attach} method and then later retrieved via
70   * the {@link #attachment attachment} method.
71   *
72   * <p> Selection keys are safe for use by multiple concurrent threads.  The
73   * operations of reading and writing the interest set will, in general, be
74   * synchronized with certain operations of the selector.  Exactly how this
75   * synchronization is performed is implementation-dependent: In a naive
76   * implementation, reading or writing the interest set may block indefinitely
77   * if a selection operation is already in progress; in a high-performance
78   * implementation, reading or writing the interest set may block briefly, if at
79   * all.  In any case, a selection operation will always use the interest-set
80   * value that was current at the moment that the operation began.  </p>
81   *
82   *
83   * @author Mark Reinhold
84   * @author JSR-51 Expert Group
85   * @version 1.24, 03/12/19
86   * @since 1.4
87   *
88   * @see SelectableChannel
89   * @see Selector
90   */
91  
92  public abstract class SelectionKey {
93  
94      /**
95       * Constructs an instance of this class.
96       */
97      protected SelectionKey() { }
98  
99  
100     // -- Channel and selector operations --
101 
102     /**
103      * Returns the channel for which this key was created.  This method will
104      * continue to return the channel even after the key is cancelled.  </p>
105      *
106      * @return  This key's channel
107      */
108     public abstract SelectableChannel   channel();
109 
110     /**
111      * Returns the selector for which this key was created.  This method will
112      * continue to return the selector even after the key is cancelled.  </p>
113      *
114      * @return  This key's selector
115      */
116     public abstract Selector   selector();
117 
118     /**
119      * Tells whether or not this key is valid.
120      *
121      * <p> A key is valid upon creation and remains so until it is cancelled,
122      * its channel is closed, or its selector is closed.  </p>
123      *
124      * @return  <tt>true</tt> if, and only if, this key is valid
125      */
126     public abstract boolean isValid();
127 
128     /**
129      * Requests that the registration of this key's channel with its selector
130      * be cancelled.  Upon return the key will be invalid and will have been
131      * added to its selector's cancelled-key set.  The key will be removed from
132      * all of the selector's key sets during the next selection operation.
133      *
134      * <p> If this key has already been cancelled then invoking this method has
135      * no effect.  Once cancelled, a key remains forever invalid. </p>
136      *
137      * <p> This method may be invoked at any time.  It synchronizes on the
138      * selector's cancelled-key set, and therefore may block briefly if invoked
139      * concurrently with a cancellation or selection operation involving the
140      * same selector.  </p>
141      */
142     public abstract void cancel();
143 
144 
145     // -- Operation-set accessors --
146 
147     /**
148      * Retrieves this key's interest set.
149      *
150      * <p> It is guaranteed that the returned set will only contain operation
151      * bits that are valid for this key's channel.
152      *
153      * <p> This method may be invoked at any time.  Whether or not it blocks,
154      * and for how long, is implementation-dependent.  </p>
155      *
156      * @return  This key's interest set
157      *
158      * @throws  CancelledKeyException
159      *          If this key has been cancelled
160      */
161     public abstract int interestOps();
162 
163     /**
164      * Sets this key's interest set to the given value.
165      *
166      * <p> This method may be invoked at any time.  Whether or not it blocks,
167      * and for how long, is implementation-dependent.  </p>
168      *
169      * @param  ops  The new interest set
170      *
171      * @return  This selection key
172      *
173      * @throws  IllegalArgumentException
174      *          If a bit in the set does not correspond to an operation that
175      *          is supported by this key's channel, that is, if
176      *          <tt>set & ~(channel().validOps()) != 0</tt>
177      *
178      * @throws  CancelledKeyException
179      *          If this key has been cancelled
180      */
181     public abstract SelectionKey   interestOps(int ops);
182 
183     /**
184      * Retrieves this key's ready-operation set.
185      *
186      * <p> It is guaranteed that the returned set will only contain operation
187      * bits that are valid for this key's channel.  </p>
188      *
189      * @return  This key's ready-operation set
190      *
191      * @throws  CancelledKeyException
192      *          If this key has been cancelled
193      */
194     public abstract int readyOps();
195 
196 
197     // -- Operation bits and bit-testing convenience methods --
198 
199     /**
200      * Operation-set bit for read operations.
201      *
202      * <p> Suppose that a selection key's interest set contains
203      * <tt>OP_READ</tt> at the start of a <a
204      * HREF="Selector.html#selop">selection operation</a>.  If the selector
205      * detects that the corresponding channel is ready for reading, has reached
206      * end-of-stream, has been remotely shut down for further reading, or has
207      * an error pending, then it will add <tt>OP_READ</tt> to the key's
208      * ready-operation set and add the key to its selected-key&nbsp;set.  </p>
209      */
210     public static final int OP_READ = 1 << 0;
211 
212     /**
213      * Operation-set bit for write operations.  </p>
214      *
215      * <p> Suppose that a selection key's interest set contains
216      * <tt>OP_WRITE</tt> at the start of a <a
217      * HREF="Selector.html#selop">selection operation</a>.  If the selector
218      * detects that the corresponding channel is ready for writing, has been
219      * remotely shut down for further writing, or has an error pending, then it
220      * will add <tt>OP_WRITE</tt> to the key's ready set and add the key to its
221      * selected-key&nbsp;set.  </p>
222      */
223     public static final int OP_WRITE = 1 << 2;
224 
225     /**
226      * Operation-set bit for socket-connect operations.  </p>
227      *
228      * <p> Suppose that a selection key's interest set contains
229      * <tt>OP_CONNECT</tt> at the start of a <a
230      * HREF="Selector.html#selop">selection operation</a>.  If the selector
231      * detects that the corresponding socket channel is ready to complete its
232      * connection sequence, or has an error pending, then it will add
233      * <tt>OP_CONNECT</tt> to the key's ready set and add the key to its
234      * selected-key&nbsp;set.  </p>
235      */
236     public static final int OP_CONNECT = 1 << 3;
237 
238     /**
239      * Operation-set bit for socket-accept operations.  </p>
240      *
241      * <p> Suppose that a selection key's interest set contains
242      * <tt>OP_ACCEPT</tt> at the start of a <a
243      * HREF="Selector.html#selop">selection operation</a>.  If the selector
244      * detects that the corresponding server-socket channel is ready to accept
245      * another connection, or has an error pending, then it will add
246      * <tt>OP_ACCEPT</tt> to the key's ready set and add the key to its
247      * selected-key&nbsp;set.  </p>
248      */
249     public static final int OP_ACCEPT = 1 << 4;
250 
251     /**
252      * Tests whether this key's channel is ready for reading.
253      *
254      * <p> An invocation of this method of the form <tt>k.isReadable()</tt>
255      * behaves in exactly the same way as the expression
256      *
257      * <blockquote><pre>
258      * k.readyOps()&nbsp;&amp;&nbsp;OP_READ&nbsp;!=&nbsp;0</pre></blockquote>
259      *
260      * <p> If this key's channel does not support read operations then this
261      * method always returns <tt>false</tt>.  </p>
262      *
263      * @return  <tt>true</tt> if, and only if,
264      *          <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_READ</tt> is
265      *          nonzero
266      *
267      * @throws  CancelledKeyException
268      *          If this key has been cancelled
269      */
270     public final boolean isReadable() {
271     return (readyOps() & OP_READ) != 0;
272     }
273 
274     /**
275      * Tests whether this key's channel is ready for writing.
276      *
277      * <p> An invocation of this method of the form <tt>k.isWritable()</tt>
278      * behaves in exactly the same way as the expression
279      *
280      * <blockquote><pre>
281      * k.readyOps()&nbsp;&amp;&nbsp;OP_WRITE&nbsp;!=&nbsp;0</pre></blockquote>
282      *
283      * <p> If this key's channel does not support write operations then this
284      * method always returns <tt>false</tt>.  </p>
285      *
286      * @return  <tt>true</tt> if, and only if,
287      *          <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_WRITE</tt>
288      *          is nonzero
289      *
290      * @throws  CancelledKeyException
291      *          If this key has been cancelled
292      */
293     public final boolean isWritable() {
294     return (readyOps() & OP_WRITE) != 0;
295     }
296 
297     /**
298      * Tests whether this key's channel has either finished, or failed to
299      * finish, its socket-connection operation.
300      *
301      * <p> An invocation of this method of the form <tt>k.isConnectable()</tt>
302      * behaves in exactly the same way as the expression
303      *
304      * <blockquote><pre>
305      * k.readyOps()&nbsp;&amp;&nbsp;OP_CONNECT&nbsp;!=&nbsp;0</pre></blockquote>
306      *
307      * <p> If this key's channel does not support socket-connect operations
308      * then this method always returns <tt>false</tt>.  </p>
309      *
310      * @return  <tt>true</tt> if, and only if,
311      *          <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_CONNECT</tt>
312      *          is nonzero
313      *
314      * @throws  CancelledKeyException
315      *          If this key has been cancelled
316      */
317     public final boolean isConnectable() {
318     return (readyOps() & OP_CONNECT) != 0;
319     }
320 
321     /**
322      * Tests whether this key's channel is ready to accept a new socket
323      * connection.
324      *
325      * <p> An invocation of this method of the form <tt>k.isAcceptable()</tt>
326      * behaves in exactly the same way as the expression
327      *
328      * <blockquote><pre>
329      * k.readyOps()&nbsp;&amp;&nbsp;OP_ACCEPT&nbsp;!=&nbsp;0</pre></blockquote>
330      *
331      * <p> If this key's channel does not support socket-accept operations then
332      * this method always returns <tt>false</tt>.  </p>
333      *
334      * @return  <tt>true</tt> if, and only if,
335      *          <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_ACCEPT</tt>
336      *          is nonzero
337      *
338      * @throws  CancelledKeyException
339      *          If this key has been cancelled
340      */
341     public final boolean isAcceptable() {
342     return (readyOps() & OP_ACCEPT) != 0;
343     }
344 
345 
346     // -- Attachments --
347 
348     private volatile Object   attachment = null;
349 
350     /**
351      * Attaches the given object to this key.
352      *
353      * <p> An attached object may later be retrieved via the {@link #attachment
354      * attachment} method.  Only one object may be attached at a time; invoking
355      * this method causes any previous attachment to be discarded.  The current
356      * attachment may be discarded by attaching <tt>null</tt>.  </p>
357      *
358      * @param  ob
359      *         The object to be attached; may be <tt>null</tt>
360      *
361      * @return  The previously-attached object, if any,
362      *          otherwise <tt>null</tt>
363      */
364     public final Object   attach(Object   ob) {
365     Object   a = attachment;
366     attachment = ob;
367     return a;
368     }
369 
370     /**
371      * Retrieves the current attachment.  </p>
372      *
373      * @return  The object currently attached to this key,
374      *          or <tt>null</tt> if there is no attachment
375      */
376     public final Object   attachment() {
377     return attachment;
378     }
379 
380 }
381
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags