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 17 package java.nio.channels; 18 19 import java.io.IOException; 20 import java.nio.channels.spi.AbstractInterruptibleChannel; 21 import java.nio.channels.spi.SelectorProvider; 22 23 /** 24 * A channel that can be used with a {@link Selector}. The channel must be 25 * registered with a selector by calling one of the {@code register} methods, 26 * which return a {@link SelectionKey} object. In order to deregister a channel 27 * from a selector, its selection key must be canceled. This can be done 28 * explicitly by calling the {@link SelectionKey#cancel()} method but it is also 29 * done implicitly when the channel or the selector is closed. 30 * <p> 31 * A channel may be registered with several selectors at the same time but only 32 * once for any given selector. 33 */ 34 public abstract class SelectableChannel extends AbstractInterruptibleChannel 35 implements Channel { 36 37 /** 38 * Constructs a new {@code SelectableChannel}. 39 */ 40 protected SelectableChannel() { 41 } 42 43 /** 44 * Gets the blocking lock which synchronizes the {@code configureBlocking} 45 * and {@code register} methods. 46 * 47 * @return the blocking object as lock. 48 */ 49 public abstract Object blockingLock(); 50 51 /** 52 * Sets the blocking mode of this channel. A call to this method blocks if 53 * other calls to this method or to a {@code register} method are executing. 54 * The new blocking mode is valid for calls to other methods that are 55 * invoked after the call to this method. If other methods are already 56 * executing when this method is called, they still have the old mode and 57 * the call to this method might block depending on the implementation. 58 * 59 * @param block 60 * {@code true} for setting this channel's mode to blocking, 61 * {@code false} to set it to non-blocking. 62 * @return this channel. 63 * @throws ClosedChannelException 64 * if this channel is closed. 65 * @throws IllegalBlockingModeException 66 * if {@code block} is {@code true} and this channel has been 67 * registered with at least one selector. 68 * @throws IOException 69 * if an I/O error occurs. 70 */ 71 public abstract SelectableChannel configureBlocking(boolean block) 72 throws IOException; 73 74 /** 75 * Indicates whether this channel is in blocking mode. 76 * 77 * @return {@code true} if this channel is blocking, undefined if this 78 * channel is closed. 79 */ 80 public abstract boolean isBlocking(); 81 82 /** 83 * Indicates whether this channel is registered with at least one selector. 84 * 85 * @return {@code true} if this channel is registered, {@code false} 86 * otherwise. 87 */ 88 public abstract boolean isRegistered(); 89 90 /** 91 * Gets this channel's selection key for the specified selector. 92 * 93 * @param sel 94 * the selector with which this channel has been registered. 95 * @return the selection key for the channel or {@code null} if this channel 96 * has not been registered with {@code sel}. 97 */ 98 public abstract SelectionKey keyFor(Selector sel); 99 100 /** 101 * Gets the provider of this channel. 102 * 103 * @return the provider of this channel. 104 */ 105 public abstract SelectorProvider provider(); 106 107 /** 108 * Registers this channel with the specified selector for the specified 109 * interest set. If the channel is already registered with the selector, the 110 * corresponding selection key is returned but the 111 * {@link SelectionKey interest set} is updated to {@code operations}. The 112 * returned key is canceled if the channel is closed while registering is in 113 * progress. 114 * <p> 115 * Calling this method is valid at any time. If another thread executes this 116 * method or the {@code configureBlocking(boolean} method then this call is 117 * blocked until the other call finishes. After that, it will synchronize on 118 * the key set of the selector and thus may again block if other threads 119 * also hold locks on the key set of the same selector. 120 * <p> 121 * Calling this method is equivalent to calling 122 * {@code register(selector, operations, null)}. 123 * 124 * @param selector 125 * the selector with which to register this channel. 126 * @param operations 127 * this channel's {@link SelectionKey interest set}. 128 * @return the selection key for this registration. 129 * @throws ClosedChannelException 130 * if the channel is closed. 131 * @throws IllegalBlockingModeException 132 * if the channel is in blocking mode. 133 * @throws IllegalSelectorException 134 * if this channel does not have the same provider as the given 135 * selector. 136 * @throws CancelledKeyException 137 * if this channel is registered but its key has been canceled. 138 * @throws IllegalArgumentException 139 * if the operation given is not supported by this channel. 140 */ 141 public final SelectionKey register(Selector selector, int operations) 142 throws ClosedChannelException { 143 return register(selector, operations, null); 144 } 145 146 /** 147 * Registers this channel with the specified selector for the specified 148 * interest set and an object to attach. If the channel is already 149 * registered with the selector, the corresponding selection key is returned 150 * but its {@link SelectionKey interest set} is updated to {@code ops} and 151 * the attached object is updated to {@code att}. The returned key is 152 * canceled if the channel is closed while registering is in progress. 153 * <p> 154 * Calling this method is valid at any time. If another thread executes this 155 * method or the {@code configureBlocking(boolean)} method then this call is 156 * blocked until the other call finishes. After that, it will synchronize on 157 * the key set of the selector and thus may again block if other threads 158 * also hold locks on the key set of the same selector. 159 * 160 * @param sel 161 * the selector with which to register this channel. 162 * @param ops 163 * this channel's {@link SelectionKey interest set}. 164 * @param att 165 * the object to attach, can be {@code null}. 166 * @return the selection key for this registration. 167 * @throws ClosedChannelException 168 * if this channel is closed. 169 * @throws IllegalArgumentException 170 * if {@code ops} is not supported by this channel. 171 * @throws IllegalBlockingModeException 172 * if this channel is in blocking mode. 173 * @throws IllegalSelectorException 174 * if this channel does not have the same provider as the given 175 * selector. 176 * @throws CancelledKeyException 177 * if this channel is registered but its key has been canceled. 178 */ 179 public abstract SelectionKey register(Selector sel, int ops, Object att) 180 throws ClosedChannelException; 181 182 /** 183 * Gets the set of valid {@link SelectionKey operations} of this channel. 184 * Instances of a concrete channel class always return the same value. 185 * 186 * @return the set of operations that this channel supports. 187 */ 188 public abstract int validOps(); 189 } 190
