1 /*
2 * Copyright 1995-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 }
Save This Page