001/* SocketImpl.java -- Abstract socket implementation class 002 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 003 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; 043import java.io.InputStream; 044import java.io.OutputStream; 045 046 047/* Written using on-line Java Platform 1.2 API Specification. 048 * Believed complete and correct. 049 */ 050 051/** 052 * This abstract class serves as the parent class for socket implementations. 053 * The implementation class serves an intermediary to native routines that 054 * perform system specific socket operations. 055 * <p> 056 * A default implementation is provided by the system, but this can be 057 * changed via installing a <code>SocketImplFactory</code> (through a call 058 * to the static method <code>Socket.setSocketImplFactory</code>). A 059 * subclass of <code>Socket</code> can also pass in a <code>SocketImpl</code> 060 * to the <code>Socket(SocketImpl)</code> constructor to use an 061 * implementation different from the system default without installing 062 * a factory. 063 * 064 * @author Aaron M. Renn (arenn@urbanophile.com) 065 * @author Per Bothner (bothner@cygnus.com) 066 */ 067public abstract class SocketImpl implements SocketOptions 068{ 069 /** 070 * The address of the remote end of the socket connection 071 */ 072 protected InetAddress address; 073 074 /** 075 * A FileDescriptor object representing this socket connection. 076 */ 077 protected FileDescriptor fd; 078 079 /** 080 * The port number the socket is bound to locally 081 */ 082 protected int localport = -1; 083 084 /** 085 * The port number of the remote end of the socket connection 086 */ 087 protected int port; 088 089 /** 090 * Default, no-argument constructor for use by subclasses. 091 */ 092 public SocketImpl() 093 { 094 } 095 096 /** 097 * Creates a new socket that is not bound to any local address/port and 098 * is not connected to any remote address/port. This will be created as 099 * 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}