View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, 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      /**
75       * Initializes a new instance of this class.
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.
184      *
185      * @return  The new channel
186      *
187      * @throws  IOException
188      *          If an I/O error occurs
189      */
190     public abstract DatagramChannel openDatagramChannel()
191         throws IOException;
192 
193     /**
194      * Opens a datagram channel.
195      *
196      * @param   family
197      *          The protocol family
198      *
199      * @return  A new datagram channel
200      *
201      * @throws  UnsupportedOperationException
202      *          If the specified protocol family is not supported
203      * @throws  IOException
204      *          If an I/O error occurs
205      *
206      * @since 1.7
207      */
208     public abstract DatagramChannel openDatagramChannel(ProtocolFamily family)
209         throws IOException;
210 
211     /**
212      * Opens a pipe.
213      *
214      * @return  The new pipe
215      *
216      * @throws  IOException
217      *          If an I/O error occurs
218      */
219     public abstract Pipe openPipe()
220         throws IOException;
221 
222     /**
223      * Opens a selector.
224      *
225      * @return  The new selector
226      *
227      * @throws  IOException
228      *          If an I/O error occurs
229      */
230     public abstract AbstractSelector openSelector()
231         throws IOException;
232 
233     /**
234      * Opens a server-socket channel.
235      *
236      * @return  The new channel
237      *
238      * @throws  IOException
239      *          If an I/O error occurs
240      */
241     public abstract ServerSocketChannel openServerSocketChannel()
242         throws IOException;
243 
244     /**
245      * Opens a socket channel.
246      *
247      * @return  The new channel
248      *
249      * @throws  IOException
250      *          If an I/O error occurs
251      */
252     public abstract SocketChannel openSocketChannel()
253         throws IOException;
254 
255     /**
256      * Returns the channel inherited from the entity that created this
257      * Java virtual machine.
258      *
259      * <p> On many operating systems a process, such as a Java virtual
260      * machine, can be started in a manner that allows the process to
261      * inherit a channel from the entity that created the process. The
262      * manner in which this is done is system dependent, as are the
263      * possible entities to which the channel may be connected. For example,
264      * on UNIX systems, the Internet services daemon (<i>inetd</i>) is used to
265      * start programs to service requests when a request arrives on an
266      * associated network port. In this example, the process that is started,
267      * inherits a channel representing a network socket.
268      *
269      * <p> In cases where the inherited channel represents a network socket
270      * then the {@link java.nio.channels.Channel Channel} type returned
271      * by this method is determined as follows:
272      *
273      * <ul>
274      *
275      *  <li><p> If the inherited channel represents a stream-oriented connected
276      *  socket then a {@link java.nio.channels.SocketChannel SocketChannel} is
277      *  returned. The socket channel is, at least initially, in blocking
278      *  mode, bound to a socket address, and connected to a peer.
279      *  </p></li>
280      *
281      *  <li><p> If the inherited channel represents a stream-oriented listening
282      *  socket then a {@link java.nio.channels.ServerSocketChannel
283      *  ServerSocketChannel} is returned. The server-socket channel is, at
284      *  least initially, in blocking mode, and bound to a socket address.
285      *  </p></li>
286      *
287      *  <li><p> If the inherited channel is a datagram-oriented socket
288      *  then a {@link java.nio.channels.DatagramChannel DatagramChannel} is
289      *  returned. The datagram channel is, at least initially, in blocking
290      *  mode, and bound to a socket address.
291      *  </p></li>
292      *
293      * </ul>
294      *
295      * <p> In addition to the network-oriented channels described, this method
296      * may return other kinds of channels in the future.
297      *
298      * <p> The first invocation of this method creates the channel that is
299      * returned. Subsequent invocations of this method return the same
300      * channel. </p>
301      *
302      * @return  The inherited channel, if any, otherwise <tt>null</tt>.
303      *
304      * @throws  IOException
305      *          If an I/O error occurs
306      *
307      * @throws  SecurityException
308      *          If a security manager has been installed and it denies
309      *          {@link RuntimePermission}<tt>("inheritedChannel")</tt>
310      *
311      * @since 1.5
312      */
313    public Channel inheritedChannel() throws IOException {
314         return null;
315    }
316 
317 }