1 /*
2 * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net;
27
28 import java.io.FileDescriptor;
29 import java.io.IOException;
30 import java.util.Objects;
31 import java.util.Set;
32
33 /**
34 * Abstract datagram and multicast socket implementation base class.
35 * @author Pavani Diwanji
36 * @since 1.1
37 */
38
39 public abstract class DatagramSocketImpl implements SocketOptions {
40
41 /**
42 * The local port number.
43 */
44 protected int localPort;
45
46 /**
47 * The file descriptor object.
48 */
49 protected FileDescriptor fd;
50
51 /**
52 * The DatagramSocket or MulticastSocket
53 * that owns this impl
54 */
55 DatagramSocket socket;
56
57 void setDatagramSocket(DatagramSocket socket) {
58 this.socket = socket;
59 }
60
61 DatagramSocket getDatagramSocket() {
62 return socket;
63 }
64
65 int dataAvailable() {
66 // default impl returns zero, which disables the calling
67 // functionality
68 return 0;
69 }
70
71 /**
72 * Creates a datagram socket.
73 * @exception SocketException if there is an error in the
74 * underlying protocol, such as a TCP error.
75 */
76 protected abstract void create() throws SocketException;
77
78 /**
79 * Binds a datagram socket to a local port and address.
80 * @param lport the local port
81 * @param laddr the local address
82 * @exception SocketException if there is an error in the
83 * underlying protocol, such as a TCP error.
84 */
85 protected abstract void bind(int lport, InetAddress laddr) throws SocketException;
86
87 /**
88 * Sends a datagram packet. The packet contains the data and the
89 * destination address to send the packet to.
90 * @param p the packet to be sent.
91 * @exception IOException if an I/O exception occurs while sending the
92 * datagram packet.
93 * @exception PortUnreachableException may be thrown if the socket is connected
94 * to a currently unreachable destination. Note, there is no guarantee that
95 * the exception will be thrown.
96 */
97 protected abstract void send(DatagramPacket p) throws IOException;
98
99 /**
100 * Connects a datagram socket to a remote destination. This associates the remote
101 * address with the local socket so that datagrams may only be sent to this destination
102 * and received from this destination. This may be overridden to call a native
103 * system connect.
104 *
105 * <p>If the remote destination to which the socket is connected does not
106 * exist, or is otherwise unreachable, and if an ICMP destination unreachable
107 * packet has been received for that address, then a subsequent call to
108 * send or receive may throw a PortUnreachableException.
109 * Note, there is no guarantee that the exception will be thrown.
110 * @param address the remote InetAddress to connect to
111 * @param port the remote port number
112 * @exception SocketException may be thrown if the socket cannot be
113 * connected to the remote destination
114 * @since 1.4
115 */
116 protected void connect(InetAddress address, int port) throws SocketException {}
117
118 /**
119 * Disconnects a datagram socket from its remote destination.
120 * @since 1.4
121 */
122 protected void disconnect() {}
123
124 /**
125 * Peek at the packet to see who it is from. Updates the specified {@code InetAddress}
126 * to the address which the packet came from.
127 * @param i an InetAddress object
128 * @return the port number which the packet came from.
129 * @exception IOException if an I/O exception occurs
130 * @exception PortUnreachableException may be thrown if the socket is connected
131 * to a currently unreachable destination. Note, there is no guarantee that the
132 * exception will be thrown.
133 */
134 protected abstract int peek(InetAddress i) throws IOException;
135
136 /**
137 * Peek at the packet to see who it is from. The data is copied into the specified
138 * {@code DatagramPacket}. The data is returned,
139 * but not consumed, so that a subsequent peekData/receive operation
140 * will see the same data.
141 * @param p the Packet Received.
142 * @return the port number which the packet came from.
143 * @exception IOException if an I/O exception occurs
144 * @exception PortUnreachableException may be thrown if the socket is connected
145 * to a currently unreachable destination. Note, there is no guarantee that the
146 * exception will be thrown.
147 * @since 1.4
148 */
149 protected abstract int peekData(DatagramPacket p) throws IOException;
150 /**
151 * Receive the datagram packet.
152 * @param p the Packet Received.
153 * @exception IOException if an I/O exception occurs
154 * while receiving the datagram packet.
155 * @exception PortUnreachableException may be thrown if the socket is connected
156 * to a currently unreachable destination. Note, there is no guarantee that the
157 * exception will be thrown.
158 */
159 protected abstract void receive(DatagramPacket p) throws IOException;
160
161 /**
162 * Set the TTL (time-to-live) option.
163 * @param ttl a byte specifying the TTL value
164 *
165 * @deprecated use setTimeToLive instead.
166 * @exception IOException if an I/O exception occurs while setting
167 * the time-to-live option.
168 * @see #getTTL()
169 */
170 @Deprecated
171 protected abstract void setTTL(byte ttl) throws IOException;
172
173 /**
174 * Retrieve the TTL (time-to-live) option.
175 *
176 * @exception IOException if an I/O exception occurs
177 * while retrieving the time-to-live option
178 * @deprecated use getTimeToLive instead.
179 * @return a byte representing the TTL value
180 * @see #setTTL(byte)
181 */
182 @Deprecated
183 protected abstract byte getTTL() throws IOException;
184
185 /**
186 * Set the TTL (time-to-live) option.
187 * @param ttl an {@code int} specifying the time-to-live value
188 * @exception IOException if an I/O exception occurs
189 * while setting the time-to-live option.
190 * @see #getTimeToLive()
191 */
192 protected abstract void setTimeToLive(int ttl) throws IOException;
193
194 /**
195 * Retrieve the TTL (time-to-live) option.
196 * @exception IOException if an I/O exception occurs
197 * while retrieving the time-to-live option
198 * @return an {@code int} representing the time-to-live value
199 * @see #setTimeToLive(int)
200 */
201 protected abstract int getTimeToLive() throws IOException;
202
203 /**
204 * Join the multicast group.
205 * @param inetaddr multicast address to join.
206 * @exception IOException if an I/O exception occurs
207 * while joining the multicast group.
208 */
209 protected abstract void join(InetAddress inetaddr) throws IOException;
210
211 /**
212 * Leave the multicast group.
213 * @param inetaddr multicast address to leave.
214 * @exception IOException if an I/O exception occurs
215 * while leaving the multicast group.
216 */
217 protected abstract void leave(InetAddress inetaddr) throws IOException;
218
219 /**
220 * Join the multicast group.
221 * @param mcastaddr address to join.
222 * @param netIf specifies the local interface to receive multicast
223 * datagram packets
224 * @throws IOException if an I/O exception occurs while joining
225 * the multicast group
226 * @since 1.4
227 */
228 protected abstract void joinGroup(SocketAddress mcastaddr,
229 NetworkInterface netIf)
230 throws IOException;
231
232 /**
233 * Leave the multicast group.
234 * @param mcastaddr address to leave.
235 * @param netIf specified the local interface to leave the group at
236 * @throws IOException if an I/O exception occurs while leaving
237 * the multicast group
238 * @since 1.4
239 */
240 protected abstract void leaveGroup(SocketAddress mcastaddr,
241 NetworkInterface netIf)
242 throws IOException;
243
244 /**
245 * Close the socket.
246 */
247 protected abstract void close();
248
249 /**
250 * Gets the local port.
251 * @return an {@code int} representing the local port value
252 */
253 protected int getLocalPort() {
254 return localPort;
255 }
256
257 /**
258 * Gets the datagram socket file descriptor.
259 * @return a {@code FileDescriptor} object representing the datagram socket
260 * file descriptor
261 */
262 protected FileDescriptor getFileDescriptor() {
263 return fd;
264 }
265
266 /**
267 * Called to set a socket option.
268 *
269 * @implSpec
270 * The default implementation of this method first checks that the given
271 * socket option {@code name} is not null, then throws {@code
272 * UnsupportedOperationException}. Subclasses should override this method
273 * with an appropriate implementation.
274 *
275 * @param <T> The type of the socket option value
276 * @param name The socket option
277 * @param value The value of the socket option. A value of {@code null}
278 * may be valid for some options.
279 *
280 * @throws UnsupportedOperationException if the DatagramSocketImpl does not
281 * support the option
282 * @throws IllegalArgumentException if the value is not valid for
283 * the option
284 * @throws IOException if an I/O error occurs, or if the socket is closed
285 * @throws NullPointerException if name is {@code null}
286 *
287 * @since 9
288 */
289 protected <T> void setOption(SocketOption<T> name, T value) throws IOException {
290 Objects.requireNonNull(name);
291 throw new UnsupportedOperationException("'" + name + "' not supported");
292 }
293
294 /**
295 * Called to get a socket option.
296 *
297 * @implSpec
298 * The default implementation of this method first checks that the given
299 * socket option {@code name} is not null, then throws {@code
300 * UnsupportedOperationException}. Subclasses should override this method
301 * with an appropriate implementation.
302 *
303 * @param <T> The type of the socket option value
304 * @param name The socket option
305 * @return the socket option
306 *
307 * @throws UnsupportedOperationException if the DatagramSocketImpl does not
308 * support the option
309 * @throws IOException if an I/O error occurs, or if the socket is closed
310 * @throws NullPointerException if name is {@code null}
311 *
312 * @since 9
313 */
314 protected <T> T getOption(SocketOption<T> name) throws IOException {
315 Objects.requireNonNull(name);
316 throw new UnsupportedOperationException("'" + name + "' not supported");
317 }
318
319 /**
320 * Returns a set of SocketOptions supported by this impl
321 * and by this impl's socket (DatagramSocket or MulticastSocket)
322 *
323 * @implSpec
324 * The default implementation of this method returns an empty set.
325 * Subclasses should override this method with an appropriate implementation.
326 *
327 * @return a Set of SocketOptions
328 *
329 * @since 9
330 */
331 protected Set<SocketOption<?>> supportedOptions() {
332 return Set.of();
333 }
334 }