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