1 /*
2 * Copyright (c) 1995, 2020, 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 /**
29 * This class represents a datagram packet.
30 * <p>
31 * Datagram packets are used to implement a connectionless packet
32 * delivery service. Each message is routed from one machine to
33 * another based solely on information contained within that packet.
34 * Multiple packets sent from one machine to another might be routed
35 * differently, and might arrive in any order. Packet delivery is
36 * not guaranteed.
37 *
38 * <p>
39 * Unless otherwise specified, passing a {@code null} argument causes
40 * a {@link NullPointerException NullPointerException} to be thrown.
41 *
42 * <p>
43 * Methods and constructors of {@code DatagramPacket} accept parameters
44 * of type {@link SocketAddress}. {@code DatagramPacket} supports
45 * {@link InetSocketAddress}, and may support additional {@code SocketAddress}
46 * sub-types.
47 *
48 * @author Pavani Diwanji
49 * @author Benjamin Renaud
50 * @since 1.0
51 */
52 public final
53 class DatagramPacket {
54
55 /**
56 * Perform class initialization
57 */
58 static {
59 sun.security.action.LoadLibraryAction.privilegedLoadLibrary("net");
60 init();
61 }
62
63 /*
64 * The fields of this class are package-private since DatagramSocketImpl
65 * classes needs to access them.
66 */
67 byte[] buf;
68 int offset;
69 int length;
70 int bufLength;
71 InetAddress address;
72 int port;
73
74 /**
75 * Constructs a {@code DatagramPacket} for receiving packets of
76 * length {@code length}, specifying an offset into the buffer.
77 * <p>
78 * The {@code length} argument must be less than or equal to
79 * {@code buf.length}.
80 *
81 * @param buf buffer for holding the incoming datagram.
82 * @param offset the offset for the buffer
83 * @param length the number of bytes to read.
84 *
85 * @throws IllegalArgumentException if the length or offset
86 * is negative, or if the length plus the offset is
87 * greater than the length of the packet's given buffer.
88 *
89 * @since 1.2
90 */
91 public DatagramPacket(byte buf[], int offset, int length) {
92 setData(buf, offset, length);
93 this.address = null;
94 this.port = -1;
95 }
96
97 /**
98 * Constructs a {@code DatagramPacket} for receiving packets of
99 * length {@code length}.
100 * <p>
101 * The {@code length} argument must be less than or equal to
102 * {@code buf.length}.
103 *
104 * @param buf buffer for holding the incoming datagram.
105 * @param length the number of bytes to read.
106 *
107 * @throws IllegalArgumentException if the length is negative
108 * or if the length is greater than the length of the
109 * packet's given buffer.
110 */
111 public DatagramPacket(byte buf[], int length) {
112 this (buf, 0, length);
113 }
114
115 /**
116 * Constructs a datagram packet for sending packets of length
117 * {@code length} with offset {@code offset} to the
118 * specified port number on the specified host. The
119 * {@code length} argument must be less than or equal to
120 * {@code buf.length}.
121 *
122 * @param buf the packet data.
123 * @param offset the packet data offset.
124 * @param length the packet data length.
125 * @param address the destination address, or {@code null}.
126 * @param port the destination port number.
127 *
128 * @throws IllegalArgumentException if the length or offset
129 * is negative, or if the length plus the offset is
130 * greater than the length of the packet's given buffer,
131 * or if the port is out of range.
132 *
133 * @see java.net.InetAddress
134 *
135 * @since 1.2
136 */
137 public DatagramPacket(byte buf[], int offset, int length,
138 InetAddress address, int port) {
139 setData(buf, offset, length);
140 setAddress(address);
141 setPort(port);
142 }
143
144 /**
145 * Constructs a datagram packet for sending packets of length
146 * {@code length} with offset {@code offset} to the
147 * specified port number on the specified host. The
148 * {@code length} argument must be less than or equal to
149 * {@code buf.length}.
150 *
151 * @param buf the packet data.
152 * @param offset the packet data offset.
153 * @param length the packet data length.
154 * @param address the destination socket address.
155 *
156 * @throws IllegalArgumentException if address is null or its
157 * type is not supported, or if the length or offset is
158 * negative, or if the length plus the offset is greater
159 * than the length of the packet's given buffer.
160 *
161 * @see java.net.InetAddress
162 *
163 * @since 1.4
164 */
165 public DatagramPacket(byte buf[], int offset, int length, SocketAddress address) {
166 setData(buf, offset, length);
167 setSocketAddress(address);
168 }
169
170 /**
171 * Constructs a datagram packet for sending packets of length
172 * {@code length} to the specified port number on the specified
173 * host. The {@code length} argument must be less than or equal
174 * to {@code buf.length}.
175 *
176 * @param buf the packet data.
177 * @param length the packet length.
178 * @param address the destination address, or {@code null}.
179 * @param port the destination port number.
180 *
181 * @throws IllegalArgumentException if the length is negative,
182 * or if the length is greater than the length of the
183 * packet's given buffer, or if the port is out of range.
184 *
185 * @see java.net.InetAddress
186 */
187 public DatagramPacket(byte buf[], int length,
188 InetAddress address, int port) {
189 this(buf, 0, length, address, port);
190 }
191
192 /**
193 * Constructs a datagram packet for sending packets of length
194 * {@code length} to the specified port number on the specified
195 * host. The {@code length} argument must be less than or equal
196 * to {@code buf.length}.
197 *
198 * @param buf the packet data.
199 * @param length the packet length.
200 * @param address the destination address.
201 *
202 * @throws IllegalArgumentException if address is null or its type is
203 * not supported, or if the length is negative, or if the length
204 * is greater than the length of the packet's given buffer, or
205 * if the port is out of range.
206 *
207 * @see java.net.InetAddress
208 *
209 * @since 1.4
210 */
211 public DatagramPacket(byte buf[], int length, SocketAddress address) {
212 this(buf, 0, length, address);
213 }
214
215 /**
216 * Returns the IP address of the machine to which this datagram is being
217 * sent or from which the datagram was received.
218 *
219 * @return the IP address of the machine to which this datagram is being
220 * sent or from which the datagram was received.
221 * @see java.net.InetAddress
222 * @see #setAddress(java.net.InetAddress)
223 */
224 public synchronized InetAddress getAddress() {
225 return address;
226 }
227
228 /**
229 * Returns the port number on the remote host to which this datagram is
230 * being sent or from which the datagram was received.
231 *
232 * @return the port number on the remote host to which this datagram is
233 * being sent or from which the datagram was received.
234 * @see #setPort(int)
235 */
236 public synchronized int getPort() {
237 return port;
238 }
239
240 /**
241 * Returns the data buffer. The data received or the data to be sent
242 * starts from the {@code offset} in the buffer,
243 * and runs for {@code length} long.
244 *
245 * @return the buffer used to receive or send data
246 * @see #setData(byte[], int, int)
247 */
248 public synchronized byte[] getData() {
249 return buf;
250 }
251
252 /**
253 * Returns the offset of the data to be sent or the offset of the
254 * data received.
255 *
256 * @return the offset of the data to be sent or the offset of the
257 * data received.
258 *
259 * @since 1.2
260 */
261 public synchronized int getOffset() {
262 return offset;
263 }
264
265 /**
266 * Returns the length of the data to be sent or the length of the
267 * data received.
268 *
269 * @return the length of the data to be sent or the length of the
270 * data received.
271 * @see #setLength(int)
272 */
273 public synchronized int getLength() {
274 return length;
275 }
276
277 /**
278 * Set the data buffer for this packet. This sets the
279 * data, length and offset of the packet.
280 *
281 * @param buf the buffer to set for this packet
282 * @param offset the offset into the data
283 * @param length the length of the data
284 * and/or the length of the buffer used to receive data
285 *
286 * @throws IllegalArgumentException if the length or offset
287 * is negative, or if the length plus the offset is
288 * greater than the length of the packet's given buffer.
289 *
290 * @see #getData
291 * @see #getOffset
292 * @see #getLength
293 *
294 * @since 1.2
295 */
296 public synchronized void setData(byte[] buf, int offset, int length) {
297 /* this will check to see if buf is null */
298 if (length < 0 || offset < 0 ||
299 (length + offset) < 0 ||
300 ((length + offset) > buf.length)) {
301 throw new IllegalArgumentException("illegal length or offset");
302 }
303 this.buf = buf;
304 this.length = length;
305 this.bufLength = length;
306 this.offset = offset;
307 }
308
309 /**
310 * Sets the IP address of the machine to which this datagram
311 * is being sent.
312 *
313 * @param iaddr the {@code InetAddress}, or {@code null}.
314 *
315 * @see #getAddress()
316 *
317 * @since 1.1
318 */
319 public synchronized void setAddress(InetAddress iaddr) {
320 address = iaddr;
321 }
322
323 /**
324 * Sets the port number on the remote host to which this datagram
325 * is being sent.
326 *
327 * @param iport the port number
328 *
329 * @throws IllegalArgumentException if the port is out of range
330 *
331 * @see #getPort()
332 *
333 * @since 1.1
334 */
335 public synchronized void setPort(int iport) {
336 if (iport < 0 || iport > 0xFFFF) {
337 throw new IllegalArgumentException("Port out of range:"+ iport);
338 }
339 port = iport;
340 }
341
342 /**
343 * Sets the SocketAddress (usually IP address + port number) of the remote
344 * host to which this datagram is being sent.
345 *
346 * @param address the {@code SocketAddress}
347 *
348 * @throws IllegalArgumentException if address is null or is a
349 * SocketAddress subclass not supported.
350 *
351 * @see #getSocketAddress
352 *
353 * @since 1.4
354 */
355 public synchronized void setSocketAddress(SocketAddress address) {
356 if (address == null || !(address instanceof InetSocketAddress))
357 throw new IllegalArgumentException("unsupported address type");
358 InetSocketAddress addr = (InetSocketAddress) address;
359 if (addr.isUnresolved())
360 throw new IllegalArgumentException("unresolved address");
361 setAddress(addr.getAddress());
362 setPort(addr.getPort());
363 }
364
365 /**
366 * Gets the SocketAddress (usually IP address + port number) of the remote
367 * host that this packet is being sent to or is coming from.
368 *
369 * @return the {@code SocketAddress}
370 *
371 * @see #setSocketAddress
372 *
373 * @since 1.4
374 */
375 public synchronized SocketAddress getSocketAddress() {
376 return new InetSocketAddress(getAddress(), getPort());
377 }
378
379 /**
380 * Set the data buffer for this packet. With the offset of
381 * this DatagramPacket set to 0, and the length set to
382 * the length of {@code buf}.
383 *
384 * @param buf the buffer to set for this packet.
385 *
386 * @see #getLength
387 * @see #getData
388 *
389 * @since 1.1
390 */
391 public synchronized void setData(byte[] buf) {
392 if (buf == null) {
393 throw new NullPointerException("null packet buffer");
394 }
395 this.buf = buf;
396 this.offset = 0;
397 this.length = buf.length;
398 this.bufLength = buf.length;
399 }
400
401 /**
402 * Set the length for this packet. The length of the packet is
403 * the number of bytes from the packet's data buffer that will be
404 * sent, or the number of bytes of the packet's data buffer that
405 * will be used for receiving data. The length must be lesser or
406 * equal to the offset plus the length of the packet's buffer.
407 *
408 * @param length the length to set for this packet.
409 *
410 * @throws IllegalArgumentException if the length is negative,
411 * or if the length plus the offset is greater than the
412 * length of the packet's data buffer.
413 *
414 * @see #getLength
415 * @see #setData
416 *
417 * @since 1.1
418 */
419 public synchronized void setLength(int length) {
420 if ((length + offset) > buf.length || length < 0 ||
421 (length + offset) < 0) {
422 throw new IllegalArgumentException("illegal length");
423 }
424 this.length = length;
425 this.bufLength = this.length;
426 }
427
428 /**
429 * Perform class load-time initializations.
430 */
431 private static native void init();
432 }