001 /*
002 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.nio.channels;
027
028 import java.io.IOException;
029 import java.net.DatagramSocket;
030 import java.net.SocketAddress;
031 import java.nio.ByteBuffer;
032 import java.nio.channels.spi.*;
033
034 /**
035 * A selectable channel for datagram-oriented sockets.
036 *
037 *
038 * <p> Datagram channels are not a complete abstraction of network datagram
039 * sockets. Binding and the manipulation of socket options must be done
040 * through an associated {@link java.net.DatagramSocket} object obtained by
041 * invoking the {@link #socket() socket} method. It is not possible to create
042 * a channel for an arbitrary, pre-existing datagram socket, nor is it possible
043 * to specify the {@link java.net.DatagramSocketImpl} object to be used by a
044 * datagram socket associated with a datagram channel.
045 *
046 * <p> A datagram channel is created by invoking the {@link #open open} method
047 * of this class. A newly-created datagram channel is open but not connected.
048 * A datagram channel need not be connected in order for the {@link #send send}
049 * and {@link #receive receive} methods to be used. A datagram channel may be
050 * connected, by invoking its {@link #connect connect} method, in order to
051 * avoid the overhead of the security checks are otherwise performed as part of
052 * every send and receive operation. A datagram channel must be connected in
053 * order to use the {@link #read(java.nio.ByteBuffer) read} and {@link
054 * #write(java.nio.ByteBuffer) write} methods, since those methods do not
055 * accept or return socket addresses.
056 *
057 * <p> Once connected, a datagram channel remains connected until it is
058 * disconnected or closed. Whether or not a datagram channel is connected may
059 * be determined by invoking its {@link #isConnected isConnected} method.
060 *
061 * <p> Datagram channels are safe for use by multiple concurrent threads. They
062 * support concurrent reading and writing, though at most one thread may be
063 * reading and at most one thread may be writing at any given time. </p>
064 *
065 *
066 * @author Mark Reinhold
067 * @author JSR-51 Expert Group
068 * @version 1.39, 07/05/05
069 * @since 1.4
070 */
071
072 public abstract class DatagramChannel extends AbstractSelectableChannel
073 implements ByteChannel, ScatteringByteChannel,
074 GatheringByteChannel {
075
076 /**
077 * Initializes a new instance of this class.
078 */
079 protected DatagramChannel(SelectorProvider provider) {
080 super (provider);
081 }
082
083 /**
084 * Opens a datagram channel.
085 *
086 * <p> The new channel is created by invoking the {@link
087 * java.nio.channels.spi.SelectorProvider#openDatagramChannel()
088 * openDatagramChannel} method of the system-wide default {@link
089 * java.nio.channels.spi.SelectorProvider} object. The channel will not be
090 * connected. </p>
091 *
092 * @return A new datagram channel
093 *
094 * @throws IOException
095 * If an I/O error occurs
096 */
097 public static DatagramChannel open() throws IOException {
098 return SelectorProvider.provider().openDatagramChannel();
099 }
100
101 /**
102 * Returns an operation set identifying this channel's supported
103 * operations.
104 *
105 * <p> Datagram channels support reading and writing, so this method
106 * returns <tt>(</tt>{@link SelectionKey#OP_READ} <tt>|</tt> {@link
107 * SelectionKey#OP_WRITE}<tt>)</tt>. </p>
108 *
109 * @return The valid-operation set
110 */
111 public final int validOps() {
112 return (SelectionKey.OP_READ | SelectionKey.OP_WRITE);
113 }
114
115 // -- Socket-specific operations --
116
117 /**
118 * Retrieves a datagram socket associated with this channel.
119 *
120 * <p> The returned object will not declare any public methods that are not
121 * declared in the {@link java.net.DatagramSocket} class. </p>
122 *
123 * @return A datagram socket associated with this channel
124 */
125 public abstract DatagramSocket socket();
126
127 /**
128 * Tells whether or not this channel's socket is connected. </p>
129 *
130 * @return <tt>true</tt> if, and only if, this channel's socket
131 * is connected
132 */
133 public abstract boolean isConnected();
134
135 /**
136 * Connects this channel's socket.
137 *
138 * <p> The channel's socket is configured so that it only receives
139 * datagrams from, and sends datagrams to, the given remote <i>peer</i>
140 * address. Once connected, datagrams may not be received from or sent to
141 * any other address. A datagram socket remains connected until it is
142 * explicitly disconnected or until it is closed.
143 *
144 * <p> This method performs exactly the same security checks as the {@link
145 * java.net.DatagramSocket#connect connect} method of the {@link
146 * java.net.DatagramSocket} class. That is, if a security manager has been
147 * installed then this method verifies that its {@link
148 * java.lang.SecurityManager#checkAccept checkAccept} and {@link
149 * java.lang.SecurityManager#checkConnect checkConnect} methods permit
150 * datagrams to be received from and sent to, respectively, the given
151 * remote address.
152 *
153 * <p> This method may be invoked at any time. It will not have any effect
154 * on read or write operations that are already in progress at the moment
155 * that it is invoked. </p>
156 *
157 * @param remote
158 * The remote address to which this channel is to be connected
159 *
160 * @return This datagram channel
161 *
162 * @throws ClosedChannelException
163 * If this channel is closed
164 *
165 * @throws AsynchronousCloseException
166 * If another thread closes this channel
167 * while the connect operation is in progress
168 *
169 * @throws ClosedByInterruptException
170 * If another thread interrupts the current thread
171 * while the connect operation is in progress, thereby
172 * closing the channel and setting the current thread's
173 * interrupt status
174 *
175 * @throws SecurityException
176 * If a security manager has been installed
177 * and it does not permit access to the given remote address
178 *
179 * @throws IOException
180 * If some other I/O error occurs
181 */
182 public abstract DatagramChannel connect(SocketAddress remote)
183 throws IOException;
184
185 /**
186 * Disconnects this channel's socket.
187 *
188 * <p> The channel's socket is configured so that it can receive datagrams
189 * from, and sends datagrams to, any remote address so long as the security
190 * manager, if installed, permits it.
191 *
192 * <p> This method may be invoked at any time. It will not have any effect
193 * on read or write operations that are already in progress at the moment
194 * that it is invoked.
195 *
196 * <p> If this channel's socket is not connected, or if the channel is
197 * closed, then invoking this method has no effect. </p>
198 *
199 * @return This datagram channel
200 *
201 * @throws IOException
202 * If some other I/O error occurs
203 */
204 public abstract DatagramChannel disconnect() throws IOException;
205
206 /**
207 * Receives a datagram via this channel.
208 *
209 * <p> If a datagram is immediately available, or if this channel is in
210 * blocking mode and one eventually becomes available, then the datagram is
211 * copied into the given byte buffer and its source address is returned.
212 * If this channel is in non-blocking mode and a datagram is not
213 * immediately available then this method immediately returns
214 * <tt>null</tt>.
215 *
216 * <p> The datagram is transferred into the given byte buffer starting at
217 * its current position, as if by a regular {@link
218 * ReadableByteChannel#read(java.nio.ByteBuffer) read} operation. If there
219 * are fewer bytes remaining in the buffer than are required to hold the
220 * datagram then the remainder of the datagram is silently discarded.
221 *
222 * <p> This method performs exactly the same security checks as the {@link
223 * java.net.DatagramSocket#receive receive} method of the {@link
224 * java.net.DatagramSocket} class. That is, if the socket is not connected
225 * to a specific remote address and a security manager has been installed
226 * then for each datagram received this method verifies that the source's
227 * address and port number are permitted by the security manager's {@link
228 * java.lang.SecurityManager#checkAccept checkAccept} method. The overhead
229 * of this security check can be avoided by first connecting the socket via
230 * the {@link #connect connect} method.
231 *
232 * <p> This method may be invoked at any time. If another thread has
233 * already initiated a read operation upon this channel, however, then an
234 * invocation of this method will block until the first operation is
235 * complete. </p>
236 *
237 * @param dst
238 * The buffer into which the datagram is to be transferred
239 *
240 * @return The datagram's source address,
241 * or <tt>null</tt> if this channel is in non-blocking mode
242 * and no datagram was immediately available
243 *
244 * @throws ClosedChannelException
245 * If this channel is closed
246 *
247 * @throws AsynchronousCloseException
248 * If another thread closes this channel
249 * while the read operation is in progress
250 *
251 * @throws ClosedByInterruptException
252 * If another thread interrupts the current thread
253 * while the read operation is in progress, thereby
254 * closing the channel and setting the current thread's
255 * interrupt status
256 *
257 * @throws SecurityException
258 * If a security manager has been installed
259 * and it does not permit datagrams to be accepted
260 * from the datagram's sender
261 *
262 * @throws IOException
263 * If some other I/O error occurs
264 */
265 public abstract SocketAddress receive(ByteBuffer dst)
266 throws IOException;
267
268 /**
269 * Sends a datagram via this channel.
270 *
271 * <p> If this channel is in non-blocking mode and there is sufficient room
272 * in the underlying output buffer, or if this channel is in blocking mode
273 * and sufficient room becomes available, then the remaining bytes in the
274 * given buffer are transmitted as a single datagram to the given target
275 * address.
276 *
277 * <p> The datagram is transferred from the byte buffer as if by a regular
278 * {@link WritableByteChannel#write(java.nio.ByteBuffer) write} operation.
279 *
280 * <p> This method performs exactly the same security checks as the {@link
281 * java.net.DatagramSocket#send send} method of the {@link
282 * java.net.DatagramSocket} class. That is, if the socket is not connected
283 * to a specific remote address and a security manager has been installed
284 * then for each datagram sent this method verifies that the target address
285 * and port number are permitted by the security manager's {@link
286 * java.lang.SecurityManager#checkConnect checkConnect} method. The
287 * overhead of this security check can be avoided by first connecting the
288 * socket via the {@link #connect connect} method.
289 *
290 * <p> This method may be invoked at any time. If another thread has
291 * already initiated a write operation upon this channel, however, then an
292 * invocation of this method will block until the first operation is
293 * complete. </p>
294 *
295 * @param src
296 * The buffer containing the datagram to be sent
297 *
298 * @param target
299 * The address to which the datagram is to be sent
300 *
301 * @return The number of bytes sent, which will be either the number
302 * of bytes that were remaining in the source buffer when this
303 * method was invoked or, if this channel is non-blocking, may be
304 * zero if there was insufficient room for the datagram in the
305 * underlying output buffer
306 *
307 * @throws ClosedChannelException
308 * If this channel is closed
309 *
310 * @throws AsynchronousCloseException
311 * If another thread closes this channel
312 * while the read operation is in progress
313 *
314 * @throws ClosedByInterruptException
315 * If another thread interrupts the current thread
316 * while the read operation is in progress, thereby
317 * closing the channel and setting the current thread's
318 * interrupt status
319 *
320 * @throws SecurityException
321 * If a security manager has been installed
322 * and it does not permit datagrams to be sent
323 * to the given address
324 *
325 * @throws IOException
326 * If some other I/O error occurs
327 */
328 public abstract int send(ByteBuffer src, SocketAddress target)
329 throws IOException;
330
331 // -- ByteChannel operations --
332
333 /**
334 * Reads a datagram from this channel.
335 *
336 * <p> This method may only be invoked if this channel's socket is
337 * connected, and it only accepts datagrams from the socket's peer. If
338 * there are more bytes in the datagram than remain in the given buffer
339 * then the remainder of the datagram is silently discarded. Otherwise
340 * this method behaves exactly as specified in the {@link
341 * ReadableByteChannel} interface. </p>
342 *
343 * @throws NotYetConnectedException
344 * If this channel's socket is not connected
345 */
346 public abstract int read(ByteBuffer dst) throws IOException;
347
348 /**
349 * Reads a datagram from this channel.
350 *
351 * <p> This method may only be invoked if this channel's socket is
352 * connected, and it only accepts datagrams from the socket's peer. If
353 * there are more bytes in the datagram than remain in the given buffers
354 * then the remainder of the datagram is silently discarded. Otherwise
355 * this method behaves exactly as specified in the {@link
356 * ScatteringByteChannel} interface. </p>
357 *
358 * @throws NotYetConnectedException
359 * If this channel's socket is not connected
360 */
361 public abstract long read(ByteBuffer[] dsts, int offset, int length)
362 throws IOException;
363
364 /**
365 * Reads a datagram from this channel.
366 *
367 * <p> This method may only be invoked if this channel's socket is
368 * connected, and it only accepts datagrams from the socket's peer. If
369 * there are more bytes in the datagram than remain in the given buffers
370 * then the remainder of the datagram is silently discarded. Otherwise
371 * this method behaves exactly as specified in the {@link
372 * ScatteringByteChannel} interface. </p>
373 *
374 * @throws NotYetConnectedException
375 * If this channel's socket is not connected
376 */
377 public final long read(ByteBuffer[] dsts) throws IOException {
378 return read(dsts, 0, dsts.length);
379 }
380
381 /**
382 * Writes a datagram to this channel.
383 *
384 * <p> This method may only be invoked if this channel's socket is
385 * connected, in which case it sends datagrams directly to the socket's
386 * peer. Otherwise it behaves exactly as specified in the {@link
387 * WritableByteChannel} interface. </p>
388 *
389 * @throws NotYetConnectedException
390 * If this channel's socket is not connected
391 */
392 public abstract int write(ByteBuffer src) throws IOException;
393
394 /**
395 * Writes a datagram to this channel.
396 *
397 * <p> This method may only be invoked if this channel's socket is
398 * connected, in which case it sends datagrams directly to the socket's
399 * peer. Otherwise it behaves exactly as specified in the {@link
400 * GatheringByteChannel} interface. </p>
401 *
402 * @return The number of bytes sent, which will be either the number
403 * of bytes that were remaining in the source buffer when this
404 * method was invoked or, if this channel is non-blocking, may be
405 * zero if there was insufficient room for the datagram in the
406 * underlying output buffer
407 *
408 * @throws NotYetConnectedException
409 * If this channel's socket is not connected
410 */
411 public abstract long write(ByteBuffer[] srcs, int offset, int length)
412 throws IOException;
413
414 /**
415 * Writes a datagram to this channel.
416 *
417 * <p> This method may only be invoked if this channel's socket is
418 * connected, in which case it sends datagrams directly to the socket's
419 * peer. Otherwise it behaves exactly as specified in the {@link
420 * GatheringByteChannel} interface. </p>
421 *
422 * @return The number of bytes sent, which will be either the number
423 * of bytes that were remaining in the source buffer when this
424 * method was invoked or, if this channel is non-blocking, may be
425 * zero if there was insufficient room for the datagram in the
426 * underlying output buffer
427 *
428 * @throws NotYetConnectedException
429 * If this channel's socket is not connected
430 */
431 public final long write(ByteBuffer[] srcs) throws IOException {
432 return write(srcs, 0, srcs.length);
433 }
434
435 }
|