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