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