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
26package 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 */
42public final
43class DatagramPacket {
44
45    /**
46     * Perform class initialization
47     */
48    static {
49        java.security.AccessController.doPrivileged(
50            new java.security.PrivilegedAction<>() {
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   1.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   1.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 1.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 1.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 static native void init();
388}
389