1 /*
2  * Copyright (c) 1997, 2007, 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 javax.net;
27 
28 import java.io.IOException;
29 import java.net.InetAddress;
30 import java.net.ServerSocket;
31 import java.net.SocketException;
32 
33 /**
34  * This class creates server sockets.  It may be subclassed by other
35  * factories, which create particular types of server sockets.  This
36  * provides a general framework for the addition of public socket-level
37  * functionality.  It is the server side analogue of a socket factory,
38  * and similarly provides a way to capture a variety of policies related
39  * to the sockets being constructed.
40  *
41  * <P> Like socket factories, server Socket factory instances have
42  * methods used to create sockets. There is also an environment
43  * specific default server socket factory; frameworks will often use
44  * their own customized factory.
45  *
46  * @since 1.4
47  * @see SocketFactory
48  *
49  * @author David Brownell
50  */
51 public abstract class ServerSocketFactory
52 {
53     //
54     // NOTE:  JDK 1.1 bug in class GC, this can get collected
55     // even though it's always accessible via getDefault().
56     //
57     private static ServerSocketFactory          theFactory;
58 
59 
60     /**
61      * Creates a server socket factory.
62      */
ServerSocketFactory()63     protected ServerSocketFactory() { /* NOTHING */ }
64 
65     /**
66      * Returns a copy of the environment's default socket factory.
67      *
68      * @return the <code>ServerSocketFactory</code>
69      */
getDefault()70     public static ServerSocketFactory getDefault()
71     {
72         synchronized (ServerSocketFactory.class) {
73             if (theFactory == null) {
74                 //
75                 // Different implementations of this method could
76                 // work rather differently.  For example, driving
77                 // this from a system property, or using a different
78                 // implementation than JavaSoft's.
79                 //
80                 theFactory = new DefaultServerSocketFactory();
81             }
82         }
83 
84         return theFactory;
85     }
86 
87 
88     /**
89      * Returns an unbound server socket.  The socket is configured with
90      * the socket options (such as accept timeout) given to this factory.
91      *
92      * @return the unbound socket
93      * @throws IOException if the socket cannot be created
94      * @see java.net.ServerSocket#bind(java.net.SocketAddress)
95      * @see java.net.ServerSocket#bind(java.net.SocketAddress, int)
96      * @see java.net.ServerSocket#ServerSocket()
97      */
createServerSocket()98     public ServerSocket createServerSocket() throws IOException {
99         throw new SocketException("Unbound server sockets not implemented");
100     }
101 
102     /**
103      * Returns a server socket bound to the specified port.
104      * The socket is configured with the socket options
105      * (such as accept timeout) given to this factory.
106      * <P>
107      * If there is a security manager, its <code>checkListen</code>
108      * method is called with the <code>port</code> argument as its
109      * argument to ensure the operation is allowed. This could result
110      * in a SecurityException.
111      *
112      * @param port the port to listen to
113      * @return the <code>ServerSocket</code>
114      * @throws IOException for networking errors
115      * @throws SecurityException if a security manager exists and its
116      *         <code>checkListen</code> method doesn't allow the operation.
117      * @throws IllegalArgumentException if the port parameter is outside the
118      *         specified range of valid port values, which is between 0 and
119      *         65535, inclusive.
120      * @see    SecurityManager#checkListen
121      * @see java.net.ServerSocket#ServerSocket(int)
122      */
createServerSocket(int port)123     public abstract ServerSocket createServerSocket(int port)
124         throws IOException;
125 
126 
127     /**
128      * Returns a server socket bound to the specified port, and uses the
129      * specified connection backlog.  The socket is configured with
130      * the socket options (such as accept timeout) given to this factory.
131      * <P>
132      * The <code>backlog</code> argument must be a positive
133      * value greater than 0. If the value passed if equal or less
134      * than 0, then the default value will be assumed.
135      * <P>
136      * If there is a security manager, its <code>checkListen</code>
137      * method is called with the <code>port</code> argument as its
138      * argument to ensure the operation is allowed. This could result
139      * in a SecurityException.
140      *
141      * @param port the port to listen to
142      * @param backlog how many connections are queued
143      * @return the <code>ServerSocket</code>
144      * @throws IOException for networking errors
145      * @throws SecurityException if a security manager exists and its
146      *         <code>checkListen</code> method doesn't allow the operation.
147      * @throws IllegalArgumentException if the port parameter is outside the
148      *         specified range of valid port values, which is between 0 and
149      *         65535, inclusive.
150      * @see    SecurityManager#checkListen
151      * @see java.net.ServerSocket#ServerSocket(int, int)
152      */
153     public abstract ServerSocket
createServerSocket(int port, int backlog)154     createServerSocket(int port, int backlog)
155     throws IOException;
156 
157 
158     /**
159      * Returns a server socket bound to the specified port,
160      * with a specified listen backlog and local IP.
161      * <P>
162      * The <code>ifAddress</code> argument can be used on a multi-homed
163      * host for a <code>ServerSocket</code> that will only accept connect
164      * requests to one of its addresses. If <code>ifAddress</code> is null,
165      * it will accept connections on all local addresses. The socket is
166      * configured with the socket options (such as accept timeout) given
167      * to this factory.
168      * <P>
169      * The <code>backlog</code> argument must be a positive
170      * value greater than 0. If the value passed if equal or less
171      * than 0, then the default value will be assumed.
172      * <P>
173      * If there is a security manager, its <code>checkListen</code>
174      * method is called with the <code>port</code> argument as its
175      * argument to ensure the operation is allowed. This could result
176      * in a SecurityException.
177      *
178      * @param port the port to listen to
179      * @param backlog how many connections are queued
180      * @param ifAddress the network interface address to use
181      * @return the <code>ServerSocket</code>
182      * @throws IOException for networking errors
183      * @throws SecurityException if a security manager exists and its
184      *         <code>checkListen</code> method doesn't allow the operation.
185      * @throws IllegalArgumentException if the port parameter is outside the
186      *         specified range of valid port values, which is between 0 and
187      *         65535, inclusive.
188      * @see    SecurityManager#checkListen
189      * @see java.net.ServerSocket#ServerSocket(int, int, java.net.InetAddress)
190      */
191     public abstract ServerSocket
createServerSocket(int port, int backlog, InetAddress ifAddress)192     createServerSocket(int port, int backlog, InetAddress ifAddress)
193     throws IOException;
194 }
195 
196 
197 //
198 // The default factory has NO intelligence.  In fact it's not clear
199 // what sort of intelligence servers need; the onus is on clients,
200 // who have to know how to tunnel etc.
201 //
202 class DefaultServerSocketFactory extends ServerSocketFactory {
203 
DefaultServerSocketFactory()204     DefaultServerSocketFactory()
205     {
206         /* NOTHING */
207     }
208 
createServerSocket()209     public ServerSocket createServerSocket()
210     throws IOException
211     {
212         return new ServerSocket();
213     }
214 
createServerSocket(int port)215     public ServerSocket createServerSocket(int port)
216     throws IOException
217     {
218         return new ServerSocket(port);
219     }
220 
createServerSocket(int port, int backlog)221     public ServerSocket createServerSocket(int port, int backlog)
222     throws IOException
223     {
224         return new ServerSocket(port, backlog);
225     }
226 
227     public ServerSocket
createServerSocket(int port, int backlog, InetAddress ifAddress)228     createServerSocket(int port, int backlog, InetAddress ifAddress)
229     throws IOException
230     {
231         return new ServerSocket(port, backlog, ifAddress);
232     }
233 }
234