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