SelectorProvider


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