DatagramPacket


1   /*
2    * @(#)DatagramPacket.java  1.46 06/04/07
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.net;
9   
10  /**
11   * This class represents a datagram packet. 
12   * <p>
13   * Datagram packets are used to implement a connectionless packet 
14   * delivery service. Each message is routed from one machine to 
15   * another based solely on information contained within that packet. 
16   * Multiple packets sent from one machine to another might be routed 
17   * differently, and might arrive in any order. Packet delivery is
18   * not guaranteed.
19   *
20   * @author  Pavani Diwanji
21   * @author  Benjamin Renaud
22   * @version 1.46, 04/07/06
23   * @since   JDK1.0
24   */
25  public final 
26  class DatagramPacket {
27  
28      /**
29       * Perform class initialization
30       */
31      static {
32      java.security.AccessController.doPrivileged(
33            new sun.security.action.LoadLibraryAction("net"));
34      init();
35      }
36  
37      /*
38       * The fields of this class are package-private since DatagramSocketImpl 
39       * classes needs to access them.
40       */
41      byte[] buf;
42      int offset;
43      int length;
44      int bufLength;
45      InetAddress   address;
46      int port;
47  
48      /**
49       * Constructs a <code>DatagramPacket</code> for receiving packets of 
50       * length <code>length</code>, specifying an offset into the buffer.
51       * <p>
52       * The <code>length</code> argument must be less than or equal to 
53       * <code>buf.length</code>. 
54       *
55       * @param   buf      buffer for holding the incoming datagram.
56       * @param   offset   the offset for the buffer
57       * @param   length   the number of bytes to read.
58       *
59       * @since 1.2
60       */
61      public DatagramPacket(byte buf[], int offset, int length) {
62      setData(buf, offset, length);
63      this.address = null;
64      this.port = -1;
65      }
66  
67      /**
68       * Constructs a <code>DatagramPacket</code> for receiving packets of 
69       * length <code>length</code>. 
70       * <p>
71       * The <code>length</code> argument must be less than or equal to 
72       * <code>buf.length</code>. 
73       *
74       * @param   buf      buffer for holding the incoming datagram.
75       * @param   length   the number of bytes to read.
76       */
77      public DatagramPacket(byte buf[], int length) {
78      this (buf, 0, length);
79      }
80      
81      /**
82       * Constructs a datagram packet for sending packets of length
83       * <code>length</code> with offset <code>ioffset</code>to the
84       * specified port number on the specified host. The
85       * <code>length</code> argument must be less than or equal to
86       * <code>buf.length</code>.
87       *
88       * @param   buf      the packet data.
89       * @param   offset   the packet data offset.
90       * @param   length   the packet data length.
91       * @param   address  the destination address.
92       * @param   port     the destination port number.
93       * @see java.net.InetAddress
94       *
95       * @since 1.2
96       */
97      public DatagramPacket(byte buf[], int offset, int length,
98                InetAddress   address, int port) {
99      setData(buf, offset, length);
100     setAddress(address);
101     setPort(port);
102     }
103 
104     /**
105      * Constructs a datagram packet for sending packets of length
106      * <code>length</code> with offset <code>ioffset</code>to the
107      * specified port number on the specified host. The
108      * <code>length</code> argument must be less than or equal to
109      * <code>buf.length</code>.
110      *
111      * @param   buf      the packet data.
112      * @param   offset   the packet data offset.
113      * @param   length   the packet data length.
114      * @param   address  the destination socket address.
115      * @throws  IllegalArgumentException if address type is not supported
116      * @see java.net.InetAddress
117      *
118      * @since 1.4
119      */
120     public DatagramPacket(byte buf[], int offset, int length,
121               SocketAddress   address) throws SocketException   {
122     setData(buf, offset, length);
123     setSocketAddress(address);
124     }
125 
126     /**
127      * Constructs a datagram packet for sending packets of length 
128      * <code>length</code> to the specified port number on the specified 
129      * host. The <code>length</code> argument must be less than or equal 
130      * to <code>buf.length</code>. 
131      *
132      * @param   buf      the packet data.
133      * @param   length   the packet length.
134      * @param   address  the destination address.
135      * @param   port     the destination port number.
136      * @see     java.net.InetAddress
137      */
138     public DatagramPacket(byte buf[], int length,
139               InetAddress   address, int port) {
140     this(buf, 0, length, address, port);
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      * @throws  IllegalArgumentException if address type is not supported
153      * @since 1.4
154      * @see     java.net.InetAddress
155      */
156     public DatagramPacket(byte buf[], int length,
157               SocketAddress   address) throws SocketException   {
158     this(buf, 0, length, address);
159     }
160 
161     /**
162      * Returns the IP address of the machine to which this datagram is being
163      * sent or from which the datagram was received.
164      *
165      * @return  the IP address of the machine to which this datagram is being
166      *          sent or from which the datagram was received.
167      * @see     java.net.InetAddress
168      * @see #setAddress(java.net.InetAddress)
169      */
170     public synchronized InetAddress   getAddress() {
171     return address;
172     }
173     
174     /**
175      * Returns the port number on the remote host to which this datagram is
176      * being sent or from which the datagram was received.
177      *
178      * @return  the port number on the remote host to which this datagram is
179      *          being sent or from which the datagram was received.
180      * @see #setPort(int)
181      */
182     public synchronized int getPort() {
183     return port;
184     }
185     
186     /**
187      * Returns the data buffer. The data received or the data to be sent
188      * starts from the <code>offset</code> in the buffer, 
189      * and runs for <code>length</code> long.
190      *
191      * @return  the buffer used to receive or  send data
192      * @see #setData(byte[], int, int)
193      */
194     public synchronized byte[] getData() {
195     return buf;
196     }
197     
198     /**
199      * Returns the offset of the data to be sent or the offset of the
200      * data received.
201      *
202      * @return  the offset of the data to be sent or the offset of the
203      *          data received.
204      *
205      * @since 1.2
206      */
207     public synchronized int getOffset() {
208     return offset;
209     }
210 
211     /**
212      * Returns the length of the data to be sent or the length of the
213      * data received.
214      *
215      * @return  the length of the data to be sent or the length of the
216      *          data received.
217      * @see #setLength(int)
218      */
219     public synchronized int getLength() {
220     return length;
221     }
222 
223     /** 
224      * Set the data buffer for this packet. This sets the
225      * data, length and offset of the packet.
226      *
227      * @param buf the buffer to set for this packet
228      *
229      * @param offset the offset into the data
230      *
231      * @param length the length of the data 
232      *       and/or the length of the buffer used to receive data
233      *
234      * @exception NullPointerException if the argument is null
235      *
236      * @see #getData
237      * @see #getOffset
238      * @see #getLength
239      *
240      * @since 1.2
241      */
242     public synchronized void setData(byte[] buf, int offset, int length) {
243     /* this will check to see if buf is null */
244     if (length < 0 || offset < 0 ||
245         ((length + offset) > buf.length)) {
246         throw new IllegalArgumentException  ("illegal length or offset");
247     }
248     this.buf = buf;
249     this.length = length;
250     this.bufLength = length;
251     this.offset = offset;
252     }
253 
254     /**
255      * Sets the IP address of the machine to which this datagram
256      * is being sent.
257      * @param iaddr the <code>InetAddress</code>
258      * @since   JDK1.1
259      * @see #getAddress()
260      */
261     public synchronized void setAddress(InetAddress   iaddr) {
262     address = iaddr;
263     }
264 
265     /**
266      * Sets the port number on the remote host to which this datagram
267      * is being sent.
268      * @param iport the port number
269      * @since   JDK1.1
270      * @see #getPort()
271      */
272     public synchronized void setPort(int iport) {
273     if (iport < 0 || iport > 0xFFFF) {
274         throw new IllegalArgumentException  ("Port out of range:"+ iport);
275     }
276     port = iport;
277     }
278 
279     /**
280      * Sets the SocketAddress (usually IP address + port number) of the remote
281      * host to which this datagram is being sent.
282      *
283      * @param address the <code>SocketAddress</code>
284      * @throws  IllegalArgumentException if address is null or is a
285      *          SocketAddress subclass not supported by this socket
286      * 
287      * @since 1.4
288      * @see #getSocketAddress
289      */
290     public synchronized void setSocketAddress(SocketAddress   address) {
291     if (address == null || !(address instanceof InetSocketAddress  ))
292         throw new IllegalArgumentException  ("unsupported address type");
293     InetSocketAddress   addr = (InetSocketAddress  ) address;
294     if (addr.isUnresolved())
295         throw new IllegalArgumentException  ("unresolved address");
296     setAddress(addr.getAddress());
297     setPort(addr.getPort());
298     }
299 
300     /**
301      * Gets the SocketAddress (usually IP address + port number) of the remote
302      * host that this packet is being sent to or is coming from.
303      *
304      * @return the <code>SocketAddress</code>
305      * @since 1.4
306      * @see #setSocketAddress
307      */
308     public synchronized SocketAddress   getSocketAddress() {
309     return new InetSocketAddress  (getAddress(), getPort());
310     }
311 
312     /** 
313      * Set the data buffer for this packet. With the offset of 
314      * this DatagramPacket set to 0, and the length set to
315      * the length of <code>buf</code>.
316      *
317      * @param buf the buffer to set for this packet.
318      *
319      * @exception NullPointerException if the argument is null.
320      *
321      * @see #getLength
322      * @see #getData
323      *
324      * @since JDK1.1 
325      */
326     public synchronized void setData(byte[] buf) {
327     if (buf == null) {
328         throw new NullPointerException  ("null packet buffer");
329     }
330     this.buf = buf;
331     this.offset = 0;
332     this.length = buf.length;
333     this.bufLength = buf.length;
334     }
335 
336     /**  
337      * Set the length for this packet. The length of the packet is
338      * the number of bytes from the packet's data buffer that will be
339      * sent, or the number of bytes of the packet's data buffer that
340      * will be used for receiving data. The length must be lesser or
341      * equal to the offset plus the length of the packet's buffer.
342      *
343      * @param length the length to set for this packet.
344      * 
345      * @exception IllegalArgumentException if the length is negative
346      * of if the length is greater than the packet's data buffer
347      * length.
348      *
349      * @see #getLength
350      * @see #setData
351      *
352      * @since JDK1.1 
353      */
354     public synchronized void setLength(int length) {
355     if ((length + offset) > buf.length || length < 0) {
356         throw new IllegalArgumentException  ("illegal length");
357     }
358     this.length = length;
359     this.bufLength = this.length;
360     }
361 
362     /**
363      * Perform class load-time initializations.  
364      */
365     private native static void init();
366 }
367 
368 
369 
370
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags