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