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.access.SharedSecrets.getJavaLangAccess().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 }