1 /*
2 * Copyright 2000-2006 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 java.nio.channels.spi;
27
28 import java.io.FileDescriptor;
29 import java.io.IOException;
30 import java.net.ServerSocket;
31 import java.net.Socket;
32 import java.nio.channels;
33 import java.security.AccessController;
34 import java.security.PrivilegedAction;
35 import java.util.Iterator;
36 import java.util.ServiceLoader;
37 import java.util.ServiceConfigurationError;
38 import sun.security.action.GetPropertyAction;
39
40
41 /**
42 * Service-provider class for selectors and selectable channels.
43 *
44 * <p> A selector provider is a concrete subclass of this class that has a
45 * zero-argument constructor and implements the abstract methods specified
46 * below. A given invocation of the Java virtual machine maintains a single
47 * system-wide default provider instance, which is returned by the {@link
48 * #provider() provider} method. The first invocation of that method will locate
49 * the default provider as specified below.
50 *
51 * <p> The system-wide default provider is used by the static <tt>open</tt>
52 * methods of the {@link java.nio.channels.DatagramChannel#open
53 * DatagramChannel}, {@link java.nio.channels.Pipe#open Pipe}, {@link
54 * java.nio.channels.Selector#open Selector}, {@link
55 * java.nio.channels.ServerSocketChannel#open ServerSocketChannel}, and {@link
56 * java.nio.channels.SocketChannel#open SocketChannel} classes. It is also
57 * used by the {@link java.lang.System#inheritedChannel System.inheritedChannel()}
58 * method. A program may make use of a provider other than the default provider
59 * by instantiating that provider and then directly invoking the <tt>open</tt>
60 * methods defined in this class.
61 *
62 * <p> All of the methods in this class are safe for use by multiple concurrent
63 * threads. </p>
64 *
65 *
66 * @author Mark Reinhold
67 * @author JSR-51 Expert Group
68 * @since 1.4
69 */
70
71 public abstract class SelectorProvider {
72
73 private static final Object lock = new Object();
74 private static SelectorProvider provider = null;
75
76 /**
77 * Initializes a new instance of this class. </p>
78 *
79 * @throws SecurityException
80 * If a security manager has been installed and it denies
81 * {@link RuntimePermission}<tt>("selectorProvider")</tt>
82 */
83 protected SelectorProvider() {
84 SecurityManager sm = System.getSecurityManager();
85 if (sm != null)
86 sm.checkPermission(new RuntimePermission("selectorProvider"));
87 }
88
89 private static boolean loadProviderFromProperty() {
90 String cn = System.getProperty("java.nio.channels.spi.SelectorProvider");
91 if (cn == null)
92 return false;
93 try {
94 Class c = Class.forName(cn, true,
95 ClassLoader.getSystemClassLoader());
96 provider = (SelectorProvider)c.newInstance();
97 return true;
98 } catch (ClassNotFoundException x) {
99 throw new ServiceConfigurationError(null, x);
100 } catch (IllegalAccessException x) {
101 throw new ServiceConfigurationError(null, x);
102 } catch (InstantiationException x) {
103 throw new ServiceConfigurationError(null, x);
104 } catch (SecurityException x) {
105 throw new ServiceConfigurationError(null, x);
106 }
107 }
108
109 private static boolean loadProviderAsService() {
110
111 ServiceLoader<SelectorProvider> sl =
112 ServiceLoader.load(SelectorProvider.class,
113 ClassLoader.getSystemClassLoader());
114 Iterator<SelectorProvider> i = sl.iterator();
115 for (;;) {
116 try {
117 if (!i.hasNext())
118 return false;
119 provider = i.next();
120 return true;
121 } catch (ServiceConfigurationError sce) {
122 if (sce.getCause() instanceof SecurityException) {
123 // Ignore the security exception, try the next provider
124 continue;
125 }
126 throw sce;
127 }
128 }
129 }
130
131 /**
132 * Returns the system-wide default selector provider for this invocation of
133 * the Java virtual machine.
134 *
135 * <p> The first invocation of this method locates the default provider
136 * object as follows: </p>
137 *
138 * <ol>
139 *
140 * <li><p> If the system property
141 * <tt>java.nio.channels.spi.SelectorProvider</tt> is defined then it is
142 * taken to be the fully-qualified name of a concrete provider class.
143 * The class is loaded and instantiated; if this process fails then an
144 * unspecified error is thrown. </p></li>
145 *
146 * <li><p> If a provider class has been installed in a jar file that is
147 * visible to the system class loader, and that jar file contains a
148 * provider-configuration file named
149 * <tt>java.nio.channels.spi.SelectorProvider</tt> in the resource
150 * directory <tt>META-INF/services</tt>, then the first class name
151 * specified in that file is taken. The class is loaded and
152 * instantiated; if this process fails then an unspecified error is
153 * thrown. </p></li>
154 *
155 * <li><p> Finally, if no provider has been specified by any of the above
156 * means then the system-default provider class is instantiated and the
157 * result is returned. </p></li>
158 *
159 * </ol>
160 *
161 * <p> Subsequent invocations of this method return the provider that was
162 * returned by the first invocation. </p>
163 *
164 * @return The system-wide default selector provider
165 */
166 public static SelectorProvider provider() {
167 synchronized (lock) {
168 if (provider != null)
169 return provider;
170 return AccessController.doPrivileged(
171 new PrivilegedAction<SelectorProvider>() {
172 public SelectorProvider run() {
173 if (loadProviderFromProperty())
174 return provider;
175 if (loadProviderAsService())
176 return provider;
177 provider = sun.nio.ch.DefaultSelectorProvider.create();
178 return provider;
179 }
180 });
181 }
182 }
183
184 /**
185 * Opens a datagram channel. </p>
186 *
187 * @return The new channel
188 */
189 public abstract DatagramChannel openDatagramChannel()
190 throws IOException;
191
192 /**
193 * Opens a pipe. </p>
194 *
195 * @return The new pipe
196 */
197 public abstract Pipe openPipe()
198 throws IOException;
199
200 /**
201 * Opens a selector. </p>
202 *
203 * @return The new selector
204 */
205 public abstract AbstractSelector openSelector()
206 throws IOException;
207
208 /**
209 * Opens a server-socket channel. </p>
210 *
211 * @return The new channel
212 */
213 public abstract ServerSocketChannel openServerSocketChannel()
214 throws IOException;
215
216 /**
217 * Opens a socket channel. </p>
218 *
219 * @return The new channel
220 */
221 public abstract SocketChannel openSocketChannel()
222 throws IOException;
223
224 /**
225 * Returns the channel inherited from the entity that created this
226 * Java virtual machine.
227 *
228 * <p> On many operating systems a process, such as a Java virtual
229 * machine, can be started in a manner that allows the process to
230 * inherit a channel from the entity that created the process. The
231 * manner in which this is done is system dependent, as are the
232 * possible entities to which the channel may be connected. For example,
233 * on UNIX systems, the Internet services daemon (<i>inetd</i>) is used to
234 * start programs to service requests when a request arrives on an
235 * associated network port. In this example, the process that is started,
236 * inherits a channel representing a network socket.
237 *
238 * <p> In cases where the inherited channel represents a network socket
239 * then the {@link java.nio.channels.Channel Channel} type returned
240 * by this method is determined as follows:
241 *
242 * <ul>
243 *
244 * <li><p> If the inherited channel represents a stream-oriented connected
245 * socket then a {@link java.nio.channels.SocketChannel SocketChannel} is
246 * returned. The socket channel is, at least initially, in blocking
247 * mode, bound to a socket address, and connected to a peer.
248 * </p></li>
249 *
250 * <li><p> If the inherited channel represents a stream-oriented listening
251 * socket then a {@link java.nio.channels.ServerSocketChannel
252 * ServerSocketChannel} is returned. The server-socket channel is, at
253 * least initially, in blocking mode, and bound to a socket address.
254 * </p></li>
255 *
256 * <li><p> If the inherited channel is a datagram-oriented socket
257 * then a {@link java.nio.channels.DatagramChannel DatagramChannel} is
258 * returned. The datagram channel is, at least initially, in blocking
259 * mode, and bound to a socket address.
260 * </p></li>
261 *
262 * </ul>
263 *
264 * <p> In addition to the network-oriented channels described, this method
265 * may return other kinds of channels in the future.
266 *
267 * <p> The first invocation of this method creates the channel that is
268 * returned. Subsequent invocations of this method return the same
269 * channel. </p>
270 *
271 * @return The inherited channel, if any, otherwise <tt>null</tt>.
272 *
273 * @throws IOException
274 * If an I/O error occurs
275 *
276 * @throws SecurityException
277 * If a security manager has been installed and it denies
278 * {@link RuntimePermission}<tt>("inheritedChannel")</tt>
279 *
280 * @since 1.5
281 */
282 public Channel inheritedChannel() throws IOException {
283 return null;
284 }
285
286 }
Save This Page