001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.nio.channels.spi;
027
028 import java.io.FileDescriptor;
029 import java.io.IOException;
030 import java.net.ServerSocket;
031 import java.net.Socket;
032 import java.nio.channels.*;
033 import java.security.AccessController;
034 import java.security.PrivilegedAction;
035 import java.util.Iterator;
036 import java.util.ServiceLoader;
037 import java.util.ServiceConfigurationError;
038 import sun.security.action.GetPropertyAction;
039
040 /**
041 * Service-provider class for selectors and selectable channels.
042 *
043 * <p> A selector provider is a concrete subclass of this class that has a
044 * zero-argument constructor and implements the abstract methods specified
045 * below. A given invocation of the Java virtual machine maintains a single
046 * system-wide default provider instance, which is returned by the {@link
047 * #provider() provider} method. The first invocation of that method will locate
048 * the default provider as specified below.
049 *
050 * <p> The system-wide default provider is used by the static <tt>open</tt>
051 * methods of the {@link java.nio.channels.DatagramChannel#open
052 * DatagramChannel}, {@link java.nio.channels.Pipe#open Pipe}, {@link
053 * java.nio.channels.Selector#open Selector}, {@link
054 * java.nio.channels.ServerSocketChannel#open ServerSocketChannel}, and {@link
055 * java.nio.channels.SocketChannel#open SocketChannel} classes. It is also
056 * used by the {@link java.lang.System#inheritedChannel System.inheritedChannel()}
057 * method. A program may make use of a provider other than the default provider
058 * by instantiating that provider and then directly invoking the <tt>open</tt>
059 * methods defined in this class.
060 *
061 * <p> All of the methods in this class are safe for use by multiple concurrent
062 * threads. </p>
063 *
064 *
065 * @author Mark Reinhold
066 * @author JSR-51 Expert Group
067 * @version 1.35, 07/05/19
068 * @since 1.4
069 */
070
071 public abstract class SelectorProvider {
072
073 private static final Object lock = new Object();
074 private static SelectorProvider provider = null;
075
076 /**
077 * Initializes a new instance of this class. </p>
078 *
079 * @throws SecurityException
080 * If a security manager has been installed and it denies
081 * {@link RuntimePermission}<tt>("selectorProvider")</tt>
082 */
083 protected SelectorProvider() {
084 SecurityManager sm = System.getSecurityManager();
085 if (sm != null)
086 sm
087 .checkPermission(new RuntimePermission(
088 "selectorProvider"));
089 }
090
091 private static boolean loadProviderFromProperty() {
092 String cn = System
093 .getProperty("java.nio.channels.spi.SelectorProvider");
094 if (cn == null)
095 return false;
096 try {
097 Class c = Class.forName(cn, true, ClassLoader
098 .getSystemClassLoader());
099 provider = (SelectorProvider) c.newInstance();
100 return true;
101 } catch (ClassNotFoundException x) {
102 throw new ServiceConfigurationError(null, x);
103 } catch (IllegalAccessException x) {
104 throw new ServiceConfigurationError(null, x);
105 } catch (InstantiationException x) {
106 throw new ServiceConfigurationError(null, x);
107 } catch (SecurityException x) {
108 throw new ServiceConfigurationError(null, x);
109 }
110 }
111
112 private static boolean loadProviderAsService() {
113
114 ServiceLoader<SelectorProvider> sl = ServiceLoader.load(
115 SelectorProvider.class, ClassLoader
116 .getSystemClassLoader());
117 Iterator<SelectorProvider> i = sl.iterator();
118 for (;;) {
119 try {
120 if (!i.hasNext())
121 return false;
122 provider = i.next();
123 return true;
124 } catch (ServiceConfigurationError sce) {
125 if (sce.getCause() instanceof SecurityException) {
126 // Ignore the security exception, try the next provider
127 continue;
128 }
129 throw sce;
130 }
131 }
132 }
133
134 /**
135 * Returns the system-wide default selector provider for this invocation of
136 * the Java virtual machine.
137 *
138 * <p> The first invocation of this method locates the default provider
139 * object as follows: </p>
140 *
141 * <ol>
142 *
143 * <li><p> If the system property
144 * <tt>java.nio.channels.spi.SelectorProvider</tt> is defined then it is
145 * taken to be the fully-qualified name of a concrete provider class.
146 * The class is loaded and instantiated; if this process fails then an
147 * unspecified error is thrown. </p></li>
148 *
149 * <li><p> If a provider class has been installed in a jar file that is
150 * visible to the system class loader, and that jar file contains a
151 * provider-configuration file named
152 * <tt>java.nio.channels.spi.SelectorProvider</tt> in the resource
153 * directory <tt>META-INF/services</tt>, then the first class name
154 * specified in that file is taken. The class is loaded and
155 * instantiated; if this process fails then an unspecified error is
156 * thrown. </p></li>
157 *
158 * <li><p> Finally, if no provider has been specified by any of the above
159 * means then the system-default provider class is instantiated and the
160 * result is returned. </p></li>
161 *
162 * </ol>
163 *
164 * <p> Subsequent invocations of this method return the provider that was
165 * returned by the first invocation. </p>
166 *
167 * @return The system-wide default selector provider
168 */
169 public static SelectorProvider provider() {
170 synchronized (lock) {
171 if (provider != null)
172 return provider;
173 return (SelectorProvider) AccessController
174 .doPrivileged(new PrivilegedAction() {
175 public Object run() {
176 if (loadProviderFromProperty())
177 return provider;
178 if (loadProviderAsService())
179 return provider;
180 provider = sun.nio.ch.DefaultSelectorProvider
181 .create();
182 return provider;
183 }
184 });
185 }
186 }
187
188 /**
189 * Opens a datagram channel. </p>
190 *
191 * @return The new channel
192 */
193 public abstract DatagramChannel openDatagramChannel()
194 throws IOException;
195
196 /**
197 * Opens a pipe. </p>
198 *
199 * @return The new pipe
200 */
201 public abstract Pipe openPipe() throws IOException;
202
203 /**
204 * Opens a selector. </p>
205 *
206 * @return The new selector
207 */
208 public abstract AbstractSelector openSelector() throws IOException;
209
210 /**
211 * Opens a server-socket channel. </p>
212 *
213 * @return The new channel
214 */
215 public abstract ServerSocketChannel openServerSocketChannel()
216 throws IOException;
217
218 /**
219 * Opens a socket channel. </p>
220 *
221 * @return The new channel
222 */
223 public abstract SocketChannel openSocketChannel()
224 throws IOException;
225
226 /**
227 * Returns the channel inherited from the entity that created this
228 * Java virtual machine.
229 *
230 * <p> On many operating systems a process, such as a Java virtual
231 * machine, can be started in a manner that allows the process to
232 * inherit a channel from the entity that created the process. The
233 * manner in which this is done is system dependent, as are the
234 * possible entities to which the channel may be connected. For example,
235 * on UNIX systems, the Internet services daemon (<i>inetd</i>) is used to
236 * start programs to service requests when a request arrives on an
237 * associated network port. In this example, the process that is started,
238 * inherits a channel representing a network socket.
239 *
240 * <p> In cases where the inherited channel represents a network socket
241 * then the {@link java.nio.channels.Channel Channel} type returned
242 * by this method is determined as follows:
243 *
244 * <ul>
245 *
246 * <li><p> If the inherited channel represents a stream-oriented connected
247 * socket then a {@link java.nio.channels.SocketChannel SocketChannel} is
248 * returned. The socket channel is, at least initially, in blocking
249 * mode, bound to a socket address, and connected to a peer.
250 * </p></li>
251 *
252 * <li><p> If the inherited channel represents a stream-oriented listening
253 * socket then a {@link java.nio.channels.ServerSocketChannel
254 * ServerSocketChannel} is returned. The server-socket channel is, at
255 * least initially, in blocking mode, and bound to a socket address.
256 * </p></li>
257 *
258 * <li><p> If the inherited channel is a datagram-oriented socket
259 * then a {@link java.nio.channels.DatagramChannel DatagramChannel} is
260 * returned. The datagram channel is, at least initially, in blocking
261 * mode, and bound to a socket address.
262 * </p></li>
263 *
264 * </ul>
265 *
266 * <p> In addition to the network-oriented channels described, this method
267 * may return other kinds of channels in the future.
268 *
269 * <p> The first invocation of this method creates the channel that is
270 * returned. Subsequent invocations of this method return the same
271 * channel. </p>
272 *
273 * @return The inherited channel, if any, otherwise <tt>null</tt>.
274 *
275 * @throws IOException
276 * If an I/O error occurs
277 *
278 * @throws SecurityException
279 * If a security manager has been installed and it denies
280 * {@link RuntimePermission}<tt>("inheritedChannel")</tt>
281 *
282 * @since 1.5
283 */
284 public Channel inheritedChannel() throws IOException {
285 return null;
286 }
287
288 }
|