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 jdk.internal.loader.BootLoader.loadLibrary("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 }