1 /*
2 * Copyright 1997-2007 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 */
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 //
202 class 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 }
Save This Page