1 /*
2 * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net;
27
28 import java.io.IOException;
29 import java.io.InputStream;
30 import java.io.OutputStream;
31 import java.io.FileDescriptor;
32
33 /**
34 * The abstract class <code>SocketImpl</code> is a common superclass
35 * of all classes that actually implement sockets. It is used to
36 * create both client and server sockets.
37 * <p>
38 * A "plain" socket implements these methods exactly as
39 * described, without attempting to go through a firewall or proxy.
40 *
41 * @author unascribed
42 * @since JDK1.0
43 */
44 public abstract class SocketImpl implements SocketOptions {
45 /**
46 * The actual Socket object.
47 */
48 Socket socket = null;
49 ServerSocket serverSocket = null;
50
51 /**
52 * The file descriptor object for this socket.
53 */
54 protected FileDescriptor fd;
55
56 /**
57 * The IP address of the remote end of this socket.
58 */
59 protected InetAddress address;
60
61 /**
62 * The port number on the remote host to which this socket is connected.
63 */
64 protected int port;
65
66 /**
67 * The local port number to which this socket is connected.
68 */
69 protected int localport;
70
71 /**
72 * Creates either a stream or a datagram socket.
73 *
74 * @param stream if <code>true</code>, create a stream socket;
75 * otherwise, create a datagram socket.
76 * @exception IOException if an I/O error occurs while creating the
77 * socket.
78 */
79 protected abstract void create(boolean stream) throws IOException;
80
81 /**
82 * Connects this socket to the specified port on the named host.
83 *
84 * @param host the name of the remote host.
85 * @param port the port number.
86 * @exception IOException if an I/O error occurs when connecting to the
87 * remote host.
88 */
89 protected abstract void connect(String host, int port) throws IOException;
90
91 /**
92 * Connects this socket to the specified port number on the specified host.
93 *
94 * @param address the IP address of the remote host.
95 * @param port the port number.
96 * @exception IOException if an I/O error occurs when attempting a
97 * connection.
98 */
99 protected abstract void connect(InetAddress address, int port) throws IOException;
100
101 /**
102 * Connects this socket to the specified port number on the specified host.
103 * A timeout of zero is interpreted as an infinite timeout. The connection
104 * will then block until established or an error occurs.
105 *
106 * @param address the Socket address of the remote host.
107 * @param timeout the timeout value, in milliseconds, or zero for no timeout.
108 * @exception IOException if an I/O error occurs when attempting a
109 * connection.
110 * @since 1.4
111 */
112 protected abstract void connect(SocketAddress address, int timeout) throws IOException;
113
114 /**
115 * Binds this socket to the specified local IP address and port number.
116 *
117 * @param host an IP address that belongs to a local interface.
118 * @param port the port number.
119 * @exception IOException if an I/O error occurs when binding this socket.
120 */
121 protected abstract void bind(InetAddress host, int port) throws IOException;
122
123 /**
124 * Sets the maximum queue length for incoming connection indications
125 * (a request to connect) to the <code>count</code> argument. If a
126 * connection indication arrives when the queue is full, the
127 * connection is refused.
128 *
129 * @param backlog the maximum length of the queue.
130 * @exception IOException if an I/O error occurs when creating the queue.
131 */
132 protected abstract void listen(int backlog) throws IOException;
133
134 /**
135 * Accepts a connection.
136 *
137 * @param s the accepted connection.
138 * @exception IOException if an I/O error occurs when accepting the
139 * connection.
140 */
141 protected abstract void accept(SocketImpl s) throws IOException;
142
143 /**
144 * Returns an input stream for this socket.
145 *
146 * @return a stream for reading from this socket.
147 * @exception IOException if an I/O error occurs when creating the
148 * input stream.
149 */
150 protected abstract InputStream getInputStream() throws IOException;
151
152 /**
153 * Returns an output stream for this socket.
154 *
155 * @return an output stream for writing to this socket.
156 * @exception IOException if an I/O error occurs when creating the
157 * output stream.
158 */
159 protected abstract OutputStream getOutputStream() throws IOException;
160
161 /**
162 * Returns the number of bytes that can be read from this socket
163 * without blocking.
164 *
165 * @return the number of bytes that can be read from this socket
166 * without blocking.
167 * @exception IOException if an I/O error occurs when determining the
168 * number of bytes available.
169 */
170 protected abstract int available() throws IOException;
171
172 /**
173 * Closes this socket.
174 *
175 * @exception IOException if an I/O error occurs when closing this socket.
176 */
177 protected abstract void close() throws IOException;
178
179 /**
180 * Places the input stream for this socket at "end of stream".
181 * Any data sent to this socket is acknowledged and then
182 * silently discarded.
183 *
184 * If you read from a socket input stream after invoking
185 * shutdownInput() on the socket, the stream will return EOF.
186 *
187 * @exception IOException if an I/O error occurs when shutting down this
188 * socket.
189 * @see java.net.Socket#shutdownOutput()
190 * @see java.net.Socket#close()
191 * @see java.net.Socket#setSoLinger(boolean, int)
192 * @since 1.3
193 */
194 protected void shutdownInput() throws IOException {
195 throw new IOException("Method not implemented!");
196 }
197
198 /**
199 * Disables the output stream for this socket.
200 * For a TCP socket, any previously written data will be sent
201 * followed by TCP's normal connection termination sequence.
202 *
203 * If you write to a socket output stream after invoking
204 * shutdownOutput() on the socket, the stream will throw
205 * an IOException.
206 *
207 * @exception IOException if an I/O error occurs when shutting down this
208 * socket.
209 * @see java.net.Socket#shutdownInput()
210 * @see java.net.Socket#close()
211 * @see java.net.Socket#setSoLinger(boolean, int)
212 * @since 1.3
213 */
214 protected void shutdownOutput() throws IOException {
215 throw new IOException("Method not implemented!");
216 }
217
218 /**
219 * Returns the value of this socket's <code>fd</code> field.
220 *
221 * @return the value of this socket's <code>fd</code> field.
222 * @see java.net.SocketImpl#fd
223 */
224 protected FileDescriptor getFileDescriptor() {
225 return fd;
226 }
227
228 /**
229 * Returns the value of this socket's <code>address</code> field.
230 *
231 * @return the value of this socket's <code>address</code> field.
232 * @see java.net.SocketImpl#address
233 */
234 protected InetAddress getInetAddress() {
235 return address;
236 }
237
238 /**
239 * Returns the value of this socket's <code>port</code> field.
240 *
241 * @return the value of this socket's <code>port</code> field.
242 * @see java.net.SocketImpl#port
243 */
244 protected int getPort() {
245 return port;
246 }
247
248 /**
249 * Returns whether or not this SocketImpl supports sending
250 * urgent data. By default, false is returned
251 * unless the method is overridden in a sub-class
252 *
253 * @return true if urgent data supported
254 * @see java.net.SocketImpl#address
255 * @since 1.4
256 */
257 protected boolean supportsUrgentData () {
258 return false; // must be overridden in sub-class
259 }
260
261 /**
262 * Send one byte of urgent data on the socket.
263 * The byte to be sent is the low eight bits of the parameter
264 * @param data The byte of data to send
265 * @exception IOException if there is an error
266 * sending the data.
267 * @since 1.4
268 */
269 protected abstract void sendUrgentData (int data) throws IOException;
270
271 /**
272 * Returns the value of this socket's <code>localport</code> field.
273 *
274 * @return the value of this socket's <code>localport</code> field.
275 * @see java.net.SocketImpl#localport
276 */
277 protected int getLocalPort() {
278 return localport;
279 }
280
281 void setSocket(Socket soc) {
282 this.socket = soc;
283 }
284
285 Socket getSocket() {
286 return socket;
287 }
288
289 void setServerSocket(ServerSocket soc) {
290 this.serverSocket = soc;
291 }
292
293 ServerSocket getServerSocket() {
294 return serverSocket;
295 }
296
297 /**
298 * Returns the address and port of this socket as a <code>String</code>.
299 *
300 * @return a string representation of this socket.
301 */
302 public String toString() {
303 return "Socket[addr=" + getInetAddress() +
304 ",port=" + getPort() + ",localport=" + getLocalPort() + "]";
305 }
306
307 void reset() throws IOException {
308 address = null;
309 port = 0;
310 localport = 0;
311 }
312
313 /**
314 * Sets performance preferences for this socket.
315 *
316 * <p> Sockets use the TCP/IP protocol by default. Some implementations
317 * may offer alternative protocols which have different performance
318 * characteristics than TCP/IP. This method allows the application to
319 * express its own preferences as to how these tradeoffs should be made
320 * when the implementation chooses from the available protocols.
321 *
322 * <p> Performance preferences are described by three integers
323 * whose values indicate the relative importance of short connection time,
324 * low latency, and high bandwidth. The absolute values of the integers
325 * are irrelevant; in order to choose a protocol the values are simply
326 * compared, with larger values indicating stronger preferences. Negative
327 * values represent a lower priority than positive values. If the
328 * application prefers short connection time over both low latency and high
329 * bandwidth, for example, then it could invoke this method with the values
330 * <tt>(1, 0, 0)</tt>. If the application prefers high bandwidth above low
331 * latency, and low latency above short connection time, then it could
332 * invoke this method with the values <tt>(0, 1, 2)</tt>.
333 *
334 * By default, this method does nothing, unless it is overridden in a
335 * a sub-class.
336 *
337 * @param connectionTime
338 * An <tt>int</tt> expressing the relative importance of a short
339 * connection time
340 *
341 * @param latency
342 * An <tt>int</tt> expressing the relative importance of low
343 * latency
344 *
345 * @param bandwidth
346 * An <tt>int</tt> expressing the relative importance of high
347 * bandwidth
348 *
349 * @since 1.5
350 */
351 protected void setPerformancePreferences(int connectionTime,
352 int latency,
353 int bandwidth)
354 {
355 /* Not implemented yet */
356 }
357 }