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  ;
11  import java.net.DatagramSocket  ;
12  import java.net.SocketAddress  ;
13  import java.nio.ByteBuffer  ;
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  , ScatteringByteChannel  , GatheringByteChannel  
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   open() throws IOException   {
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   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   connect(SocketAddress   remote)
169     throws IOException  ;
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   disconnect() throws IOException  ;
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   receive(ByteBuffer   dst) throws IOException  ;
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   src, SocketAddress   target)
314     throws IOException  ;
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   dst) throws IOException  ;
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  [] dsts, int offset, int length)
348     throws IOException  ;
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  [] dsts) throws IOException   {
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   src) throws IOException  ;
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  [] srcs, int offset, int length)
398     throws IOException  ;
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  [] srcs) throws IOException   {
418     return write(srcs, 0, srcs.length);
419     }
420 
421 }
422
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags