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
  40 package java.net;
  41
  42 import java.io.FileDescriptor;
  43 import java.io.InputStream;
  44 import java.io.IOException;
  45 import java.io.OutputStream;
  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) throws IOException;
 117
 118   /**
 119    * Connects to the remote address and port specified as arguments.
 120    *
 121    * @param host The remote address to connect to
 122    * @param port The remote port to connect to
 123    *
 124    * @exception IOException If an error occurs
 125    */
 126   protected abstract void connect(InetAddress host, int port)
 127     throws IOException;
 128
 129   /**
 130    * Connects to the socket to the host specified in address. This
 131    * method blocks until successful connected or the timeout occurs.
 132    * A timeout of zero means no timout.
 133    *
 134    * @param address Data of remote host
 135    * @param timeout time to wait to stop connecting
 136    *
 137    * @exception IOException If an error occurs
 138    *
 139    * @since 1.4
 140    */
 141   protected abstract void connect(SocketAddress address, int timeout)
 142     throws IOException;
 143
 144   /**
 145    * Binds to the specified port on the specified addr.  Note that this addr
 146    * must represent a local IP address.
 147    * <p>
 148    * Note that it is unspecified how to bind to all interfaces on the localhost
 149    * (INADDR_ANY).
 150    *
 151    * @param host The address to bind to
 152    * @param port The port number to bind to
 153    *
 154    * @exception IOException If an error occurs
 155    */
 156   protected abstract void bind(InetAddress host, int port) throws IOException;
 157
 158   /**
 159    * Starts listening for connections on a socket. The backlog parameter
 160    * is how many pending connections will queue up waiting to be serviced
 161    * before being accept'ed.  If the queue of pending requests exceeds this
 162    * number, additional connections will be refused.
 163    *
 164    * @param backlog The length of the pending connection queue
 165    *
 166    * @exception IOException If an error occurs
 167    */
 168   protected abstract void listen(int backlog) throws IOException;
 169
 170   /**
 171    * Accepts a connection on this socket.
 172    *
 173    * @param s The implementation object for the accepted connection.
 174    *
 175    * @exception IOException If an error occurs
 176    */
 177   protected abstract void accept(SocketImpl s) throws IOException;
 178
 179   /**
 180    * Returns an <code>InputStream</code> object for reading from this socket.
 181    *
 182    * @return An <code>InputStream</code> for reading from this socket.
 183    *
 184    * @exception IOException If an error occurs
 185    */
 186   protected abstract InputStream getInputStream() throws IOException;
 187
 188   /**
 189    * Returns an <code>OutputStream</code> object for writing to this socket
 190    *
 191    * @return An <code>OutputStream</code> for writing to this socket.
 192    *
 193    * @exception IOException If an error occurs.
 194    */
 195   protected abstract OutputStream getOutputStream() throws IOException;
 196
 197   /**
 198    * Returns the number of bytes that the caller can read from this socket
 199    * without blocking.
 200    *
 201    * @return The number of readable bytes before blocking
 202    *
 203    * @exception IOException If an error occurs
 204    */
 205   protected abstract int available() throws IOException;
 206
 207   /**
 208    * Closes the socket.  This will normally cause any resources, such as the
 209    * InputStream, OutputStream and associated file descriptors  to be freed.
 210    * <p>
 211    * Note that if the SO_LINGER option is set on this socket, then the
 212    * operation could block.
 213    *
 214    * @exception IOException If an error occurs
 215    */
 216   protected abstract void close() throws IOException;
 217
 218   /**
 219    * Returns the FileDescriptor objects for this socket.
 220    *
 221    * @return A FileDescriptor for this socket.
 222    */
 223   protected FileDescriptor getFileDescriptor() { return fd; }
 224
 225   /**
 226    * Returns the remote address this socket is connected to
 227    *
 228    * @return The remote address
 229    */
 230   protected InetAddress getInetAddress() { return address; }
 231
 232   /**
 233    * Returns the remote port this socket is connected to
 234    *
 235    * @return The remote port
 236    */
 237   protected int getPort() { return port; }
 238
 239   /**
 240    * Returns true or false when this socket supports sending urgent data
 241    * or not.
 242    *
 243    * @since 1.4
 244    */
 245   protected boolean supportsUrgentData()
 246   {
 247     // This method has to be overwritten by socket classes that support
 248     // sending urgend data.
 249     return false;
 250   }
 251
 252   /**
 253    * Sends one byte of urgent data to the socket.
 254    *
 255    * @param data The byte to send, the low eight bits of it
 256    *
 257    * @exception IOException If an error occurs
 258    *
 259    * @since 1.4
 260    */
 261   protected abstract void sendUrgentData(int data)
 262     throws IOException;
 263
 264   /**
 265    * Returns the local port this socket is bound to
 266    *
 267    * @return The local port
 268    */
 269   protected int getLocalPort() { return localport; }
 270
 271   /**
 272    * Returns a <code>String</code> representing the remote host and port of
 273    * this socket.
 274    *
 275    * @return A <code>String</code> for this socket.
 276    */
 277   public String toString()
 278   {
 279     return "[addr=" + ((address == null) ? "0.0.0.0/0.0.0.0" :
 280                        address.toString())
 281             + ",port=" + port
 282             + ",localport=" + localport + "]";
 283   }
 284
 285   /**
 286    * Shut down the input side of this socket.  Subsequent reads will
 287    * return end-of-file.
 288    *
 289    * @exception IOException if an error occurs
 290    */
 291   protected void shutdownInput () throws IOException
 292   {
 293     throw new IOException ("Not implemented in this socket class");
 294   }
 295
 296   /**
 297    * Shut down the output side of this socket.  Subsequent writes will
 298    * fail with an IOException.
 299    *
 300    * @exception IOException if an error occurs
 301    */
 302   protected void shutdownOutput () throws IOException
 303   {
 304     throw new IOException ("Not implemented in this socket class");
 305   }
 306 }