In order to be used with a selector, an instance of this class must * first be registered via the {@link #register(Selector,int,Object) * register} method. This method returns a new {@link SelectionKey} object * that represents the channel's registration with the selector. * *
Once registered with a selector, a channel remains registered until it * is deregistered. This involves deallocating whatever resources were * allocated to the channel by the selector. * *
A channel cannot be deregistered directly; instead, the key representing * its registration must be cancelled. Cancelling a key requests that * the channel be deregistered during the selector's next selection operation. * A key may be cancelled explicitly by invoking its {@link * SelectionKey#cancel() cancel} method. All of a channel's keys are cancelled * implicitly when the channel is closed, whether by invoking its {@link * Channel#close close} method or by interrupting a thread blocked in an I/O * operation upon the channel. * *
If the selector itself is closed then the channel will be deregistered, * and the key representing its registration will be invalidated, without * further delay. * *
A channel may be registered at most once with any particular selector. * *
Whether or not a channel is registered with one or more selectors may be * determined by invoking the {@link #isRegistered isRegistered} method. * *
Selectable channels are safe for use by multiple concurrent * threads.
* * * *Newly-created selectable channels are always in blocking mode. * Non-blocking mode is most useful in conjunction with selector-based * multiplexing. A channel must be placed into non-blocking mode before being * registered with a selector, and may not be returned to blocking mode until * it has been deregistered. * * * @author Mark Reinhold * @author JSR-51 Expert Group * @since 1.4 * * @see SelectionKey * @see Selector */ public abstract class SelectableChannel extends AbstractInterruptibleChannel implements Channel { /** * Initializes a new instance of this class. */ protected SelectableChannel() { } /** * Returns the provider that created this channel. * * @return The provider that created this channel */ public abstract SelectorProvider provider(); /** * Returns an operation set * identifying this channel's supported operations. The bits that are set * in this integer value denote exactly the operations that are valid for * this channel. This method always returns the same value for a given * concrete channel class.
* * @return The valid-operation set */ public abstract int validOps(); // Internal state: // keySet, may be empty but is never null, typ. a tiny array // boolean isRegistered, protected by key set // regLock, lock object to prevent duplicate registrations // boolean isBlocking, protected by regLock /** * Tells whether or not this channel is currently registered with any * selectors. A newly-created channel is not registered. * *Due to the inherent delay between key cancellation and channel * deregistration, a channel may remain registered for some time after all * of its keys have been cancelled. A channel may also remain registered * for some time after it is closed.
* * @return true if, and only if, this channel is registered */ public abstract boolean isRegistered(); // // sync(keySet) { return isRegistered; } /** * Retrieves the key representing the channel's registration with the given * selector. * * @return The key returned when this channel was last registered with the * given selector, or null if this channel is not * currently registered with that selector */ public abstract SelectionKey keyFor(Selector sel); // // sync(keySet) { return findKey(sel); } /** * Registers this channel with the given selector, returning a selection * key. * *If this channel is currently registered with the given selector then * the selection key representing that registration is returned. The key's * interest set will have been changed to ops, as if by invoking * the {@link SelectionKey#interestOps(int) interestOps(int)} method. If * the att argument is not null then the key's attachment * will have been set to that value. A {@link CancelledKeyException} will * be thrown if the key has already been cancelled. * *
Otherwise this channel has not yet been registered with the given * selector, so it is registered and the resulting new key is returned. * The key's initial interest set will be ops and its attachment * will be att. * *
This method may be invoked at any time. If this method is invoked * while another invocation of this method or of the {@link * #configureBlocking(boolean) configureBlocking} method is in progress * then it will first block until the other operation is complete. This * method will then synchronize on the selector's key set and therefore may * block if invoked concurrently with another registration or selection * operation involving the same selector.
* *If this channel is closed while this operation is in progress then * the key returned by this method will have been cancelled and will * therefore be invalid.
* * @param sel * The selector with which this channel is to be registered * * @param ops * The interest set for the resulting key * * @param att * The attachment for the resulting key; may be null * * @throws ClosedChannelException * If this channel is closed * * @throws ClosedSelectorException * If the selector is closed * * @throws IllegalBlockingModeException * If this channel is in blocking mode * * @throws IllegalSelectorException * If this channel was not created by the same provider * as the given selector * * @throws CancelledKeyException * If this channel is currently registered with the given selector * but the corresponding key has already been cancelled * * @throws IllegalArgumentException * If a bit in the ops set does not correspond to an * operation that is supported by this channel, that is, if * set & ~validOps() != 0 * * @return A key representing the registration of this channel with * the given selector */ public abstract SelectionKey register(Selector sel, int ops, Object att) throws ClosedChannelException; // // sync(regLock) { // sync(keySet) { look for selector } // if (channel found) { set interest ops -- may block in selector; // return key; } // create new key -- may block somewhere in selector; // sync(keySet) { add key; } // attach(attachment); // return key; // } /** * Registers this channel with the given selector, returning a selection * key. * *An invocation of this convenience method of the form * *
sc.register(sel, ops)* * behaves in exactly the same way as the invocation * *
sc.{@link * #register(java.nio.channels.Selector,int,java.lang.Object) * register}(sel, ops, null)* * @param sel * The selector with which this channel is to be registered * * @param ops * The interest set for the resulting key * * @throws ClosedChannelException * If this channel is closed * * @throws ClosedSelectorException * If the selector is closed * * @throws IllegalBlockingModeException * If this channel is in blocking mode * * @throws IllegalSelectorException * If this channel was not created by the same provider * as the given selector * * @throws CancelledKeyException * If this channel is currently registered with the given selector * but the corresponding key has already been cancelled * * @throws IllegalArgumentException * If a bit in ops does not correspond to an operation * that is supported by this channel, that is, if set & * ~validOps() != 0 * * @return A key representing the registration of this channel with * the given selector */ public final SelectionKey register(Selector sel, int ops) throws ClosedChannelException { return register(sel, ops, null); } /** * Adjusts this channel's blocking mode. * *
If this channel is registered with one or more selectors then an * attempt to place it into blocking mode will cause an {@link * IllegalBlockingModeException} to be thrown. * *
This method may be invoked at any time. The new blocking mode will * only affect I/O operations that are initiated after this method returns. * For some implementations this may require blocking until all pending I/O * operations are complete. * *
If this method is invoked while another invocation of this method or * of the {@link #register(Selector, int) register} method is in progress * then it will first block until the other operation is complete.
* * @param block If true then this channel will be placed in * blocking mode; if false then it will be placed * non-blocking mode * * @return This selectable channel * * @throws ClosedChannelException * If this channel is closed * * @throws IllegalBlockingModeException * If block is true and this channel is * registered with one or more selectors * * @throws IOException * If an I/O error occurs */ public abstract SelectableChannel configureBlocking(boolean block) throws IOException; // // sync(regLock) { // sync(keySet) { throw IBME if block && isRegistered; } // change mode; // } /** * Tells whether or not every I/O operation on this channel will block * until it completes. A newly-created channel is always in blocking mode. * *If this channel is closed then the value returned by this method is * not specified.
* * @return true if, and only if, this channel is in blocking mode */ public abstract boolean isBlocking(); /** * Retrieves the object upon which the {@link #configureBlocking * configureBlocking} and {@link #register register} methods synchronize. * This is often useful in the implementation of adaptors that require a * specific blocking mode to be maintained for a short period of time. * * * @return The blocking-mode lock object */ public abstract Object blockingLock(); }