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