001/* DatagramSocketImpl.java -- Abstract class for UDP socket implementations 002 Copyright (C) 1998, 1999 2000, 2001, 003 2002, 2003 Free Software Foundation, Inc. 004 005This file is part of GNU Classpath. 006 007GNU Classpath is free software; you can redistribute it and/or modify 008it under the terms of the GNU General Public License as published by 009the Free Software Foundation; either version 2, or (at your option) 010any later version. 011 012GNU Classpath is distributed in the hope that it will be useful, but 013WITHOUT ANY WARRANTY; without even the implied warranty of 014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015General Public License for more details. 016 017You should have received a copy of the GNU General Public License 018along with GNU Classpath; see the file COPYING. If not, write to the 019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02002110-1301 USA. 021 022Linking this library statically or dynamically with other modules is 023making a combined work based on this library. Thus, the terms and 024conditions of the GNU General Public License cover the whole 025combination. 026 027As a special exception, the copyright holders of this library give you 028permission to link this library with independent modules to produce an 029executable, regardless of the license terms of these independent 030modules, and to copy and distribute the resulting executable under 031terms of your choice, provided that you also meet, for each linked 032independent module, the terms and conditions of the license of that 033module. An independent module is a module which is not derived from 034or based on this library. If you modify this library, you may extend 035this exception to your version of the library, but you are not 036obligated to do so. If you do not wish to do so, delete this 037exception statement from your version. */ 038 039package java.net; 040 041import java.io.FileDescriptor; 042import java.io.IOException; 043 044 045/** 046 * This abstract class models a datagram socket implementation. An 047 * actual implementation class would implement these methods, probably 048 * via redirecting them to native code. 049 * <p> 050 * Written using on-line Java Platform 1.2 API Specification, as well 051 * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998). 052 * <p> 053 * Status: Believed complete and correct. 054 * 055 * @author Aaron M. Renn (arenn@urbanophile.com) 056 * @author Warren Levy (warrenl@cygnus.com) 057 * @since 1.1 058 */ 059public abstract class DatagramSocketImpl implements SocketOptions 060{ 061 /** 062 * The local port to which this socket is bound 063 */ 064 protected int localPort; 065 066 /** 067 * The FileDescriptor object for this object. 068 */ 069 protected FileDescriptor fd; 070 071 /** 072 * Default, no-argument constructor for subclasses to call. 073 */ 074 public DatagramSocketImpl() 075 { 076 } 077 078 /** 079 * This method binds the socket to the specified local port and address. 080 * 081 * @param lport The port number to bind to 082 * @param laddr The address to bind to 083 * 084 * @exception SocketException If an error occurs 085 */ 086 protected abstract void bind(int lport, InetAddress laddr) 087 throws SocketException; 088 089 /** 090 * This methods closes the socket 091 */ 092 protected abstract void close(); 093 094 /** 095 * Creates a new datagram socket. 096 * 097 * @exception SocketException If an error occurs 098 */ 099 protected abstract void create() throws SocketException; 100 101 /** 102 * Takes a peek at the next packet received in order to retrieve the 103 * address of the sender 104 * 105 * @param i The <code>InetAddress</code> to fill in with the information 106 * about the sender if the next packet 107 * 108 * @return The port number of the sender of the packet 109 * 110 * @exception IOException If an error occurs 111 * @exception PortUnreachableException May be thrown if the socket is 112 * connected to a currently unreachable destination. Note, there is no 113 * guarantee that the exception will be thrown. 114 */ 115 protected abstract int peek(InetAddress i) throws IOException; 116 117 /** 118 * Takes a peek at the next packet received. This packet is not consumed. 119 * With the next peekData/receive operation this packet will be read again. 120 * 121 * @param p The <code>DatagramPacket</code> to fill in with the data sent. 122 * 123 * @return The port number of the sender of the packet. 124 * 125 * @exception IOException If an error occurs 126 * @exception PortUnreachableException May be thrown if the socket is 127 * connected to a currently unreachable destination. Note, there is no 128 * guarantee that the exception will be thrown. 129 * 130 * @since 1.4 131 */ 132 protected abstract int peekData(DatagramPacket p) throws IOException; 133 134 /** 135 * Transmits the specified packet of data to the network. The destination 136 * host and port should be encoded in the packet. 137 * 138 * @param p The packet to send 139 * 140 * @exception IOException If an error occurs 141 * @exception PortUnreachableException May be thrown if the socket is 142 * connected to a currently unreachable destination. Note, there is no 143 * guarantee that the exception will be thrown. 144 */ 145 protected abstract void send(DatagramPacket p) throws IOException; 146 147 /** 148 * Receives a packet of data from the network Will block until a packet 149 * arrives. The packet info in populated into the passed in 150 * <code>DatagramPacket</code> object. 151 * 152 * @param p A place to store the incoming packet. 153 * 154 * @exception IOException If an error occurs 155 * @exception PortUnreachableException May be thrown if the socket is 156 * connected to a currently unreachable destination. Note, there is no 157 * guarantee that the exception will be thrown. 158 */ 159 protected abstract void receive(DatagramPacket p) throws IOException; 160 161 /** 162 * Connects the socket to a host specified by address and port. 163 * 164 * @param address The <code>InetAddress</code> of the host to connect to 165 * @param port The port number of the host to connect to 166 * 167 * @exception SocketException If an error occurs 168 * 169 * @since 1.4 170 */ 171 protected void connect(InetAddress address, int port) 172 throws SocketException 173 { 174 // This method has to be overwritten by real implementations 175 } 176 177 /** 178 * Disconnects the socket. 179 * 180 * @since 1.4 181 */ 182 protected void disconnect() 183 { 184 // This method has to be overwritten by real implementations 185 } 186 187 /** 188 * Sets the Time to Live (TTL) setting on this socket to the specified 189 * value. <b>Use <code>setTimeToLive(int)</code></b> instead. 190 * 191 * @param ttl The new Time to Live value 192 * 193 * @exception IOException If an error occurs 194 * @deprecated 195 */ 196 protected abstract void setTTL(byte ttl) throws IOException; 197 198 /** 199 * This method returns the current Time to Live (TTL) setting on this 200 * socket. <b>Use <code>getTimeToLive()</code></b> instead. 201 * 202 * @return the current time-to-live 203 * 204 * @exception IOException If an error occurs 205 * 206 * @deprecated // FIXME: when ? 207 */ 208 protected abstract byte getTTL() throws IOException; 209 210 /** 211 * Sets the Time to Live (TTL) setting on this socket to the specified 212 * value. 213 * 214 * @param ttl The new Time to Live value 215 * 216 * @exception IOException If an error occurs 217 */ 218 protected abstract void setTimeToLive(int ttl) throws IOException; 219 220 /** 221 * This method returns the current Time to Live (TTL) setting on this 222 * socket. 223 * 224 * @return the current time-to-live 225 * 226 * @exception IOException If an error occurs 227 */ 228 protected abstract int getTimeToLive() throws IOException; 229 230 /** 231 * Causes this socket to join the specified multicast group 232 * 233 * @param inetaddr The multicast address to join with 234 * 235 * @exception IOException If an error occurs 236 */ 237 protected abstract void join(InetAddress inetaddr) throws IOException; 238 239 /** 240 * Causes the socket to leave the specified multicast group. 241 * 242 * @param inetaddr The multicast address to leave 243 * 244 * @exception IOException If an error occurs 245 */ 246 protected abstract void leave(InetAddress inetaddr) throws IOException; 247 248 /** 249 * Causes this socket to join the specified multicast group on a specified 250 * device 251 * 252 * @param mcastaddr The address to leave 253 * @param netIf The specified network interface to join the group at 254 * 255 * @exception IOException If an error occurs 256 * 257 * @since 1.4 258 */ 259 protected abstract void joinGroup(SocketAddress mcastaddr, 260 NetworkInterface netIf) 261 throws IOException; 262 263 /** 264 * Leaves a multicast group 265 * 266 * @param mcastaddr The address to join 267 * @param netIf The specified network interface to leave the group at 268 * 269 * @exception IOException If an error occurs 270 * 271 * @since 1.4 272 */ 273 protected abstract void leaveGroup(SocketAddress mcastaddr, 274 NetworkInterface netIf) 275 throws IOException; 276 277 /** 278 * Returns the FileDescriptor for this socket 279 * 280 * @return the file descriptor associated with this socket 281 */ 282 protected FileDescriptor getFileDescriptor() 283 { 284 return fd; 285 } 286 287 /** 288 * Returns the local port this socket is bound to 289 * 290 * @return the local port 291 */ 292 protected int getLocalPort() 293 { 294 return localPort; 295 } 296}