KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)DatagramChannel.java 1.32 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.net.DatagramSocket JavaDoc;
12 import java.net.SocketAddress JavaDoc;
13 import java.nio.ByteBuffer JavaDoc;
14 import java.nio.channels.spi.*;
15
16
17 /**
18  * A selectable channel for datagram-oriented sockets.
19  *
20  *
21  * <p> Datagram channels are not a complete abstraction of network datagram
22  * sockets. Binding and the manipulation of socket options must be done
23  * through an associated {@link java.net.DatagramSocket} object obtained by
24  * invoking the {@link #socket() socket} method. It is not possible to create
25  * a channel for an arbitrary, pre-existing datagram socket, nor is it possible
26  * to specify the {@link java.net.DatagramSocketImpl} object to be used by a
27  * datagram socket associated with a datagram channel.
28  *
29  * <p> A datagram channel is created by invoking the {@link #open open} method
30  * of this class. A newly-created datagram channel is open but not connected.
31  * A datagram channel need not be connected in order for the {@link #send send}
32  * and {@link #receive receive} methods to be used. A datagram channel may be
33  * connected, by invoking its {@link #connect connect} method, in order to
34  * avoid the overhead of the security checks are otherwise performed as part of
35  * every send and receive operation. A datagram channel must be connected in
36  * order to use the {@link #read(java.nio.ByteBuffer) read} and {@link
37  * #write(java.nio.ByteBuffer) write} methods, since those methods do not
38  * accept or return socket addresses.
39  *
40  * <p> Once connected, a datagram channel remains connected until it is
41  * disconnected or closed. Whether or not a datagram channel is connected may
42  * be determined by invoking its {@link #isConnected isConnected} method.
43  *
44  * <p> Datagram channels are safe for use by multiple concurrent threads. They
45  * support concurrent reading and writing, though at most one thread may be
46  * reading and at most one thread may be writing at any given time. </p>
47  *
48  *
49  * @author Mark Reinhold
50  * @author JSR-51 Expert Group
51  * @version 1.32, 03/12/19
52  * @since 1.4
53  */

54
55 public abstract class DatagramChannel
56     extends AbstractSelectableChannel
57     implements ByteChannel JavaDoc, ScatteringByteChannel JavaDoc, GatheringByteChannel JavaDoc
58 {
59
60     /**
61      * Initializes a new instance of this class.
62      */

63     protected DatagramChannel(SelectorProvider provider) {
64     super(provider);
65     }
66
67     /**
68      * Opens a datagram channel.
69      *
70      * <p> The new channel is created by invoking the {@link
71      * java.nio.channels.spi.SelectorProvider#openDatagramChannel()
72      * openDatagramChannel} method of the system-wide default {@link
73      * java.nio.channels.spi.SelectorProvider} object. The channel will not be
74      * connected. </p>
75      *
76      * @return A new datagram channel
77      *
78      * @throws IOException
79      * If an I/O error occurs
80      */

81     public static DatagramChannel JavaDoc open() throws IOException JavaDoc {
82     return SelectorProvider.provider().openDatagramChannel();
83     }
84
85     /**
86      * Returns an operation set identifying this channel's supported
87      * operations.
88      *
89      * <p> Datagram channels support reading and writing, so this method
90      * returns <tt>(</tt>{@link SelectionKey#OP_READ} <tt>|</tt>&nbsp;{@link
91      * SelectionKey#OP_WRITE}<tt>)</tt>. </p>
92      *
93      * @return The valid-operation set
94      */

95     public final int validOps() {
96     return (SelectionKey.OP_READ
97         | SelectionKey.OP_WRITE);
98     }
99
100
101     // -- Socket-specific operations --
102

103     /**
104      * Retrieves a datagram socket associated with this channel.
105      *
106      * <p> The returned object will not declare any public methods that are not
107      * declared in the {@link java.net.DatagramSocket} class. </p>
108      *
109      * @return A datagram socket associated with this channel
110      */

111     public abstract DatagramSocket JavaDoc socket();
112
113     /**
114      * Tells whether or not this channel's socket is connected. </p>
115      *
116      * @return <tt>true</tt> if, and only if, this channel's socket
117      * is connected
118      */

119     public abstract boolean isConnected();
120
121     /**
122      * Connects this channel's socket.
123      *
124      * <p> The channel's socket is configured so that it only receives
125      * datagrams from, and sends datagrams to, the given remote <i>peer</i>
126      * address. Once connected, datagrams may not be received from or sent to
127      * any other address. A datagram socket remains connected until it is
128      * explicitly disconnected or until it is closed.
129      *
130      * <p> This method performs exactly the same security checks as the {@link
131      * java.net.DatagramSocket#connect connect} method of the {@link
132      * java.net.DatagramSocket} class. That is, if a security manager has been
133      * installed then this method verifies that its {@link
134      * java.lang.SecurityManager#checkAccept checkAccept} and {@link
135      * java.lang.SecurityManager#checkConnect checkConnect} methods permit
136      * datagrams to be received from and sent to, respectively, the given
137      * remote address.
138      *
139      * <p> This method may be invoked at any time. It will not have any effect
140      * on read or write operations that are already in progress at the moment
141      * that it is invoked. </p>
142      *
143      * @param remote
144      * The remote address to which this channel is to be connected
145      *
146      * @return This datagram channel
147      *
148      * @throws ClosedChannelException
149      * If this channel is closed
150      *
151      * @throws AsynchronousCloseException
152      * If another thread closes this channel
153      * while the connect operation is in progress
154      *
155      * @throws ClosedByInterruptException
156      * If another thread interrupts the current thread
157      * while the connect operation is in progress, thereby
158      * closing the channel and setting the current thread's
159      * interrupt status
160      *
161      * @throws SecurityException
162      * If a security manager has been installed
163      * and it does not permit access to the given remote address
164      *
165      * @throws IOException
166      * If some other I/O error occurs
167      */

168     public abstract DatagramChannel JavaDoc connect(SocketAddress JavaDoc remote)
169     throws IOException JavaDoc;
170
171     /**
172      * Disconnects this channel's socket.
173      *
174      * <p> The channel's socket is configured so that it can receive datagrams
175      * from, and sends datagrams to, any remote address so long as the security
176      * manager, if installed, permits it.
177      *
178      * <p> This method may be invoked at any time. It will not have any effect
179      * on read or write operations that are already in progress at the moment
180      * that it is invoked.
181      *
182      * <p> If this channel's socket is not connected, or if the channel is
183      * closed, then invoking this method has no effect. </p>
184      *
185      * @return This datagram channel
186      *
187      * @throws IOException
188      * If some other I/O error occurs
189      */

190     public abstract DatagramChannel JavaDoc disconnect() throws IOException JavaDoc;
191
192     /**
193      * Receives a datagram via this channel.
194      *
195      * <p> If a datagram is immediately available, or if this channel is in
196      * blocking mode and one eventually becomes available, then the datagram is
197      * copied into the given byte buffer and its source address is returned.
198      * If this channel is in non-blocking mode and a datagram is not
199      * immediately available then this method immediately returns
200      * <tt>null</tt>.
201      *
202      * <p> The datagram is transferred into the given byte buffer starting at
203      * its current position, as if by a regular {@link
204      * ReadableByteChannel#read(java.nio.ByteBuffer) read} operation. If there
205      * are fewer bytes remaining in the buffer than are required to hold the
206      * datagram then the remainder of the datagram is silently discarded.
207      *
208      * <p> This method performs exactly the same security checks as the {@link
209      * java.net.DatagramSocket#receive receive} method of the {@link
210      * java.net.DatagramSocket} class. That is, if the socket is not connected
211      * to a specific remote address and a security manager has been installed
212      * then for each datagram received this method verifies that the source's
213      * address and port number are permitted by the security manager's {@link
214      * java.lang.SecurityManager#checkAccept checkAccept} method. The overhead
215      * of this security check can be avoided by first connecting the socket via
216      * the {@link #connect connect} method.
217      *
218      * <p> This method may be invoked at any time. If another thread has
219      * already initiated a read operation upon this channel, however, then an
220      * invocation of this method will block until the first operation is
221      * complete. </p>
222      *
223      * @param dst
224      * The buffer into which the datagram is to be transferred
225      *
226      * @return The datagram's source address,
227      * or <tt>null</tt> if this channel is in non-blocking mode
228      * and no datagram was immediately available
229      *
230      * @throws ClosedChannelException
231      * If this channel is closed
232      *
233      * @throws AsynchronousCloseException
234      * If another thread closes this channel
235      * while the read operation is in progress
236      *
237      * @throws ClosedByInterruptException
238      * If another thread interrupts the current thread
239      * while the read operation is in progress, thereby
240      * closing the channel and setting the current thread's
241      * interrupt status
242      *
243      * @throws SecurityException
244      * If a security manager has been installed
245      * and it does not permit datagrams to be accepted
246      * from the datagram's sender
247      *
248      * @throws IOException
249      * If some other I/O error occurs
250      */

251     public abstract SocketAddress JavaDoc receive(ByteBuffer JavaDoc dst) throws IOException JavaDoc;
252
253     /**
254      * Sends a datagram via this channel.
255      *
256      * <p> If this channel is in non-blocking mode and there is sufficient room
257      * in the underlying output buffer, or if this channel is in blocking mode
258      * and sufficient room becomes available, then the remaining bytes in the
259      * given buffer are transmitted as a single datagram to the given target
260      * address.
261      *
262      * <p> The datagram is transferred from the byte buffer as if by a regular
263      * {@link WritableByteChannel#write(java.nio.ByteBuffer) write} operation.
264      *
265      * <p> This method performs exactly the same security checks as the {@link
266      * java.net.DatagramSocket#send send} method of the {@link
267      * java.net.DatagramSocket} class. That is, if the socket is not connected
268      * to a specific remote address and a security manager has been installed
269      * then for each datagram sent this method verifies that the target address
270      * and port number are permitted by the security manager's {@link
271      * java.lang.SecurityManager#checkConnect checkConnect} method. The
272      * overhead of this security check can be avoided by first connecting the
273      * socket via the {@link #connect connect} method.
274      *
275      * <p> This method may be invoked at any time. If another thread has
276      * already initiated a write operation upon this channel, however, then an
277      * invocation of this method will block until the first operation is
278      * complete. </p>
279      *
280      * @param src
281      * The buffer containing the datagram to be sent
282      *
283      * @param target
284      * The address to which the datagram is to be sent
285      *
286      * @return The number of bytes sent, which will be either the number
287      * of bytes that were remaining in the source buffer when this
288      * method was invoked or, if this channel is non-blocking, may be
289      * zero if there was insufficient room for the datagram in the
290      * underlying output buffer
291      *
292      * @throws ClosedChannelException
293      * If this channel is closed
294      *
295      * @throws AsynchronousCloseException
296      * If another thread closes this channel
297      * while the read operation is in progress
298      *
299      * @throws ClosedByInterruptException
300      * If another thread interrupts the current thread
301      * while the read operation is in progress, thereby
302      * closing the channel and setting the current thread's
303      * interrupt status
304      *
305      * @throws SecurityException
306      * If a security manager has been installed
307      * and it does not permit datagrams to be sent
308      * to the given address
309      *
310      * @throws IOException
311      * If some other I/O error occurs
312      */

313     public abstract int send(ByteBuffer JavaDoc src, SocketAddress JavaDoc target)
314     throws IOException JavaDoc;
315
316
317     // -- ByteChannel operations --
318

319     /**
320      * Reads a datagram from this channel.
321      *
322      * <p> This method may only be invoked if this channel's socket is
323      * connected, and it only accepts datagrams from the socket's peer. If
324      * there are more bytes in the datagram than remain in the given buffer
325      * then the remainder of the datagram is silently discarded. Otherwise
326      * this method behaves exactly as specified in the {@link
327      * ReadableByteChannel} interface. </p>
328      *
329      * @throws NotYetConnectedException
330      * If this channel's socket is not connected
331      */

332     public abstract int read(ByteBuffer JavaDoc dst) throws IOException JavaDoc;
333
334     /**
335      * Reads a datagram from this channel.
336      *
337      * <p> This method may only be invoked if this channel's socket is
338      * connected, and it only accepts datagrams from the socket's peer. If
339      * there are more bytes in the datagram than remain in the given buffers
340      * then the remainder of the datagram is silently discarded. Otherwise
341      * this method behaves exactly as specified in the {@link
342      * ScatteringByteChannel} interface. </p>
343      *
344      * @throws NotYetConnectedException
345      * If this channel's socket is not connected
346      */

347     public abstract long read(ByteBuffer JavaDoc[] dsts, int offset, int length)
348     throws IOException JavaDoc;
349
350     /**
351      * Reads a datagram from this channel.
352      *
353      * <p> This method may only be invoked if this channel's socket is
354      * connected, and it only accepts datagrams from the socket's peer. If
355      * there are more bytes in the datagram than remain in the given buffers
356      * then the remainder of the datagram is silently discarded. Otherwise
357      * this method behaves exactly as specified in the {@link
358      * ScatteringByteChannel} interface. </p>
359      *
360      * @throws NotYetConnectedException
361      * If this channel's socket is not connected
362      */

363     public final long read(ByteBuffer JavaDoc[] dsts) throws IOException JavaDoc {
364     return read(dsts, 0, dsts.length);
365     }
366
367     /**
368      * Writes a datagram to this channel.
369      *
370      * <p> This method may only be invoked if this channel's socket is
371      * connected, in which case it sends datagrams directly to the socket's
372      * peer. Otherwise it behaves exactly as specified in the {@link
373      * WritableByteChannel} interface. </p>
374      *
375      * @throws NotYetConnectedException
376      * If this channel's socket is not connected
377      */

378     public abstract int write(ByteBuffer JavaDoc src) throws IOException JavaDoc;
379
380     /**
381      * Writes a datagram to this channel.
382      *
383      * <p> This method may only be invoked if this channel's socket is
384      * connected, in which case it sends datagrams directly to the socket's
385      * peer. Otherwise it behaves exactly as specified in the {@link
386      * GatheringByteChannel} interface. </p>
387      *
388      * @return The number of bytes sent, which will be either the number
389      * of bytes that were remaining in the source buffer when this
390      * method was invoked or, if this channel is non-blocking, may be
391      * zero if there was insufficient room for the datagram in the
392      * underlying output buffer
393      *
394      * @throws NotYetConnectedException
395      * If this channel's socket is not connected
396      */

397     public abstract long write(ByteBuffer JavaDoc[] srcs, int offset, int length)
398     throws IOException JavaDoc;
399
400     /**
401      * Writes a datagram to this channel.
402      *
403      * <p> This method may only be invoked if this channel's socket is
404      * connected, in which case it sends datagrams directly to the socket's
405      * peer. Otherwise it behaves exactly as specified in the {@link
406      * GatheringByteChannel} interface. </p>
407      *
408      * @return The number of bytes sent, which will be either the number
409      * of bytes that were remaining in the source buffer when this
410      * method was invoked or, if this channel is non-blocking, may be
411      * zero if there was insufficient room for the datagram in the
412      * underlying output buffer
413      *
414      * @throws NotYetConnectedException
415      * If this channel's socket is not connected
416      */

417     public final long write(ByteBuffer JavaDoc[] srcs) throws IOException JavaDoc {
418     return write(srcs, 0, srcs.length);
419     }
420
421 }
422
Popular Tags