libjava/java/net/DatagramPacket.java

   1 /* DatagramPacket.java -- Class to model a packet to be sent via UDP
   2    Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.net;
  39
  40 /*
  41  * Written using on-line Java Platform 1.2 API Specification, as well
  42  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  43  * Status:  Believed complete and correct.
  44  */
  45
  46 /**
  47  * This class models a packet of data that is to be sent across the network
  48  * using a connectionless protocol such as UDP.  It contains the data
  49  * to be send, as well as the destination address and port.  Note that
  50  * datagram packets can arrive in any order and are not guaranteed to be
  51  * delivered at all.
  52  * <p>
  53  * This class can also be used for receiving data from the network.
  54  * <p>
  55  * Note that for all method below where the buffer length passed by the
  56  * caller cannot exceed the actually length of the byte array passed as
  57  * the buffer, if this condition is not true, then the method silently
  58  * reduces the length value to maximum allowable value.
  59  *
  60  * Written using on-line Java Platform 1.2 API Specification, as well
  61  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  62  * Status:  Believed complete and correct.
  63  *
  64  * @author Warren Levy <warrenl@cygnus.com>
  65  * @author Aarom M. Renn (arenn@urbanophile.com) (Documentation comments)
  66  * @date April 28, 1999.
  67  */
  68 public final class DatagramPacket
  69 {
  70   /**
  71    * The data buffer to send
  72    */
  73   private byte[] buffer;
  74
  75   /**
  76    * This is the offset into the buffer to start sending from or receiving to.
  77    */
  78   private int offset;
  79
  80   /**
  81    * The length of the data buffer to send.
  82    */
  83   int length;
  84
  85   /**
  86    * The maximal length of the buffer.
  87    */
  88   int maxlen;
  89
  90   /**
  91    * The address to which the packet should be sent or from which it
  92    * was received.
  93    */
  94   private InetAddress address;
  95
  96   /**
  97    * The port to which the packet should be sent or from which it was
  98    * was received.
  99    */
 100   private int port;
 101
 102   /**
 103    * This method initializes a new instance of <code>DatagramPacket</code>
 104    * which has the specified buffer, offset, and length.
 105    *
 106    * @param buf The buffer for holding the incoming datagram.
 107    * @param offset The offset into the buffer to start writing.
 108    * @param length The maximum number of bytes to read.
 109    *
 110    * @since 1.2
 111    */
 112   public DatagramPacket(byte[] buf, int offset, int length)
 113   {
 114     setData(buf, offset, length);
 115     address = null;
 116     port = -1;
 117   }
 118
 119   /**
 120    * Initializes a new instance of <code>DatagramPacket</code> for
 121    * receiving packets from the network.
 122    *
 123    * @param buf A buffer for storing the returned packet data
 124    * @param length The length of the buffer (must be &lt;= buf.length)
 125    */
 126   public DatagramPacket(byte[] buf, int length)
 127   {
 128     this(buf, 0, length);
 129   }
 130
 131   /**
 132    * Initializes a new instance of <code>DatagramPacket</code> for
 133    * transmitting packets across the network.
 134    *
 135    * @param buf A buffer containing the data to send
 136    * @param offset The offset into the buffer to start writing from.
 137    * @param len The length of the buffer (must be &lt;= buf.length)
 138    * @param addr The address to send to
 139    * @param port The port to send to
 140    *
 141    * @since 1.2
 142    */
 143   public DatagramPacket(byte[] buf, int offset, int length,
 144         InetAddress address, int port)
 145   {
 146     setData(buf, offset, length);
 147     setAddress(address);
 148     setPort(port);
 149   }
 150
 151   /**
 152    * Initializes a new instance of <code>DatagramPacket</code> for
 153    * transmitting packets across the network.
 154    *
 155    * @param buf A buffer containing the data to send
 156    * @param length The length of the buffer (must be &lt;= buf.length)
 157    * @param address The address to send to
 158    * @param port The port to send to
 159    */
 160   public DatagramPacket(byte[] buf, int length, InetAddress address, int port)
 161   {
 162     this(buf, 0, length, address, port);
 163   }
 164
 165   /**
 166    * Initializes a new instance of <code>DatagramPacket</code> for
 167    * transmitting packets across the network.
 168    *
 169    * @param buf A buffer containing the data to send
 170    * @param offset The offset into the buffer to start writing from.
 171    * @param length The length of the buffer (must be &lt;= buf.length)
 172    * @param address The socket address to send to
 173    *
 174    * @exception SocketException If an error occurs
 175    * @exception IllegalArgumentException If address type is not supported
 176    *
 177    * @since 1.4
 178    */
 179   public DatagramPacket(byte[] buf, int offset, int length,
 180                         SocketAddress address)
 181      throws SocketException
 182   {
 183     if (! (address instanceof InetSocketAddress))
 184       throw new IllegalArgumentException("unsupported address type");
 185
 186     InetSocketAddress tmp = (InetSocketAddress) address;
 187     setData(buf, offset, length);
 188     setAddress(tmp.getAddress());
 189     setPort(tmp.getPort());
 190   }
 191
 192   /**
 193    * Initializes a new instance of <code>DatagramPacket</code> for
 194    * transmitting packets across the network.
 195    *
 196    * @param buf A buffer containing the data to send
 197    * @param length The length of the buffer (must be &lt;= buf.length)
 198    * @param address The socket address to send to
 199    *
 200    * @exception SocketException If an error occurs
 201    * @exception IllegalArgumentException If address type is not supported
 202    *
 203    * @since 1.4
 204    */
 205   public DatagramPacket(byte[] buf, int length, SocketAddress address)
 206     throws SocketException
 207   {
 208     this(buf, 0, length, address);
 209   }
 210
 211   /**
 212    * Returns the address that this packet is being sent to or, if it was used
 213    * to receive a packet, the address that is was received from.  If the
 214    * constructor that doesn not take an address was used to create this object
 215    * and no packet was actually read into this object, then this method
 216    * returns <code>null</code>.
 217    *
 218    * @return The address for this packet.
 219    */
 220   public synchronized InetAddress getAddress()
 221   {
 222     return address;
 223   }
 224
 225   /**
 226    * Returns the port number this packet is being sent to or, if it was used
 227    * to receive a packet, the port that it was received from. If the
 228    * constructor that doesn not take an address was used to create this object
 229    * and no packet was actually read into this object, then this method
 230    * will return 0.
 231    *
 232    * @return The port number for this packet
 233    */
 234   public synchronized int getPort()
 235   {
 236     return port;
 237   }
 238
 239   /**
 240    * Returns the data buffer for this packet
 241    *
 242    * @return This packet's data buffer
 243    */
 244   public synchronized byte[] getData()
 245   {
 246     return buffer;
 247   }
 248
 249   /**
 250    * This method returns the current offset value into the data buffer
 251    * where data will be sent from.
 252    *
 253    * @return The buffer offset.
 254    *
 255    * @since 1.2
 256    */
 257   public synchronized int getOffset()
 258   {
 259     return offset;
 260   }
 261
 262   /**
 263    * Returns the length of the data in the buffer
 264    *
 265    * @return The length of the data
 266    */
 267   public synchronized int getLength()
 268   {
 269     return length;
 270   }
 271
 272   /**
 273    * This sets the address to which the data packet will be transmitted.
 274    *
 275    * @param addr The destination address
 276    *
 277    * @since 1.1
 278    */
 279   public synchronized void setAddress(InetAddress iaddr)
 280   {
 281     if (iaddr == null)
 282       throw new NullPointerException("Null address");
 283
 284     address = iaddr;
 285   }
 286
 287   /**
 288    * This sets the port to which the data packet will be transmitted.
 289    *
 290    * @param port The destination port
 291    *
 292    * @since 1.1
 293    */
 294   public synchronized void setPort(int iport)
 295   {
 296     if (iport < 0 || iport > 65535)
 297       throw new IllegalArgumentException("Invalid port: " + iport);
 298
 299     port = iport;
 300   }
 301
 302   /**
 303    * Sets the address of the remote host this package will be sent
 304    *
 305    * @param address The socket address of the remove host
 306    *
 307    * @exception IllegalArgumentException If address type is not supported
 308    *
 309    * @since 1.4
 310    */
 311   public void setSocketAddress(SocketAddress address)
 312     throws IllegalArgumentException
 313   {
 314     if (address == null)
 315       throw new IllegalArgumentException("address may not be null");
 316
 317     InetSocketAddress tmp = (InetSocketAddress) address;
 318     this.address = tmp.getAddress();
 319     this.port = tmp.getPort();
 320   }
 321
 322   /**
 323    * Gets the socket address of the host this packet
 324    * will be sent to/is coming from
 325    *
 326    * @return The socket address of the remote host
 327    *
 328    * @since 1.4
 329    */
 330   public SocketAddress getSocketAddress()
 331   {
 332     return new InetSocketAddress (address, port);
 333   }
 334
 335   /**
 336    * Sets the data buffer for this packet.
 337    *
 338    * @param buf The new buffer for this packet
 339    *
 340    * @exception NullPointerException If the argument is null
 341    *
 342    * @since 1.1
 343    */
 344   public void setData(byte[] buf)
 345   {
 346     setData(buf, 0, buf.length);
 347   }
 348
 349   /**
 350    * This method sets the data buffer for the packet.
 351    *
 352    * @param buf The byte array containing the data for this packet.
 353    * @param offset The offset into the buffer to start reading data from.
 354    * @param length The number of bytes of data in the buffer.
 355    *
 356    * @exception NullPointerException If the argument is null
 357    *
 358    * @since 1.2
 359    */
 360   public synchronized void setData(byte[] buf, int offset, int length)
 361   {
 362     // This form of setData must be used if offset is to be changed.
 363
 364     if (buf == null)
 365       throw new NullPointerException("Null buffer");
 366     if (offset < 0)
 367       throw new IllegalArgumentException("Invalid offset: " + offset);
 368
 369     buffer = buf;
 370     this.offset = offset;
 371     setLength(length);
 372   }
 373
 374   /**
 375    * Sets the length of the data in the buffer.
 376    *
 377    * @param length The new length.  (Where len &lt;= buf.length)
 378    *
 379    * @exception IllegalArgumentException If the length is negative or
 380    * if the length is greater than the packet's data buffer length
 381    *
 382    * @since 1.1
 383    */
 384   public synchronized void setLength(int length)
 385   {
 386     if (length < 0)
 387       throw new IllegalArgumentException("Invalid length: " + length);
 388     if (offset + length > buffer.length)
 389       throw new IllegalArgumentException("Potential buffer overflow - offset: "
 390                         + offset + " length: " + length);
 391
 392     this.length = length;
 393     this.maxlen = length;
 394   }
 395 }