content: /*
   * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.nio.channels;
  
  import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
  import java.io.IOException;
  
  
  /**
   * A token representing the registration of a {@link SelectableChannel} with a
   * {@link Selector}.
   *
   * <p> A selection key is created each time a channel is registered with a
   * selector.  A key remains valid until it is <i>cancelled</i> by invoking its
   * {@link #cancel cancel} method, by closing its channel, or by closing its
   * selector.  Cancelling a key does not immediately remove it from its
   * selector; it is instead added to the selector's <a
   * href="Selector.html#ks"><i>cancelled-key set</i></a> for removal during the
   * next selection operation.  The validity of a key may be tested by invoking
   * its {@link #isValid isValid} method.
   *
   * <a name="opsets"></a>
   *
   * <p> A selection key contains two <i>operation sets</i> represented as
   * integer values.  Each bit of an operation set denotes a category of
   * selectable operations that are supported by the key's channel.
   *
   * <ul>
   *
   *   <li><p> The <i>interest set</i> determines which operation categories will
   *   be tested for readiness the next time one of the selector's selection
   *   methods is invoked.  The interest set is initialized with the value given
   *   when the key is created; it may later be changed via the {@link
   *   #interestOps(int)} method. </p></li>
   *
   *   <li><p> The <i>ready set</i> identifies the operation categories for which
   *   the key's channel has been detected to be ready by the key's selector.
   *   The ready set is initialized to zero when the key is created; it may later
   *   be updated by the selector during a selection operation, but it cannot be
   *   updated directly. </p></li>
   *
   * </ul>
   *
   * <p> That a selection key's ready set indicates that its channel is ready for
   * some operation category is a hint, but not a guarantee, that an operation in
   * such a category may be performed by a thread without causing the thread to
   * block.  A ready set is most likely to be accurate immediately after the
   * completion of a selection operation.  It is likely to be made inaccurate by
   * external events and by I/O operations that are invoked upon the
   * corresponding channel.
   *
   * <p> This class defines all known operation-set bits, but precisely which
   * bits are supported by a given channel depends upon the type of the channel.
   * Each subclass of {@link SelectableChannel} defines an {@link
   * SelectableChannel#validOps() validOps()} method which returns a set
   * identifying just those operations that are supported by the channel.  An
   * attempt to set or test an operation-set bit that is not supported by a key's
   * channel will result in an appropriate run-time exception.
   *
   * <p> It is often necessary to associate some application-specific data with a
   * selection key, for example an object that represents the state of a
   * higher-level protocol and handles readiness notifications in order to
   * implement that protocol.  Selection keys therefore support the
   * <i>attachment</i> of a single arbitrary object to a key.  An object can be
   * attached via the {@link #attach attach} method and then later retrieved via
   * the {@link #attachment() attachment} method.
   *
   * <p> Selection keys are safe for use by multiple concurrent threads.  The
   * operations of reading and writing the interest set will, in general, be
   * synchronized with certain operations of the selector.  Exactly how this
   * synchronization is performed is implementation-dependent: In a naive
   * implementation, reading or writing the interest set may block indefinitely
   * if a selection operation is already in progress; in a high-performance
   * implementation, reading or writing the interest set may block briefly, if at
   * all.  In any case, a selection operation will always use the interest-set
   * value that was current at the moment that the operation began.  </p>
   *
   *
   * @author Mark Reinhold
   * @author JSR-51 Expert Group
   * @since 1.4
   *
   * @see SelectableChannel
   * @see Selector
   */
  
  public abstract class SelectionKey {
  
      /**
       * Constructs an instance of this class.
       */
      protected SelectionKey() { }
  
  
      // -- Channel and selector operations --
  
      /**
       * Returns the channel for which this key was created.  This method will
       * continue to return the channel even after the key is cancelled.
       *
       * @return  This key's channel
       */
      public abstract SelectableChannel channel();
  
      /**
       * Returns the selector for which this key was created.  This method will
       * continue to return the selector even after the key is cancelled.
       *
       * @return  This key's selector
       */
      public abstract Selector selector();
  
      /**
       * Tells whether or not this key is valid.
       *
       * <p> A key is valid upon creation and remains so until it is cancelled,
       * its channel is closed, or its selector is closed.  </p>
       *
       * @return  <tt>true</tt> if, and only if, this key is valid
       */
      public abstract boolean isValid();
  
      /**
       * Requests that the registration of this key's channel with its selector
       * be cancelled.  Upon return the key will be invalid and will have been
       * added to its selector's cancelled-key set.  The key will be removed from
       * all of the selector's key sets during the next selection operation.
       *
       * <p> If this key has already been cancelled then invoking this method has
       * no effect.  Once cancelled, a key remains forever invalid. </p>
       *
       * <p> This method may be invoked at any time.  It synchronizes on the
       * selector's cancelled-key set, and therefore may block briefly if invoked
       * concurrently with a cancellation or selection operation involving the
       * same selector.  </p>
       */
      public abstract void cancel();
  
  
      // -- Operation-set accessors --
  
      /**
       * Retrieves this key's interest set.
       *
       * <p> It is guaranteed that the returned set will only contain operation
       * bits that are valid for this key's channel.
       *
       * <p> This method may be invoked at any time.  Whether or not it blocks,
       * and for how long, is implementation-dependent.  </p>
       *
       * @return  This key's interest set
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public abstract int interestOps();
  
      /**
       * Sets this key's interest set to the given value.
       *
       * <p> This method may be invoked at any time.  Whether or not it blocks,
       * and for how long, is implementation-dependent.  </p>
       *
       * @param  ops  The new interest set
       *
       * @return  This selection key
       *
       * @throws  IllegalArgumentException
       *          If a bit in the set does not correspond to an operation that
       *          is supported by this key's channel, that is, if
       *          {@code (ops & ~channel().validOps()) != 0}
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public abstract SelectionKey interestOps(int ops);
  
      /**
       * Retrieves this key's ready-operation set.
       *
       * <p> It is guaranteed that the returned set will only contain operation
       * bits that are valid for this key's channel.  </p>
       *
       * @return  This key's ready-operation set
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public abstract int readyOps();
  
  
      // -- Operation bits and bit-testing convenience methods --
  
      /**
       * Operation-set bit for read operations.
       *
       * <p> Suppose that a selection key's interest set contains
       * <tt>OP_READ</tt> at the start of a <a
       * href="Selector.html#selop">selection operation</a>.  If the selector
       * detects that the corresponding channel is ready for reading, has reached
       * end-of-stream, has been remotely shut down for further reading, or has
       * an error pending, then it will add <tt>OP_READ</tt> to the key's
       * ready-operation set and add the key to its selected-key&nbsp;set.  </p>
       */
      public static final int OP_READ = 1 << 0;
  
      /**
       * Operation-set bit for write operations.
       *
       * <p> Suppose that a selection key's interest set contains
       * <tt>OP_WRITE</tt> at the start of a <a
       * href="Selector.html#selop">selection operation</a>.  If the selector
       * detects that the corresponding channel is ready for writing, has been
       * remotely shut down for further writing, or has an error pending, then it
       * will add <tt>OP_WRITE</tt> to the key's ready set and add the key to its
       * selected-key&nbsp;set.  </p>
       */
      public static final int OP_WRITE = 1 << 2;
  
      /**
       * Operation-set bit for socket-connect operations.
       *
       * <p> Suppose that a selection key's interest set contains
       * <tt>OP_CONNECT</tt> at the start of a <a
       * href="Selector.html#selop">selection operation</a>.  If the selector
       * detects that the corresponding socket channel is ready to complete its
       * connection sequence, or has an error pending, then it will add
       * <tt>OP_CONNECT</tt> to the key's ready set and add the key to its
       * selected-key&nbsp;set.  </p>
       */
      public static final int OP_CONNECT = 1 << 3;
  
      /**
       * Operation-set bit for socket-accept operations.
       *
       * <p> Suppose that a selection key's interest set contains
       * <tt>OP_ACCEPT</tt> at the start of a <a
       * href="Selector.html#selop">selection operation</a>.  If the selector
       * detects that the corresponding server-socket channel is ready to accept
       * another connection, or has an error pending, then it will add
       * <tt>OP_ACCEPT</tt> to the key's ready set and add the key to its
       * selected-key&nbsp;set.  </p>
       */
      public static final int OP_ACCEPT = 1 << 4;
  
      /**
       * Tests whether this key's channel is ready for reading.
       *
       * <p> An invocation of this method of the form <tt>k.isReadable()</tt>
       * behaves in exactly the same way as the expression
       *
       * <blockquote><pre>{@code
       * k.readyOps() & OP_READ != 0
       * }</pre></blockquote>
       *
       * <p> If this key's channel does not support read operations then this
       * method always returns <tt>false</tt>.  </p>
       *
       * @return  <tt>true</tt> if, and only if,
                  {@code readyOps() & OP_READ} is nonzero
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public final boolean isReadable() {
          return (readyOps() & OP_READ) != 0;
      }
  
      /**
       * Tests whether this key's channel is ready for writing.
       *
       * <p> An invocation of this method of the form <tt>k.isWritable()</tt>
       * behaves in exactly the same way as the expression
       *
       * <blockquote><pre>{@code
       * k.readyOps() & OP_WRITE != 0
       * }</pre></blockquote>
       *
       * <p> If this key's channel does not support write operations then this
       * method always returns <tt>false</tt>.  </p>
       *
       * @return  <tt>true</tt> if, and only if,
       *          {@code readyOps() & OP_WRITE} is nonzero
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public final boolean isWritable() {
          return (readyOps() & OP_WRITE) != 0;
      }
  
      /**
       * Tests whether this key's channel has either finished, or failed to
       * finish, its socket-connection operation.
       *
       * <p> An invocation of this method of the form <tt>k.isConnectable()</tt>
       * behaves in exactly the same way as the expression
       *
       * <blockquote><pre>{@code
       * k.readyOps() & OP_CONNECT != 0
       * }</pre></blockquote>
       *
       * <p> If this key's channel does not support socket-connect operations
       * then this method always returns <tt>false</tt>.  </p>
       *
       * @return  <tt>true</tt> if, and only if,
       *          {@code readyOps() & OP_CONNECT} is nonzero
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public final boolean isConnectable() {
          return (readyOps() & OP_CONNECT) != 0;
      }
  
      /**
       * Tests whether this key's channel is ready to accept a new socket
       * connection.
       *
       * <p> An invocation of this method of the form <tt>k.isAcceptable()</tt>
       * behaves in exactly the same way as the expression
       *
       * <blockquote><pre>{@code
       * k.readyOps() & OP_ACCEPT != 0
       * }</pre></blockquote>
       *
       * <p> If this key's channel does not support socket-accept operations then
       * this method always returns <tt>false</tt>.  </p>
       *
       * @return  <tt>true</tt> if, and only if,
       *          {@code readyOps() & OP_ACCEPT} is nonzero
       *
       * @throws  CancelledKeyException
       *          If this key has been cancelled
       */
      public final boolean isAcceptable() {
          return (readyOps() & OP_ACCEPT) != 0;
      }
  
  
      // -- Attachments --
  
      private volatile Object attachment = null;
  
      private static final AtomicReferenceFieldUpdater<SelectionKey,Object>
          attachmentUpdater = AtomicReferenceFieldUpdater.newUpdater(
              SelectionKey.class, Object.class, "attachment"
          );
  
      /**
       * Attaches the given object to this key.
       *
       * <p> An attached object may later be retrieved via the {@link #attachment()
       * attachment} method.  Only one object may be attached at a time; invoking
       * this method causes any previous attachment to be discarded.  The current
       * attachment may be discarded by attaching <tt>null</tt>.  </p>
       *
       * @param  ob
       *         The object to be attached; may be <tt>null</tt>
       *
       * @return  The previously-attached object, if any,
       *          otherwise <tt>null</tt>
       */
      public final Object attach(Object ob) {
          return attachmentUpdater.getAndSet(this, ob);
      }
  
      /**
       * Retrieves the current attachment.
       *
       * @return  The object currently attached to this key,
       *          or <tt>null</tt> if there is no attachment
       */
      public final Object attachment() {
          return attachment;
      }
  
  }
  