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 localhost/port. Sockets must be 47 * bound prior to attempting to send or receive data. 48 * 49 * @param port 50 * the port on the localhost to bind. 51 * @param addr 52 * the address on the multihomed localhost to bind. 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