KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > nio > channels > SelectableChannel


1 /*
2  * @(#)SelectableChannel.java 1.34 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 JavaDoc;
11 import java.nio.channels.spi.AbstractInterruptibleChannel JavaDoc;
12 import java.nio.channels.spi.SelectorProvider JavaDoc;
13
14
15 /**
16  * A channel that can be multiplexed via a {@link Selector}.
17  *
18  * <p> In order to be used with a selector, an instance of this class must
19  * first be <i>registered</i> via the {@link #register(Selector,int,Object)
20  * register} method. This method returns a new {@link SelectionKey} object
21  * that represents the channel's registration with the selector.
22  *
23  * <p> Once registered with a selector, a channel remains registered until it
24  * is <i>deregistered</i>. This involves deallocating whatever resources were
25  * allocated to the channel by the selector.
26  *
27  * <p> A channel cannot be deregistered directly; instead, the key representing
28  * its registration must be <i>cancelled</i>. Cancelling a key requests that
29  * the channel be deregistered during the selector's next selection operation.
30  * A key may be cancelled explicitly by invoking its {@link
31  * SelectionKey#cancel() cancel} method. All of a channel's keys are cancelled
32  * implicitly when the channel is closed, whether by invoking its {@link
33  * Channel#close close} method or by interrupting a thread blocked in an I/O
34  * operation upon the channel.
35  *
36  * <p> If the selector itself is closed then the channel will be deregistered,
37  * and the key representing its registration will be invalidated, without
38  * further delay.
39  *
40  * <p> A channel may be registered at most once with any particular selector.
41  *
42  * <p> Whether or not a channel is registered with one or more selectors may be
43  * determined by invoking the {@link #isRegistered isRegistered} method.
44  *
45  * <p> Selectable channels are safe for use by multiple concurrent
46  * threads. </p>
47  *
48  *
49  * <a name="bm">
50  * <h4>Blocking mode</h4>
51  *
52  * A selectable channel is either in <i>blocking</i> mode or in
53  * <i>non-blocking</i> mode. In blocking mode, every I/O operation invoked
54  * upon the channel will block until it completes. In non-blocking mode an I/O
55  * operation will never block and may transfer fewer bytes than were requested
56  * or possibly no bytes at all. The blocking mode of a selectable channel may
57  * be determined by invoking its {@link #isBlocking isBlocking} method.
58  *
59  * <p> Newly-created selectable channels are always in blocking mode.
60  * Non-blocking mode is most useful in conjunction with selector-based
61  * multiplexing. A channel must be placed into non-blocking mode before being
62  * registered with a selector, and may not be returned to blocking mode until
63  * it has been deregistered.
64  *
65  *
66  * @author Mark Reinhold
67  * @author JSR-51 Expert Group
68  * @version 1.34, 03/12/19
69  * @since 1.4
70  *
71  * @see SelectionKey
72  * @see Selector
73  */
74
75 public abstract class SelectableChannel
76     extends AbstractInterruptibleChannel JavaDoc
77     implements Channel JavaDoc
78 {
79
80     /**
81      * Initializes a new instance of this class.
82      */
83     protected SelectableChannel() { }
84
85     /**
86      * Returns the provider that created this channel.
87      *
88      * @return The provider that created this channel
89      */
90     public abstract SelectorProvider JavaDoc provider();
91
92     /**
93      * Returns an <a HREF="SelectionKey.html#opsets">operation set</a>
94      * identifying this channel's supported operations. The bits that are set
95      * in this integer value denote exactly the operations that are valid for
96      * this channel. This method always returns the same value for a given
97      * concrete channel class. </p>
98      *
99      * @return The valid-operation set
100      */
101     public abstract int validOps();
102
103     // Internal state:
104 // keySet, may be empty but is never null, typ. a tiny array
105 // boolean isRegistered, protected by key set
106 // regLock, lock object to prevent duplicate registrations
107 // boolean isBlocking, protected by regLock
108
109     /**
110      * Tells whether or not this channel is currently registered with any
111      * selectors. A newly-created channel is not registered.
112      *
113      * <p> Due to the inherent delay between key cancellation and channel
114      * deregistration, a channel may remain registered for some time after all
115      * of its keys have been cancelled. A channel may also remain registered
116      * for some time after it is closed. </p>
117      *
118      * @return <tt>true</tt> if, and only if, this channel is registered
119      */
120     public abstract boolean isRegistered();
121     //
122 // sync(keySet) { return isRegistered; }
123
124     /**
125      * Retrieves the key representing the channel's registration with the given
126      * selector. </p>
127      *
128      * @return The key returned when this channel was last registered with the
129      * given selector, or <tt>null</tt> if this channel is not
130      * currently registered with that selector
131      */
132     public abstract SelectionKey JavaDoc keyFor(Selector JavaDoc sel);
133     //
134 // sync(keySet) { return findKey(sel); }
135
136     /**
137      * Registers this channel with the given selector, returning a selection
138      * key.
139      *
140      * <p> If this channel is currently registered with the given selector then
141      * the selection key representing that registration is returned. The key's
142      * interest set will have been changed to <tt>ops</tt>, as if by invoking
143      * the {@link SelectionKey#interestOps(int) interestOps(int)} method. If
144      * the <tt>att</tt> argument is not <tt>null</tt> then the key's attachment
145      * will have been set to that value. A {@link CancelledKeyException} will
146      * be thrown if the key has already been cancelled.
147      *
148      * <p> Otherwise this channel has not yet been registered with the given
149      * selector, so it is registered and the resulting new key is returned.
150      * The key's initial interest set will be <tt>ops</tt> and its attachment
151      * will be <tt>att</tt>.
152      *
153      * <p> This method may be invoked at any time. If this method is invoked
154      * while another invocation of this method or of the {@link
155      * #configureBlocking(boolean) configureBlocking} method is in progress
156      * then it will first block until the other operation is complete. This
157      * method will then synchronize on the selector's key set and therefore may
158      * block if invoked concurrently with another registration or selection
159      * operation involving the same selector. </p>
160      *
161      * <p> If this channel is closed while this operation is in progress then
162      * the key returned by this method will have been cancelled and will
163      * therefore be invalid. </p>
164      *
165      * @param sel
166      * The selector with which this channel is to be registered
167      *
168      * @param ops
169      * The interest set for the resulting key
170      *
171      * @param att
172      * The attachment for the resulting key; may be <tt>null</tt>
173      *
174      * @throws ClosedChannelException
175      * If this channel is closed
176      *
177      * @throws IllegalBlockingModeException
178      * If this channel is in blocking mode
179      *
180      * @throws IllegalSelectorException
181      * If this channel was not created by the same provider
182      * as the given selector
183      *
184      * @throws CancelledKeyException
185      * If this channel is currently registered with the given selector
186      * but the corresponding key has already been cancelled
187      *
188      * @throws IllegalArgumentException
189      * If a bit in the <tt>ops</tt> set does not correspond to an
190      * operation that is supported by this channel, that is, if
191      * <tt>set & ~validOps() != 0</tt>
192      *
193      * @return A key representing the registration of this channel with
194      * the given selector
195      */
196     public abstract SelectionKey JavaDoc register(Selector JavaDoc sel, int ops, Object JavaDoc att)
197     throws ClosedChannelException JavaDoc;
198     //
199 // sync(regLock) {
200 // sync(keySet) { look for selector }
201 // if (channel found) { set interest ops -- may block in selector;
202 // return key; }
203 // create new key -- may block somewhere in selector;
204 // sync(keySet) { add key; }
205 // attach(attachment);
206 // return key;
207 // }
208
209     /**
210      * Registers this channel with the given selector, returning a selection
211      * key.
212      *
213      * <p> An invocation of this convenience method of the form
214      *
215      * <blockquote><tt>sc.register(sel, ops)</tt></blockquote>
216      *
217      * behaves in exactly the same way as the invocation
218      *
219      * <blockquote><tt>sc.{@link
220      * #register(java.nio.channels.Selector,int,java.lang.Object)
221      * register}(sel, ops, null)</tt></blockquote>
222      *
223      * @param sel
224      * The selector with which this channel is to be registered
225      *
226      * @param ops
227      * The interest set for the resulting key
228      *
229      * @throws ClosedChannelException
230      * If this channel is closed
231      *
232      * @throws IllegalBlockingModeException
233      * If this channel is in blocking mode
234      *
235      * @throws IllegalSelectorException
236      * If this channel was not created by the same provider
237      * as the given selector
238      *
239      * @throws CancelledKeyException
240      * If this channel is currently registered with the given selector
241      * but the corresponding key has already been cancelled
242      *
243      * @throws IllegalArgumentException
244      * If a bit in <tt>ops</tt> does not correspond to an operation
245      * that is supported by this channel, that is, if <tt>set &
246      * ~validOps() != 0</tt>
247      *
248      * @return A key representing the registration of this channel with
249      * the given selector
250      */
251     public final SelectionKey JavaDoc register(Selector JavaDoc sel, int ops)
252     throws ClosedChannelException JavaDoc
253     {
254     return register(sel, ops, null);
255     }
256
257     /**
258      * Adjusts this channel's blocking mode.
259      *
260      * <p> If this channel is registered with one or more selectors then an
261      * attempt to place it into blocking mode will cause an {@link
262      * IllegalBlockingModeException} to be thrown.
263      *
264      * <p> This method may be invoked at any time. The new blocking mode will
265      * only affect I/O operations that are initiated after this method returns.
266      * For some implementations this may require blocking until all pending I/O
267      * operations are complete.
268      *
269      * <p> If this method is invoked while another invocation of this method or
270      * of the {@link #register(Selector, int) register} method is in progress
271      * then it will first block until the other operation is complete. </p>
272      *
273      * @param block If <tt>true</tt> then this channel will be placed in
274      * blocking mode; if <tt>false</tt> then it will be placed
275      * non-blocking mode
276      *
277      * @return This selectable channel
278      *
279      * @throws ClosedChannelException
280      * If this channel is closed
281      *
282      * @throws IllegalBlockingModeException
283      * If <tt>block</tt> is <tt>true</tt> and this channel is
284      * registered with one or more selectors
285      *
286      * @throws IOException
287      * If an I/O error occurs
288      */
289     public abstract SelectableChannel JavaDoc configureBlocking(boolean block)
290     throws IOException JavaDoc;
291     //
292 // sync(regLock) {
293 // sync(keySet) { throw IBME if block && isRegistered; }
294 // change mode;
295 // }
296
297     /**
298      * Tells whether or not every I/O operation on this channel will block
299      * until it completes. A newly-created channel is always in blocking mode.
300      *
301      * <p> If this channel is closed then the value returned by this method is
302      * not specified. </p>
303      *
304      * @return <tt>true</tt> if, and only if, this channel is in blocking mode
305      */
306     public abstract boolean isBlocking();
307
308     /**
309      * Retrieves the object upon which the {@link #configureBlocking
310      * configureBlocking} and {@link #register register} methods synchronize.
311      * This is often useful in the implementation of adaptors that require a
312      * specific blocking mode to be maintained for a short period of time.
313      * </p>
314      *
315      * @return The blocking-mode lock object
316      */
317     public abstract Object JavaDoc blockingLock();
318
319 }
320
Popular Tags