1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.net;
19
20import java.io.FileDescriptor;
21import java.io.IOException;
22
23/**
24 * The abstract superclass for datagram and multicast socket implementations.
25 */
26public abstract class DatagramSocketImpl implements SocketOptions {
27
28    /**
29     * File descriptor that is used to address this socket.
30     */
31    protected FileDescriptor fd;
32
33    /**
34     * The number of the local port to which this socket is bound.
35     */
36    protected int localPort;
37
38    /**
39     * Constructs an unbound datagram socket implementation.
40     */
41    public DatagramSocketImpl() {
42        localPort = -1;
43    }
44
45    /**
46     * Binds the datagram socket to the given local host/port. Sockets must be
47     * bound prior to attempting to send or receive data.
48     *
49     * @param port
50     *            the port on the local host to bind to.
51     * @param addr
52     *            the address on the multihomed local host to bind to.
53     * @throws SocketException
54     *                if an error occurs while binding, for example, if the port
55     *                has been already bound.
56     */
57    protected abstract void bind(int port, InetAddress addr) throws SocketException;
58
59    /**
60     * Closes this socket.
61     */
62    protected abstract void close();
63
64    /**
65     * This method allocates the socket descriptor in the underlying operating
66     * system.
67     *
68     * @throws SocketException
69     *             if an error occurs while creating the socket.
70     */
71    protected abstract void create() throws SocketException;
72
73    /**
74     * Gets the {@code FileDescriptor} of this datagram socket, which is invalid
75     * if the socket is closed or not bound.
76     *
77     * @return the current file descriptor of this socket.
78     */
79    protected FileDescriptor getFileDescriptor() {
80        return fd;
81    }
82
83    /**
84     * Returns the local port to which this socket is bound.
85     */
86    protected int getLocalPort() {
87        return localPort;
88    }
89
90    /**
91     * Gets the time-to-live (TTL) for multicast packets sent on this socket.
92     *
93     * @return the time-to-live option as a byte value.
94     * @throws IOException
95     *             if an error occurs while getting the time-to-live option
96     *             value.
97     * @deprecated Use {@link #getTimeToLive} instead.
98     * @see #getTimeToLive()
99     */
100    @Deprecated
101    protected abstract byte getTTL() throws IOException;
102
103    /**
104     * Gets the time-to-live (TTL) for multicast packets sent on this socket.
105     * The TTL option defines how many routers a packet may be pass before it is
106     * discarded.
107     *
108     * @return the time-to-live option as an integer value.
109     * @throws IOException
110     *             if an error occurs while getting the time-to-live option
111     *             value.
112     */
113    protected abstract int getTimeToLive() throws IOException;
114
115    /**
116     * Adds this socket to the multicast group {@code addr}. A socket must join
117     * a group before being able to receive data. Further, a socket may be a
118     * member of multiple groups but may join any group only once.
119     *
120     * @param addr
121     *            the multicast group to which this socket has to be joined.
122     * @throws IOException
123     *             if an error occurs while joining the specified multicast
124     *             group.
125     */
126    protected abstract void join(InetAddress addr) throws IOException;
127
128    /**
129     * Adds this socket to the multicast group {@code addr}. A socket must join
130     * a group before being able to receive data. Further, a socket may be a
131     * member of multiple groups but may join any group only once.
132     *
133     * @param addr
134     *            the multicast group to which this socket has to be joined.
135     * @param netInterface
136     *            the local network interface which will receive the multicast
137     *            datagram packets.
138     * @throws IOException
139     *             if an error occurs while joining the specified multicast
140     *             group.
141     */
142    protected abstract void joinGroup(SocketAddress addr,
143            NetworkInterface netInterface) throws IOException;
144
145    /**
146     * Removes this socket from the multicast group {@code addr}.
147     *
148     * @param addr
149     *            the multicast group to be left.
150     * @throws IOException
151     *             if an error occurs while leaving the group or no multicast
152     *             address was assigned.
153     */
154    protected abstract void leave(InetAddress addr) throws IOException;
155
156    /**
157     * Removes this socket from the multicast group {@code addr}.
158     *
159     * @param addr
160     *            the multicast group to be left.
161     * @param netInterface
162     *            the local network interface on which this socket has to be
163     *            removed.
164     * @throws IOException
165     *             if an error occurs while leaving the group.
166     */
167    protected abstract void leaveGroup(SocketAddress addr,
168            NetworkInterface netInterface) throws IOException;
169
170    /**
171     * Peeks at the incoming packet to this socket and returns the address of
172     * the {@code sender}. The method will block until a packet is received or
173     * timeout expires.
174     *
175     * @param sender
176     *            the origin address of a packet.
177     * @return the address of {@code sender} as an integer value.
178     * @throws IOException
179     *                if an error or a timeout occurs while reading the address.
180     */
181    protected abstract int peek(InetAddress sender) throws IOException;
182
183    /**
184     * Receives data and stores it in the supplied datagram packet {@code pack}.
185     * This call will block until either data has been received or, if a timeout
186     * is set, the timeout has expired. If the timeout expires an {@code
187     * InterruptedIOException} is thrown.
188     *
189     * @param pack
190     *            the datagram packet container to fill in the received data.
191     * @throws IOException
192     *                if an error or timeout occurs while receiving data.
193     */
194    protected abstract void receive(DatagramPacket pack) throws IOException;
195
196    /**
197     * Sends the given datagram packet {@code pack}. The packet contains the
198     * data and the address and port information of the target host as well.
199     *
200     * @param pack
201     *            the datagram packet to be sent.
202     * @throws IOException
203     *                if an error occurs while sending the packet.
204     */
205    protected abstract void send(DatagramPacket pack) throws IOException;
206
207    /**
208     * Sets the time-to-live (TTL) option for multicast packets sent on this
209     * socket.
210     *
211     * @param ttl
212     *            the time-to-live option value. Valid values are 0 < ttl
213     *            <= 255.
214     * @throws IOException
215     *             if an error occurs while setting the option.
216     */
217    protected abstract void setTimeToLive(int ttl) throws IOException;
218
219    /**
220     * Sets the time-to-live (TTL) option for multicast packets sent on this
221     * socket.
222     *
223     * @param ttl
224     *            the time-to-live option value. Valid values are 0 < ttl
225     *            <= 255.
226     * @throws IOException
227     *             if an error occurs while setting the option.
228     * @deprecated Use {@link #setTimeToLive} instead.
229     * @see #setTimeToLive(int)
230     */
231    @Deprecated
232    protected abstract void setTTL(byte ttl) throws IOException;
233
234    /**
235     * Connects this socket to the specified remote address and port.
236     *
237     * @param inetAddr
238     *            the address of the target host which has to be connected.
239     * @param port
240     *            the port on the target host which has to be connected.
241     * @throws SocketException
242     *                if the datagram socket cannot be connected to the
243     *                specified remote address and port.
244     */
245    protected void connect(InetAddress inetAddr, int port)
246            throws SocketException {
247        // do nothing
248    }
249
250    /**
251     * Disconnects this socket from the remote host.
252     */
253    protected void disconnect() {
254        // do nothing
255    }
256
257    /**
258     * Receives data into the supplied datagram packet by peeking. The data is
259     * not removed from socket buffer and can be received again by another
260     * {@code peekData()} or {@code receive()} call. This call blocks until
261     * either data has been received or, if a timeout is set, the timeout has
262     * been expired.
263     *
264     * @param pack
265     *            the datagram packet used to store the data.
266     * @return the port the packet was received from.
267     * @throws IOException
268     *                if an error occurs while peeking at the data.
269     */
270    protected abstract int peekData(DatagramPacket pack) throws IOException;
271
272    /**
273     * Initialize the bind() state.
274     * @hide used in java.nio.
275     */
276    protected void onBind(InetAddress localAddress, int localPort) {
277        // Do not add any code to these methods. They are concrete only to preserve API
278        // compatibility.
279    }
280
281    /**
282     * Initialize the connect() state.
283     * @hide used in java.nio.
284     */
285    protected void onConnect(InetAddress remoteAddress, int remotePort) {
286        // Do not add any code to these methods. They are concrete only to preserve API
287        // compatibility.
288    }
289
290    /**
291     * Initialize the disconnected state.
292     * @hide used in java.nio.
293     */
294    protected void onDisconnect() {
295        // Do not add any code to these methods. They are concrete only to preserve API
296        // compatibility.
297    }
298
299    /**
300     * Initialize the closed state.
301     * @hide used in java.nio.
302     */
303    protected void onClose() {
304        // Do not add any code to these methods. They are concrete only to preserve API
305        // compatibility.
306    }
307}
308