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
26package javax.net;
27
28import java.io.IOException;
29import java.net.InetAddress;
30import java.net.ServerSocket;
31import 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 */
51public 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     */
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     */
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     */
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     */
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
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
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//
202class DefaultServerSocketFactory extends ServerSocketFactory {
203
204    DefaultServerSocketFactory()
205    {
206        /* NOTHING */
207    }
208
209    public ServerSocket createServerSocket()
210    throws IOException
211    {
212        return new ServerSocket();
213    }
214
215    public ServerSocket createServerSocket(int port)
216    throws IOException
217    {
218        return new ServerSocket(port);
219    }
220
221    public ServerSocket createServerSocket(int port, int backlog)
222    throws IOException
223    {
224        return new ServerSocket(port, backlog);
225    }
226
227    public ServerSocket
228    createServerSocket(int port, int backlog, InetAddress ifAddress)
229    throws IOException
230    {
231        return new ServerSocket(port, backlog, ifAddress);
232    }
233}
234