author | alanb |
Sun, 15 Feb 2009 12:25:54 +0000 | |
changeset 2057 | 3acf8e5e2ca0 |
parent 1247 | b4c26443dee5 |
child 2427 | f35f516befc3 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
2 |
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
7 |
* published by the Free Software Foundation. Sun designates this |
|
8 |
* particular file as subject to the "Classpath" exception as provided |
|
9 |
* by Sun in the LICENSE file that accompanied this code. |
|
10 |
* |
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
21 |
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 |
* CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 |
* have any questions. |
|
24 |
*/ |
|
25 |
||
26 |
package java.nio.channels; |
|
27 |
||
28 |
import java.io.IOException; |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
29 |
import java.net.ProtocolFamily; |
2 | 30 |
import java.net.DatagramSocket; |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
31 |
import java.net.SocketOption; |
2 | 32 |
import java.net.SocketAddress; |
33 |
import java.nio.ByteBuffer; |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
34 |
import java.nio.channels.spi.AbstractSelectableChannel; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
35 |
import java.nio.channels.spi.SelectorProvider; |
2 | 36 |
|
37 |
/** |
|
38 |
* A selectable channel for datagram-oriented sockets. |
|
39 |
* |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
40 |
* <p> A datagram channel is created by invoking one of the {@link #open open} methods |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
41 |
* of this class. It is not possible to create a channel for an arbitrary, |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
42 |
* pre-existing datagram socket. A newly-created datagram channel is open but not |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
43 |
* connected. A datagram channel need not be connected in order for the {@link #send |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
44 |
* send} and {@link #receive receive} methods to be used. A datagram channel may be |
2 | 45 |
* connected, by invoking its {@link #connect connect} method, in order to |
46 |
* avoid the overhead of the security checks are otherwise performed as part of |
|
47 |
* every send and receive operation. A datagram channel must be connected in |
|
48 |
* order to use the {@link #read(java.nio.ByteBuffer) read} and {@link |
|
49 |
* #write(java.nio.ByteBuffer) write} methods, since those methods do not |
|
50 |
* accept or return socket addresses. |
|
51 |
* |
|
52 |
* <p> Once connected, a datagram channel remains connected until it is |
|
53 |
* disconnected or closed. Whether or not a datagram channel is connected may |
|
54 |
* be determined by invoking its {@link #isConnected isConnected} method. |
|
55 |
* |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
56 |
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object) |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
57 |
* setOption} method. A datagram channel to an Internet Protocol socket supports |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
58 |
* the following options: |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
59 |
* <blockquote> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
60 |
* <table border> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
61 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
62 |
* <th>Option Name</th> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
63 |
* <th>Description</th> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
64 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
65 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
66 |
* <td> {@link java.net.StandardSocketOption#SO_SNDBUF SO_SNDBUF} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
67 |
* <td> The size of the socket send buffer </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
68 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
69 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
70 |
* <td> {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
71 |
* <td> The size of the socket receive buffer </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
72 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
73 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
74 |
* <td> {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
75 |
* <td> Re-use address </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
76 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
77 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
78 |
* <td> {@link java.net.StandardSocketOption#SO_BROADCAST SO_BROADCAST} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
79 |
* <td> Allow transmission of broadcast datagrams </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
80 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
81 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
82 |
* <td> {@link java.net.StandardSocketOption#IP_TOS IP_TOS} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
83 |
* <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
84 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
85 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
86 |
* <td> {@link java.net.StandardSocketOption#IP_MULTICAST_IF IP_MULTICAST_IF} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
87 |
* <td> The network interface for Internet Protocol (IP) multicast datagrams </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
88 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
89 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
90 |
* <td> {@link java.net.StandardSocketOption#IP_MULTICAST_TTL |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
91 |
* IP_MULTICAST_TTL} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
92 |
* <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
93 |
* datagrams </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
94 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
95 |
* <tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
96 |
* <td> {@link java.net.StandardSocketOption#IP_MULTICAST_LOOP |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
97 |
* IP_MULTICAST_LOOP} </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
98 |
* <td> Loopback for Internet Protocol (IP) multicast datagrams </td> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
99 |
* </tr> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
100 |
* </table> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
101 |
* </blockquote> |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
102 |
* Additional (implementation specific) options may also be supported. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
103 |
* |
2 | 104 |
* <p> Datagram channels are safe for use by multiple concurrent threads. They |
105 |
* support concurrent reading and writing, though at most one thread may be |
|
106 |
* reading and at most one thread may be writing at any given time. </p> |
|
107 |
* |
|
108 |
* @author Mark Reinhold |
|
109 |
* @author JSR-51 Expert Group |
|
110 |
* @since 1.4 |
|
111 |
*/ |
|
112 |
||
113 |
public abstract class DatagramChannel |
|
114 |
extends AbstractSelectableChannel |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
115 |
implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, MulticastChannel |
2 | 116 |
{ |
117 |
||
118 |
/** |
|
119 |
* Initializes a new instance of this class. |
|
120 |
*/ |
|
121 |
protected DatagramChannel(SelectorProvider provider) { |
|
122 |
super(provider); |
|
123 |
} |
|
124 |
||
125 |
/** |
|
126 |
* Opens a datagram channel. |
|
127 |
* |
|
128 |
* <p> The new channel is created by invoking the {@link |
|
129 |
* java.nio.channels.spi.SelectorProvider#openDatagramChannel() |
|
130 |
* openDatagramChannel} method of the system-wide default {@link |
|
131 |
* java.nio.channels.spi.SelectorProvider} object. The channel will not be |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
132 |
* connected. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
133 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
134 |
* <p> The {@link ProtocolFamily ProtocolFamily} of the channel's socket |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
135 |
* is platform (and possibly configuration) dependent and therefore unspecified. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
136 |
* The {@link #open(ProtocolFamily) open} allows the protocol family to be |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
137 |
* selected when opening a datagram channel, and should be used to open |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
138 |
* datagram channels that are intended for Internet Protocol multicasting. |
2 | 139 |
* |
140 |
* @return A new datagram channel |
|
141 |
* |
|
142 |
* @throws IOException |
|
143 |
* If an I/O error occurs |
|
144 |
*/ |
|
145 |
public static DatagramChannel open() throws IOException { |
|
146 |
return SelectorProvider.provider().openDatagramChannel(); |
|
147 |
} |
|
148 |
||
149 |
/** |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
150 |
* Opens a datagram channel. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
151 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
152 |
* <p> The {@code family} parameter is used to specify the {@link |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
153 |
* ProtocolFamily}. If the datagram channel is to be used for IP multicasing |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
154 |
* then this should correspond to the address type of the multicast groups |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
155 |
* that this channel will join. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
156 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
157 |
* <p> The new channel is created by invoking the {@link |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
158 |
* java.nio.channels.spi.SelectorProvider#openDatagramChannel(ProtocolFamily) |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
159 |
* openDatagramChannel} method of the system-wide default {@link |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
160 |
* java.nio.channels.spi.SelectorProvider} object. The channel will not be |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
161 |
* connected. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
162 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
163 |
* @param family |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
164 |
* The protocol family |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
165 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
166 |
* @return A new datagram channel |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
167 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
168 |
* @throws UnsupportedOperationException |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
169 |
* If the specified protocol family is not supported. For example, |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
170 |
* suppose the parameter is specified as {@link |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
171 |
* java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
172 |
* but IPv6 is not enabled on the platform. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
173 |
* @throws IOException |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
174 |
* If an I/O error occurs |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
175 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
176 |
* @since 1.7 |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
177 |
*/ |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
178 |
public static DatagramChannel open(ProtocolFamily family) throws IOException { |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
179 |
return SelectorProvider.provider().openDatagramChannel(family); |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
180 |
} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
181 |
|
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
182 |
/** |
2 | 183 |
* Returns an operation set identifying this channel's supported |
184 |
* operations. |
|
185 |
* |
|
186 |
* <p> Datagram channels support reading and writing, so this method |
|
187 |
* returns <tt>(</tt>{@link SelectionKey#OP_READ} <tt>|</tt> {@link |
|
188 |
* SelectionKey#OP_WRITE}<tt>)</tt>. </p> |
|
189 |
* |
|
190 |
* @return The valid-operation set |
|
191 |
*/ |
|
192 |
public final int validOps() { |
|
193 |
return (SelectionKey.OP_READ |
|
194 |
| SelectionKey.OP_WRITE); |
|
195 |
} |
|
196 |
||
197 |
||
198 |
// -- Socket-specific operations -- |
|
199 |
||
200 |
/** |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
201 |
* @throws AlreadyBoundException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
202 |
* @throws UnsupportedAddressTypeException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
203 |
* @throws ClosedChannelException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
204 |
* @throws IOException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
205 |
* @throws SecurityException |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
206 |
* If a security manager has been installed and its {@link |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
207 |
* SecurityManager#checkListen checkListen} method denies the |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
208 |
* operation |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
209 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
210 |
* @since 1.7 |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
211 |
*/ |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
212 |
public abstract DatagramChannel bind(SocketAddress local) |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
213 |
throws IOException; |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
214 |
|
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
215 |
/** |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
216 |
* @throws UnsupportedOperationException {@inheritDoc} |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
217 |
* @throws IllegalArgumentException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
218 |
* @throws ClosedChannelException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
219 |
* @throws IOException {@inheritDoc} |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
220 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
221 |
* @since 1.7 |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
222 |
*/ |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
223 |
public abstract <T> DatagramChannel setOption(SocketOption<T> name, T value) |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
224 |
throws IOException; |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
225 |
|
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
226 |
/** |
2 | 227 |
* Retrieves a datagram socket associated with this channel. |
228 |
* |
|
229 |
* <p> The returned object will not declare any public methods that are not |
|
230 |
* declared in the {@link java.net.DatagramSocket} class. </p> |
|
231 |
* |
|
232 |
* @return A datagram socket associated with this channel |
|
233 |
*/ |
|
234 |
public abstract DatagramSocket socket(); |
|
235 |
||
236 |
/** |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
237 |
* Tells whether or not this channel's socket is connected. |
2 | 238 |
* |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
239 |
* @return {@code true} if, and only if, this channel's socket |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
240 |
* is {@link #isOpen open} and connected |
2 | 241 |
*/ |
242 |
public abstract boolean isConnected(); |
|
243 |
||
244 |
/** |
|
245 |
* Connects this channel's socket. |
|
246 |
* |
|
247 |
* <p> The channel's socket is configured so that it only receives |
|
248 |
* datagrams from, and sends datagrams to, the given remote <i>peer</i> |
|
249 |
* address. Once connected, datagrams may not be received from or sent to |
|
250 |
* any other address. A datagram socket remains connected until it is |
|
251 |
* explicitly disconnected or until it is closed. |
|
252 |
* |
|
253 |
* <p> This method performs exactly the same security checks as the {@link |
|
254 |
* java.net.DatagramSocket#connect connect} method of the {@link |
|
255 |
* java.net.DatagramSocket} class. That is, if a security manager has been |
|
256 |
* installed then this method verifies that its {@link |
|
257 |
* java.lang.SecurityManager#checkAccept checkAccept} and {@link |
|
258 |
* java.lang.SecurityManager#checkConnect checkConnect} methods permit |
|
259 |
* datagrams to be received from and sent to, respectively, the given |
|
260 |
* remote address. |
|
261 |
* |
|
262 |
* <p> This method may be invoked at any time. It will not have any effect |
|
263 |
* on read or write operations that are already in progress at the moment |
|
264 |
* that it is invoked. </p> |
|
265 |
* |
|
266 |
* @param remote |
|
267 |
* The remote address to which this channel is to be connected |
|
268 |
* |
|
269 |
* @return This datagram channel |
|
270 |
* |
|
271 |
* @throws ClosedChannelException |
|
272 |
* If this channel is closed |
|
273 |
* |
|
274 |
* @throws AsynchronousCloseException |
|
275 |
* If another thread closes this channel |
|
276 |
* while the connect operation is in progress |
|
277 |
* |
|
278 |
* @throws ClosedByInterruptException |
|
279 |
* If another thread interrupts the current thread |
|
280 |
* while the connect operation is in progress, thereby |
|
281 |
* closing the channel and setting the current thread's |
|
282 |
* interrupt status |
|
283 |
* |
|
284 |
* @throws SecurityException |
|
285 |
* If a security manager has been installed |
|
286 |
* and it does not permit access to the given remote address |
|
287 |
* |
|
288 |
* @throws IOException |
|
289 |
* If some other I/O error occurs |
|
290 |
*/ |
|
291 |
public abstract DatagramChannel connect(SocketAddress remote) |
|
292 |
throws IOException; |
|
293 |
||
294 |
/** |
|
295 |
* Disconnects this channel's socket. |
|
296 |
* |
|
297 |
* <p> The channel's socket is configured so that it can receive datagrams |
|
298 |
* from, and sends datagrams to, any remote address so long as the security |
|
299 |
* manager, if installed, permits it. |
|
300 |
* |
|
301 |
* <p> This method may be invoked at any time. It will not have any effect |
|
302 |
* on read or write operations that are already in progress at the moment |
|
303 |
* that it is invoked. |
|
304 |
* |
|
305 |
* <p> If this channel's socket is not connected, or if the channel is |
|
306 |
* closed, then invoking this method has no effect. </p> |
|
307 |
* |
|
308 |
* @return This datagram channel |
|
309 |
* |
|
310 |
* @throws IOException |
|
311 |
* If some other I/O error occurs |
|
312 |
*/ |
|
313 |
public abstract DatagramChannel disconnect() throws IOException; |
|
314 |
||
315 |
/** |
|
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
316 |
* Returns the remote address to which this channel's socket is connected. |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
317 |
* |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
318 |
* @return The remote address; {@code null} if the channel's socket is not |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
319 |
* connected |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
320 |
* |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
321 |
* @throws ClosedChannelException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
322 |
* If the channel is closed |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
323 |
* @throws IOException |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
324 |
* If an I/O error occurs |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
325 |
* |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
326 |
* @since 1.7 |
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
327 |
*/ |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1247
diff
changeset
|
328 |
public abstract SocketAddress getRemoteAddress() throws IOException; |
1152
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
329 |
|
29d6145d1097
4640544: New I/O: Complete socket-channel functionality
alanb
parents:
2
diff
changeset
|
330 |
/** |
2 | 331 |
* Receives a datagram via this channel. |
332 |
* |
|
333 |
* <p> If a datagram is immediately available, or if this channel is in |
|
334 |
* blocking mode and one eventually becomes available, then the datagram is |
|
335 |
* copied into the given byte buffer and its source address is returned. |
|
336 |
* If this channel is in non-blocking mode and a datagram is not |
|
337 |
* immediately available then this method immediately returns |
|
338 |
* <tt>null</tt>. |
|
339 |
* |
|
340 |
* <p> The datagram is transferred into the given byte buffer starting at |
|
341 |
* its current position, as if by a regular {@link |
|
342 |
* ReadableByteChannel#read(java.nio.ByteBuffer) read} operation. If there |
|
343 |
* are fewer bytes remaining in the buffer than are required to hold the |
|
344 |
* datagram then the remainder of the datagram is silently discarded. |
|
345 |
* |
|
346 |
* <p> This method performs exactly the same security checks as the {@link |
|
347 |
* java.net.DatagramSocket#receive receive} method of the {@link |
|
348 |
* java.net.DatagramSocket} class. That is, if the socket is not connected |
|
349 |
* to a specific remote address and a security manager has been installed |
|
350 |
* then for each datagram received this method verifies that the source's |
|
351 |
* address and port number are permitted by the security manager's {@link |
|
352 |
* java.lang.SecurityManager#checkAccept checkAccept} method. The overhead |
|
353 |
* of this security check can be avoided by first connecting the socket via |
|
354 |
* the {@link #connect connect} method. |
|
355 |
* |
|
356 |
* <p> This method may be invoked at any time. If another thread has |
|
357 |
* already initiated a read operation upon this channel, however, then an |
|
358 |
* invocation of this method will block until the first operation is |
|
359 |
* complete. </p> |
|
360 |
* |
|
361 |
* @param dst |
|
362 |
* The buffer into which the datagram is to be transferred |
|
363 |
* |
|
364 |
* @return The datagram's source address, |
|
365 |
* or <tt>null</tt> if this channel is in non-blocking mode |
|
366 |
* and no datagram was immediately available |
|
367 |
* |
|
368 |
* @throws ClosedChannelException |
|
369 |
* If this channel is closed |
|
370 |
* |
|
371 |
* @throws AsynchronousCloseException |
|
372 |
* If another thread closes this channel |
|
373 |
* while the read operation is in progress |
|
374 |
* |
|
375 |
* @throws ClosedByInterruptException |
|
376 |
* If another thread interrupts the current thread |
|
377 |
* while the read operation is in progress, thereby |
|
378 |
* closing the channel and setting the current thread's |
|
379 |
* interrupt status |
|
380 |
* |
|
381 |
* @throws SecurityException |
|
382 |
* If a security manager has been installed |
|
383 |
* and it does not permit datagrams to be accepted |
|
384 |
* from the datagram's sender |
|
385 |
* |
|
386 |
* @throws IOException |
|
387 |
* If some other I/O error occurs |
|
388 |
*/ |
|
389 |
public abstract SocketAddress receive(ByteBuffer dst) throws IOException; |
|
390 |
||
391 |
/** |
|
392 |
* Sends a datagram via this channel. |
|
393 |
* |
|
394 |
* <p> If this channel is in non-blocking mode and there is sufficient room |
|
395 |
* in the underlying output buffer, or if this channel is in blocking mode |
|
396 |
* and sufficient room becomes available, then the remaining bytes in the |
|
397 |
* given buffer are transmitted as a single datagram to the given target |
|
398 |
* address. |
|
399 |
* |
|
400 |
* <p> The datagram is transferred from the byte buffer as if by a regular |
|
401 |
* {@link WritableByteChannel#write(java.nio.ByteBuffer) write} operation. |
|
402 |
* |
|
403 |
* <p> This method performs exactly the same security checks as the {@link |
|
404 |
* java.net.DatagramSocket#send send} method of the {@link |
|
405 |
* java.net.DatagramSocket} class. That is, if the socket is not connected |
|
406 |
* to a specific remote address and a security manager has been installed |
|
407 |
* then for each datagram sent this method verifies that the target address |
|
408 |
* and port number are permitted by the security manager's {@link |
|
409 |
* java.lang.SecurityManager#checkConnect checkConnect} method. The |
|
410 |
* overhead of this security check can be avoided by first connecting the |
|
411 |
* socket via the {@link #connect connect} method. |
|
412 |
* |
|
413 |
* <p> This method may be invoked at any time. If another thread has |
|
414 |
* already initiated a write operation upon this channel, however, then an |
|
415 |
* invocation of this method will block until the first operation is |
|
416 |
* complete. </p> |
|
417 |
* |
|
418 |
* @param src |
|
419 |
* The buffer containing the datagram to be sent |
|
420 |
* |
|
421 |
* @param target |
|
422 |
* The address to which the datagram is to be sent |
|
423 |
* |
|
424 |
* @return The number of bytes sent, which will be either the number |
|
425 |
* of bytes that were remaining in the source buffer when this |
|
426 |
* method was invoked or, if this channel is non-blocking, may be |
|
427 |
* zero if there was insufficient room for the datagram in the |
|
428 |
* underlying output buffer |
|
429 |
* |
|
430 |
* @throws ClosedChannelException |
|
431 |
* If this channel is closed |
|
432 |
* |
|
433 |
* @throws AsynchronousCloseException |
|
434 |
* If another thread closes this channel |
|
435 |
* while the read operation is in progress |
|
436 |
* |
|
437 |
* @throws ClosedByInterruptException |
|
438 |
* If another thread interrupts the current thread |
|
439 |
* while the read operation is in progress, thereby |
|
440 |
* closing the channel and setting the current thread's |
|
441 |
* interrupt status |
|
442 |
* |
|
443 |
* @throws SecurityException |
|
444 |
* If a security manager has been installed |
|
445 |
* and it does not permit datagrams to be sent |
|
446 |
* to the given address |
|
447 |
* |
|
448 |
* @throws IOException |
|
449 |
* If some other I/O error occurs |
|
450 |
*/ |
|
451 |
public abstract int send(ByteBuffer src, SocketAddress target) |
|
452 |
throws IOException; |
|
453 |
||
454 |
||
455 |
// -- ByteChannel operations -- |
|
456 |
||
457 |
/** |
|
458 |
* Reads a datagram from this channel. |
|
459 |
* |
|
460 |
* <p> This method may only be invoked if this channel's socket is |
|
461 |
* connected, and it only accepts datagrams from the socket's peer. If |
|
462 |
* there are more bytes in the datagram than remain in the given buffer |
|
463 |
* then the remainder of the datagram is silently discarded. Otherwise |
|
464 |
* this method behaves exactly as specified in the {@link |
|
465 |
* ReadableByteChannel} interface. </p> |
|
466 |
* |
|
467 |
* @throws NotYetConnectedException |
|
468 |
* If this channel's socket is not connected |
|
469 |
*/ |
|
470 |
public abstract int read(ByteBuffer dst) throws IOException; |
|
471 |
||
472 |
/** |
|
473 |
* Reads a datagram from this channel. |
|
474 |
* |
|
475 |
* <p> This method may only be invoked if this channel's socket is |
|
476 |
* connected, and it only accepts datagrams from the socket's peer. If |
|
477 |
* there are more bytes in the datagram than remain in the given buffers |
|
478 |
* then the remainder of the datagram is silently discarded. Otherwise |
|
479 |
* this method behaves exactly as specified in the {@link |
|
480 |
* ScatteringByteChannel} interface. </p> |
|
481 |
* |
|
482 |
* @throws NotYetConnectedException |
|
483 |
* If this channel's socket is not connected |
|
484 |
*/ |
|
485 |
public abstract long read(ByteBuffer[] dsts, int offset, int length) |
|
486 |
throws IOException; |
|
487 |
||
488 |
/** |
|
489 |
* Reads a datagram from this channel. |
|
490 |
* |
|
491 |
* <p> This method may only be invoked if this channel's socket is |
|
492 |
* connected, and it only accepts datagrams from the socket's peer. If |
|
493 |
* there are more bytes in the datagram than remain in the given buffers |
|
494 |
* then the remainder of the datagram is silently discarded. Otherwise |
|
495 |
* this method behaves exactly as specified in the {@link |
|
496 |
* ScatteringByteChannel} interface. </p> |
|
497 |
* |
|
498 |
* @throws NotYetConnectedException |
|
499 |
* If this channel's socket is not connected |
|
500 |
*/ |
|
501 |
public final long read(ByteBuffer[] dsts) throws IOException { |
|
502 |
return read(dsts, 0, dsts.length); |
|
503 |
} |
|
504 |
||
505 |
/** |
|
506 |
* Writes a datagram to this channel. |
|
507 |
* |
|
508 |
* <p> This method may only be invoked if this channel's socket is |
|
509 |
* connected, in which case it sends datagrams directly to the socket's |
|
510 |
* peer. Otherwise it behaves exactly as specified in the {@link |
|
511 |
* WritableByteChannel} interface. </p> |
|
512 |
* |
|
513 |
* @throws NotYetConnectedException |
|
514 |
* If this channel's socket is not connected |
|
515 |
*/ |
|
516 |
public abstract int write(ByteBuffer src) throws IOException; |
|
517 |
||
518 |
/** |
|
519 |
* Writes a datagram to this channel. |
|
520 |
* |
|
521 |
* <p> This method may only be invoked if this channel's socket is |
|
522 |
* connected, in which case it sends datagrams directly to the socket's |
|
523 |
* peer. Otherwise it behaves exactly as specified in the {@link |
|
524 |
* GatheringByteChannel} interface. </p> |
|
525 |
* |
|
526 |
* @return The number of bytes sent, which will be either the number |
|
527 |
* of bytes that were remaining in the source buffer when this |
|
528 |
* method was invoked or, if this channel is non-blocking, may be |
|
529 |
* zero if there was insufficient room for the datagram in the |
|
530 |
* underlying output buffer |
|
531 |
* |
|
532 |
* @throws NotYetConnectedException |
|
533 |
* If this channel's socket is not connected |
|
534 |
*/ |
|
535 |
public abstract long write(ByteBuffer[] srcs, int offset, int length) |
|
536 |
throws IOException; |
|
537 |
||
538 |
/** |
|
539 |
* Writes a datagram to this channel. |
|
540 |
* |
|
541 |
* <p> This method may only be invoked if this channel's socket is |
|
542 |
* connected, in which case it sends datagrams directly to the socket's |
|
543 |
* peer. Otherwise it behaves exactly as specified in the {@link |
|
544 |
* GatheringByteChannel} interface. </p> |
|
545 |
* |
|
546 |
* @return The number of bytes sent, which will be either the number |
|
547 |
* of bytes that were remaining in the source buffer when this |
|
548 |
* method was invoked or, if this channel is non-blocking, may be |
|
549 |
* zero if there was insufficient room for the datagram in the |
|
550 |
* underlying output buffer |
|
551 |
* |
|
552 |
* @throws NotYetConnectedException |
|
553 |
* If this channel's socket is not connected |
|
554 |
*/ |
|
555 |
public final long write(ByteBuffer[] srcs) throws IOException { |
|
556 |
return write(srcs, 0, srcs.length); |
|
557 |
} |
|
558 |
||
559 |
} |