Source for java.net.DatagramSocketImpl

   1: /* DatagramSocketImpl.java -- Abstract class for UDP socket implementations
   2:    Copyright (C) 1998, 1999 2000, 2001,
   3:                  2002, 2003 Free Software Foundation, Inc.
   4: 
   5: This file is part of GNU Classpath.
   6: 
   7: GNU Classpath is free software; you can redistribute it and/or modify
   8: it under the terms of the GNU General Public License as published by
   9: the Free Software Foundation; either version 2, or (at your option)
  10: any later version.
  11: 
  12: GNU Classpath is distributed in the hope that it will be useful, but
  13: WITHOUT ANY WARRANTY; without even the implied warranty of
  14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15: General Public License for more details.
  16: 
  17: You should have received a copy of the GNU General Public License
  18: along with GNU Classpath; see the file COPYING.  If not, write to the
  19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20: 02110-1301 USA.
  21: 
  22: Linking this library statically or dynamically with other modules is
  23: making a combined work based on this library.  Thus, the terms and
  24: conditions of the GNU General Public License cover the whole
  25: combination.
  26: 
  27: As a special exception, the copyright holders of this library give you
  28: permission to link this library with independent modules to produce an
  29: executable, regardless of the license terms of these independent
  30: modules, and to copy and distribute the resulting executable under
  31: terms of your choice, provided that you also meet, for each linked
  32: independent module, the terms and conditions of the license of that
  33: module.  An independent module is a module which is not derived from
  34: or based on this library.  If you modify this library, you may extend
  35: this exception to your version of the library, but you are not
  36: obligated to do so.  If you do not wish to do so, delete this
  37: exception statement from your version. */
  38: 
  39: package java.net;
  40: 
  41: import java.io.FileDescriptor;
  42: import java.io.IOException;
  43: 
  44: 
  45: /**
  46:  * This abstract class models a datagram socket implementation.  An
  47:  * actual implementation class would implement these methods, probably
  48:  * via redirecting them to native code.
  49:  * <p>
  50:  * Written using on-line Java Platform 1.2 API Specification, as well
  51:  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  52:  * <p>
  53:  * Status:  Believed complete and correct.
  54:  *
  55:  * @author Aaron M. Renn (arenn@urbanophile.com)
  56:  * @author Warren Levy (warrenl@cygnus.com)
  57:  * @since 1.1
  58:  */
  59: public abstract class DatagramSocketImpl implements SocketOptions
  60: {
  61:   /**
  62:    * The local port to which this socket is bound
  63:    */
  64:   protected int localPort;
  65: 
  66:   /**
  67:    * The FileDescriptor object for this object.
  68:    */
  69:   protected FileDescriptor fd;
  70: 
  71:   /**
  72:    * Default, no-argument constructor for subclasses to call.
  73:    */
  74:   public DatagramSocketImpl()
  75:   {
  76:   }
  77: 
  78:   /**
  79:    * This method binds the socket to the specified local port and address.
  80:    *
  81:    * @param lport The port number to bind to
  82:    * @param laddr The address to bind to
  83:    *
  84:    * @exception SocketException If an error occurs
  85:    */
  86:   protected abstract void bind(int lport, InetAddress laddr)
  87:     throws SocketException;
  88: 
  89:   /**
  90:    * This methods closes the socket
  91:    */
  92:   protected abstract void close();
  93: 
  94:   /**
  95:    * Creates a new datagram socket.
  96:    *
  97:    * @exception SocketException If an error occurs
  98:    */
  99:   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: }