View Javadoc
1   /*
2    * Copyright (c) 1996, 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  
26  package java.net;
27  
28  import java.io.FileDescriptor;
29  import java.io.IOException;
30  import java.io.InterruptedIOException;
31  
32  /**
33   * Abstract datagram and multicast socket implementation base class.
34   * @author Pavani Diwanji
35   * @since  JDK1.1
36   */
37  
38  public abstract class DatagramSocketImpl implements SocketOptions {
39  
40      /**
41       * The local port number.
42       */
43      protected int localPort;
44  
45      /**
46       * The file descriptor object.
47       */
48      protected FileDescriptor fd;
49  
50      /**
51       * Creates a datagram socket.
52       * @exception SocketException if there is an error in the
53       * underlying protocol, such as a TCP error.
54       */
55      protected abstract void create() throws SocketException;
56  
57      /**
58       * Binds a datagram socket to a local port and address.
59       * @param lport the local port
60       * @param laddr the local address
61       * @exception SocketException if there is an error in the
62       * underlying protocol, such as a TCP error.
63       */
64      protected abstract void bind(int lport, InetAddress laddr) throws SocketException;
65  
66      /**
67       * Sends a datagram packet. The packet contains the data and the
68       * destination address to send the packet to.
69       * @param p the packet to be sent.
70       * @exception IOException if an I/O exception occurs while sending the
71       * datagram packet.
72       * @exception  PortUnreachableException may be thrown if the socket is connected
73       * to a currently unreachable destination. Note, there is no guarantee that
74       * the exception will be thrown.
75       */
76      protected abstract void send(DatagramPacket p) throws IOException;
77  
78      /**
79       * Connects a datagram socket to a remote destination. This associates the remote
80       * address with the local socket so that datagrams may only be sent to this destination
81       * and received from this destination. This may be overridden to call a native
82       * system connect.
83       *
84       * <p>If the remote destination to which the socket is connected does not
85       * exist, or is otherwise unreachable, and if an ICMP destination unreachable
86       * packet has been received for that address, then a subsequent call to
87       * send or receive may throw a PortUnreachableException.
88       * Note, there is no guarantee that the exception will be thrown.
89       * @param address the remote InetAddress to connect to
90       * @param port the remote port number
91       * @exception   SocketException may be thrown if the socket cannot be
92       * connected to the remote destination
93       * @since 1.4
94       */
95      protected void connect(InetAddress address, int port) throws SocketException {}
96  
97      /**
98       * Disconnects a datagram socket from its remote destination.
99       * @since 1.4
100      */
101     protected void disconnect() {}
102 
103     /**
104      * Peek at the packet to see who it is from. Updates the specified {@code InetAddress}
105      * to the address which the packet came from.
106      * @param i an InetAddress object
107      * @return the port number which the packet came from.
108      * @exception IOException if an I/O exception occurs
109      * @exception  PortUnreachableException may be thrown if the socket is connected
110      *       to a currently unreachable destination. Note, there is no guarantee that the
111      *       exception will be thrown.
112      */
113     protected abstract int peek(InetAddress i) throws IOException;
114 
115     /**
116      * Peek at the packet to see who it is from. The data is copied into the specified
117      * {@code DatagramPacket}. The data is returned,
118      * but not consumed, so that a subsequent peekData/receive operation
119      * will see the same data.
120      * @param p the Packet Received.
121      * @return the port number which the packet came from.
122      * @exception IOException if an I/O exception occurs
123      * @exception  PortUnreachableException may be thrown if the socket is connected
124      *       to a currently unreachable destination. Note, there is no guarantee that the
125      *       exception will be thrown.
126      * @since 1.4
127      */
128     protected abstract int peekData(DatagramPacket p) throws IOException;
129     /**
130      * Receive the datagram packet.
131      * @param p the Packet Received.
132      * @exception IOException if an I/O exception occurs
133      * while receiving the datagram packet.
134      * @exception  PortUnreachableException may be thrown if the socket is connected
135      *       to a currently unreachable destination. Note, there is no guarantee that the
136      *       exception will be thrown.
137      */
138     protected abstract void receive(DatagramPacket p) throws IOException;
139 
140     /**
141      * Set the TTL (time-to-live) option.
142      * @param ttl a byte specifying the TTL value
143      *
144      * @deprecated use setTimeToLive instead.
145      * @exception IOException if an I/O exception occurs while setting
146      * the time-to-live option.
147      * @see #getTTL()
148      */
149     @Deprecated
150     protected abstract void setTTL(byte ttl) throws IOException;
151 
152     /**
153      * Retrieve the TTL (time-to-live) option.
154      *
155      * @exception IOException if an I/O exception occurs
156      * while retrieving the time-to-live option
157      * @deprecated use getTimeToLive instead.
158      * @return a byte representing the TTL value
159      * @see #setTTL(byte)
160      */
161     @Deprecated
162     protected abstract byte getTTL() throws IOException;
163 
164     /**
165      * Set the TTL (time-to-live) option.
166      * @param ttl an {@code int} specifying the time-to-live value
167      * @exception IOException if an I/O exception occurs
168      * while setting the time-to-live option.
169      * @see #getTimeToLive()
170      */
171     protected abstract void setTimeToLive(int ttl) throws IOException;
172 
173     /**
174      * Retrieve the TTL (time-to-live) option.
175      * @exception IOException if an I/O exception occurs
176      * while retrieving the time-to-live option
177      * @return an {@code int} representing the time-to-live value
178      * @see #setTimeToLive(int)
179      */
180     protected abstract int getTimeToLive() throws IOException;
181 
182     /**
183      * Join the multicast group.
184      * @param inetaddr multicast address to join.
185      * @exception IOException if an I/O exception occurs
186      * while joining the multicast group.
187      */
188     protected abstract void join(InetAddress inetaddr) throws IOException;
189 
190     /**
191      * Leave the multicast group.
192      * @param inetaddr multicast address to leave.
193      * @exception IOException if an I/O exception occurs
194      * while leaving the multicast group.
195      */
196     protected abstract void leave(InetAddress inetaddr) throws IOException;
197 
198     /**
199      * Join the multicast group.
200      * @param mcastaddr address to join.
201      * @param netIf specifies the local interface to receive multicast
202      *        datagram packets
203      * @throws IOException if an I/O exception occurs while joining
204      * the multicast group
205      * @since 1.4
206      */
207     protected abstract void joinGroup(SocketAddress mcastaddr,
208                                       NetworkInterface netIf)
209         throws IOException;
210 
211     /**
212      * Leave the multicast group.
213      * @param mcastaddr address to leave.
214      * @param netIf specified the local interface to leave the group at
215      * @throws IOException if an I/O exception occurs while leaving
216      * the multicast group
217      * @since 1.4
218      */
219     protected abstract void leaveGroup(SocketAddress mcastaddr,
220                                        NetworkInterface netIf)
221         throws IOException;
222 
223     /**
224      * Close the socket.
225      */
226     protected abstract void close();
227 
228     /**
229      * Gets the local port.
230      * @return an {@code int} representing the local port value
231      */
232     protected int getLocalPort() {
233         return localPort;
234     }
235 
236     /**
237      * Gets the datagram socket file descriptor.
238      * @return a {@code FileDescriptor} object representing the datagram socket
239      * file descriptor
240      */
241     protected FileDescriptor getFileDescriptor() {
242         return fd;
243     }
244 }