libjava/java/net/SocketImpl.java

   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., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 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 }