Source for java.net.SocketImpl

   1: /* SocketImpl.java -- Abstract socket implementation class
   2:    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
   3:    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: import java.io.InputStream;
  44: import java.io.OutputStream;
  45: 
  46: 
  47: /* Written using on-line Java Platform 1.2 API Specification.
  48:  * Believed complete and correct.
  49:  */
  50: 
  51: /**
  52:  * This abstract class serves as the parent class for socket implementations.
  53:  * The implementation class serves an intermediary to native routines that
  54:  * perform system specific socket operations.
  55:  * <p>
  56:  * A default implementation is provided by the system, but this can be
  57:  * changed via installing a <code>SocketImplFactory</code> (through a call
  58:  * to the static method <code>Socket.setSocketImplFactory</code>).  A
  59:  * subclass of <code>Socket</code> can also pass in a <code>SocketImpl</code>
  60:  * to the <code>Socket(SocketImpl)</code> constructor to use an
  61:  * implementation different from the system default without installing
  62:  * a factory.
  63:  *
  64:  * @author Aaron M. Renn (arenn@urbanophile.com)
  65:  * @author Per Bothner (bothner@cygnus.com)
  66:  */
  67: public abstract class SocketImpl implements SocketOptions
  68: {
  69:   /**
  70:    * The address of the remote end of the socket connection
  71:    */
  72:   protected InetAddress address;
  73: 
  74:   /**
  75:    * A FileDescriptor object representing this socket connection.
  76:    */
  77:   protected FileDescriptor fd;
  78: 
  79:   /**
  80:    * The port number the socket is bound to locally
  81:    */
  82:   protected int localport = -1;
  83: 
  84:   /**
  85:    * The port number of the remote end of the socket connection
  86:    */
  87:   protected int port;
  88: 
  89:   /**
  90:    * Default, no-argument constructor for use by subclasses.
  91:    */
  92:   public SocketImpl()
  93:   {
  94:   }
  95: 
  96:   /**
  97:    * Creates a new socket that is not bound to any local address/port and
  98:    * is not connected to any remote address/port.  This will be created as
  99:    * a stream socket if the stream parameter is true, or a datagram socket
 100:    * if the stream parameter is false.
 101:    *
 102:    * @param stream true for a stream socket, false for a datagram socket
 103:    *
 104:    * @exception IOException If an error occurs
 105:    */
 106:   protected abstract void create(boolean stream) throws IOException;
 107: 
 108:   /**
 109:    * Connects to the remote hostname and port specified as arguments.
 110:    *
 111:    * @param host The remote hostname to connect to
 112:    * @param port The remote port to connect to
 113:    *
 114:    * @exception IOException If an error occurs
 115:    */
 116:   protected abstract void connect(String host, int port)
 117:     throws IOException;
 118: 
 119:   /**
 120:    * Connects to the remote address and port specified as arguments.
 121:    *
 122:    * @param host The remote address to connect to
 123:    * @param port The remote port to connect to
 124:    *
 125:    * @exception IOException If an error occurs
 126:    */
 127:   protected abstract void connect(InetAddress host, int port)
 128:     throws IOException;
 129: 
 130:   /**
 131:    * Connects to the socket to the host specified in address. This
 132:    * method blocks until successful connected or the timeout occurs.
 133:    * A timeout of zero means no timout.
 134:    *
 135:    * @param address Data of remote host
 136:    * @param timeout time to wait to stop connecting
 137:    *
 138:    * @exception IOException If an error occurs
 139:    *
 140:    * @since 1.4
 141:    */
 142:   protected abstract void connect(SocketAddress address, int timeout)
 143:     throws IOException;
 144: 
 145:   /**
 146:    * Binds to the specified port on the specified addr.  Note that this addr
 147:    * must represent a local IP address.
 148:    * <p>
 149:    * Note that it is unspecified how to bind to all interfaces on the localhost
 150:    * (INADDR_ANY).
 151:    *
 152:    * @param host The address to bind to
 153:    * @param port The port number to bind to
 154:    *
 155:    * @exception IOException If an error occurs
 156:    */
 157:   protected abstract void bind(InetAddress host, int port)
 158:     throws IOException;
 159: 
 160:   /**
 161:    * Starts listening for connections on a socket. The backlog parameter
 162:    * is how many pending connections will queue up waiting to be serviced
 163:    * before being accept'ed.  If the queue of pending requests exceeds this
 164:    * number, additional connections will be refused.
 165:    *
 166:    * @param backlog The length of the pending connection queue
 167:    *
 168:    * @exception IOException If an error occurs
 169:    */
 170:   protected abstract void listen(int backlog) throws IOException;
 171: 
 172:   /**
 173:    * Accepts a connection on this socket.
 174:    *
 175:    * @param s The implementation object for the accepted connection.
 176:    *
 177:    * @exception IOException If an error occurs
 178:    */
 179:   protected abstract void accept(SocketImpl s) throws IOException;
 180: 
 181:   /**
 182:    * Returns an <code>InputStream</code> object for reading from this socket.
 183:    *
 184:    * @return An <code>InputStream</code> for reading from this socket.
 185:    *
 186:    * @exception IOException If an error occurs
 187:    */
 188:   protected abstract InputStream getInputStream() throws IOException;
 189: 
 190:   /**
 191:    * Returns an <code>OutputStream</code> object for writing to this socket
 192:    *
 193:    * @return An <code>OutputStream</code> for writing to this socket.
 194:    *
 195:    * @exception IOException If an error occurs.
 196:    */
 197:   protected abstract OutputStream getOutputStream() throws IOException;
 198: 
 199:   /**
 200:    * Returns the number of bytes that the caller can read from this socket
 201:    * without blocking.
 202:    *
 203:    * @return The number of readable bytes before blocking
 204:    *
 205:    * @exception IOException If an error occurs
 206:    */
 207:   protected abstract int available() throws IOException;
 208: 
 209:   /**
 210:    * Closes the socket.  This will normally cause any resources, such as the
 211:    * InputStream, OutputStream and associated file descriptors  to be freed.
 212:    * <p>
 213:    * Note that if the SO_LINGER option is set on this socket, then the
 214:    * operation could block.
 215:    *
 216:    * @exception IOException If an error occurs
 217:    */
 218:   protected abstract void close() throws IOException;
 219: 
 220:   /**
 221:    * Returns the FileDescriptor objects for this socket.
 222:    *
 223:    * @return A FileDescriptor for this socket.
 224:    */
 225:   protected FileDescriptor getFileDescriptor()
 226:   {
 227:     return fd;
 228:   }
 229: 
 230:   /**
 231:    * Returns the remote address this socket is connected to
 232:    *
 233:    * @return The remote address
 234:    */
 235:   protected InetAddress getInetAddress()
 236:   {
 237:     return address;
 238:   }
 239: 
 240:   /**
 241:    * Returns the remote port this socket is connected to
 242:    *
 243:    * @return The remote port
 244:    */
 245:   protected int getPort()
 246:   {
 247:     return port;
 248:   }
 249: 
 250:   /**
 251:    * Returns true or false when this socket supports sending urgent data
 252:    * or not.
 253:    *
 254:    * @return true if the socket implementation supports sending urgent data,
 255:    * false otherwise
 256:    *
 257:    * @since 1.4
 258:    */
 259:   protected boolean supportsUrgentData()
 260:   {
 261:     // This method has to be overwritten by socket classes that support
 262:     // sending urgend data.
 263:     return false;
 264:   }
 265: 
 266:   /**
 267:    * Sends one byte of urgent data to the socket.
 268:    *
 269:    * @param data The byte to send, the low eight bits of it
 270:    *
 271:    * @exception IOException If an error occurs
 272:    *
 273:    * @since 1.4
 274:    */
 275:   protected abstract void sendUrgentData(int data) throws IOException;
 276: 
 277:   /**
 278:    * Returns the local port this socket is bound to
 279:    *
 280:    * @return The local port
 281:    */
 282:   protected int getLocalPort()
 283:   {
 284:     return localport;
 285:   }
 286: 
 287:   /**
 288:    * Returns a <code>String</code> representing the remote host and port of
 289:    * this socket.
 290:    *
 291:    * @return A <code>String</code> for this socket.
 292:    */
 293:   public String toString()
 294:   {
 295:     return "[addr="
 296:            + ((address == null) ? "0.0.0.0/0.0.0.0" : address.toString())
 297:            + ",port=" + port + ",localport=" + localport + "]";
 298:   }
 299: 
 300:   /**
 301:    * Shut down the input side of this socket.  Subsequent reads will
 302:    * return end-of-file.
 303:    *
 304:    * @exception IOException if an error occurs
 305:    */
 306:   protected void shutdownInput() throws IOException
 307:   {
 308:     throw new IOException("Not implemented in this socket class");
 309:   }
 310: 
 311:   /**
 312:    * Shut down the output side of this socket.  Subsequent writes will
 313:    * fail with an IOException.
 314:    *
 315:    * @exception IOException if an error occurs
 316:    */
 317:   protected void shutdownOutput() throws IOException
 318:   {
 319:     throw new IOException("Not implemented in this socket class");
 320:   }
 321: }