View Javadoc
1   /*
2    * Copyright (c) 1995, 2013, 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} 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}, 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} 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 this method on the
185      * socket, the stream's {@code available} method will return 0, and its
186      * {@code read} methods will return {@code -1} (end of stream).
187      *
188      * @exception IOException if an I/O error occurs when shutting down this
189      * socket.
190      * @see java.net.Socket#shutdownOutput()
191      * @see java.net.Socket#close()
192      * @see java.net.Socket#setSoLinger(boolean, int)
193      * @since 1.3
194      */
195     protected void shutdownInput() throws IOException {
196       throw new IOException("Method not implemented!");
197     }
198 
199     /**
200      * Disables the output stream for this socket.
201      * For a TCP socket, any previously written data will be sent
202      * followed by TCP's normal connection termination sequence.
203      *
204      * If you write to a socket output stream after invoking
205      * shutdownOutput() on the socket, the stream will throw
206      * an IOException.
207      *
208      * @exception IOException if an I/O error occurs when shutting down this
209      * socket.
210      * @see java.net.Socket#shutdownInput()
211      * @see java.net.Socket#close()
212      * @see java.net.Socket#setSoLinger(boolean, int)
213      * @since 1.3
214      */
215     protected void shutdownOutput() throws IOException {
216       throw new IOException("Method not implemented!");
217     }
218 
219     /**
220      * Returns the value of this socket's {@code fd} field.
221      *
222      * @return  the value of this socket's {@code fd} field.
223      * @see     java.net.SocketImpl#fd
224      */
225     protected FileDescriptor getFileDescriptor() {
226         return fd;
227     }
228 
229     /**
230      * Returns the value of this socket's {@code address} field.
231      *
232      * @return  the value of this socket's {@code address} field.
233      * @see     java.net.SocketImpl#address
234      */
235     protected InetAddress getInetAddress() {
236         return address;
237     }
238 
239     /**
240      * Returns the value of this socket's {@code port} field.
241      *
242      * @return  the value of this socket's {@code port} field.
243      * @see     java.net.SocketImpl#port
244      */
245     protected int getPort() {
246         return port;
247     }
248 
249     /**
250      * Returns whether or not this SocketImpl supports sending
251      * urgent data. By default, false is returned
252      * unless the method is overridden in a sub-class
253      *
254      * @return  true if urgent data supported
255      * @see     java.net.SocketImpl#address
256      * @since 1.4
257      */
258     protected boolean supportsUrgentData () {
259         return false; // must be overridden in sub-class
260     }
261 
262     /**
263      * Send one byte of urgent data on the socket.
264      * The byte to be sent is the low eight bits of the parameter
265      * @param data The byte of data to send
266      * @exception IOException if there is an error
267      *  sending the data.
268      * @since 1.4
269      */
270     protected abstract void sendUrgentData (int data) throws IOException;
271 
272     /**
273      * Returns the value of this socket's {@code localport} field.
274      *
275      * @return  the value of this socket's {@code localport} field.
276      * @see     java.net.SocketImpl#localport
277      */
278     protected int getLocalPort() {
279         return localport;
280     }
281 
282     void setSocket(Socket soc) {
283         this.socket = soc;
284     }
285 
286     Socket getSocket() {
287         return socket;
288     }
289 
290     void setServerSocket(ServerSocket soc) {
291         this.serverSocket = soc;
292     }
293 
294     ServerSocket getServerSocket() {
295         return serverSocket;
296     }
297 
298     /**
299      * Returns the address and port of this socket as a {@code String}.
300      *
301      * @return  a string representation of this socket.
302      */
303     public String toString() {
304         return "Socket[addr=" + getInetAddress() +
305             ",port=" + getPort() + ",localport=" + getLocalPort()  + "]";
306     }
307 
308     void reset() throws IOException {
309         address = null;
310         port = 0;
311         localport = 0;
312     }
313 
314     /**
315      * Sets performance preferences for this socket.
316      *
317      * <p> Sockets use the TCP/IP protocol by default.  Some implementations
318      * may offer alternative protocols which have different performance
319      * characteristics than TCP/IP.  This method allows the application to
320      * express its own preferences as to how these tradeoffs should be made
321      * when the implementation chooses from the available protocols.
322      *
323      * <p> Performance preferences are described by three integers
324      * whose values indicate the relative importance of short connection time,
325      * low latency, and high bandwidth.  The absolute values of the integers
326      * are irrelevant; in order to choose a protocol the values are simply
327      * compared, with larger values indicating stronger preferences. Negative
328      * values represent a lower priority than positive values. If the
329      * application prefers short connection time over both low latency and high
330      * bandwidth, for example, then it could invoke this method with the values
331      * {@code (1, 0, 0)}.  If the application prefers high bandwidth above low
332      * latency, and low latency above short connection time, then it could
333      * invoke this method with the values {@code (0, 1, 2)}.
334      *
335      * By default, this method does nothing, unless it is overridden in a
336      * a sub-class.
337      *
338      * @param  connectionTime
339      *         An {@code int} expressing the relative importance of a short
340      *         connection time
341      *
342      * @param  latency
343      *         An {@code int} expressing the relative importance of low
344      *         latency
345      *
346      * @param  bandwidth
347      *         An {@code int} expressing the relative importance of high
348      *         bandwidth
349      *
350      * @since 1.5
351      */
352     protected void setPerformancePreferences(int connectionTime,
353                                           int latency,
354                                           int bandwidth)
355     {
356         /* Not implemented yet */
357     }
358 }