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.loader.BootLoader.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 * @throws 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 * @throws 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 * @throws 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 }