64 * interface could possibly unify them, so no such class has been defined. The |
64 * interface could possibly unify them, so no such class has been defined. The |
65 * only requirement enforced here is that provider classes must have a |
65 * only requirement enforced here is that provider classes must have a |
66 * zero-argument constructor so that they may be instantiated during lookup. |
66 * zero-argument constructor so that they may be instantiated during lookup. |
67 * <p/> |
67 * <p/> |
68 * <p> A service provider identifies itself by placing a provider-configuration |
68 * <p> A service provider identifies itself by placing a provider-configuration |
69 * file in the resource directory <tt>META-INF/services</tt>. The file's name |
69 * file in the resource directory {@code META-INF/services}. The file's name |
70 * should consist of the fully-qualified name of the abstract service class. |
70 * should consist of the fully-qualified name of the abstract service class. |
71 * The file should contain a list of fully-qualified concrete provider-class |
71 * The file should contain a list of fully-qualified concrete provider-class |
72 * names, one per line. Space and tab characters surrounding each name, as |
72 * names, one per line. Space and tab characters surrounding each name, as |
73 * well as blank lines, are ignored. The comment character is <tt>'#'</tt> |
73 * well as blank lines, are ignored. The comment character is {@code '#'} |
74 * (<tt>0x23</tt>); on each line all characters following the first comment |
74 * ({@code 0x23}); on each line all characters following the first comment |
75 * character are ignored. The file must be encoded in UTF-8. |
75 * character are ignored. The file must be encoded in UTF-8. |
76 * <p/> |
76 * <p/> |
77 * <p> If a particular concrete provider class is named in more than one |
77 * <p> If a particular concrete provider class is named in more than one |
78 * configuration file, or is named in the same configuration file more than |
78 * configuration file, or is named in the same configuration file more than |
79 * once, then the duplicates will be ignored. The configuration file naming a |
79 * once, then the duplicates will be ignored. The configuration file naming a |
81 * unit as the provider itself. The provider must be accessible from the same |
81 * unit as the provider itself. The provider must be accessible from the same |
82 * class loader that was initially queried to locate the configuration file; |
82 * class loader that was initially queried to locate the configuration file; |
83 * note that this is not necessarily the class loader that found the file. |
83 * note that this is not necessarily the class loader that found the file. |
84 * <p/> |
84 * <p/> |
85 * <p> <b>Example:</b> Suppose we have a service class named |
85 * <p> <b>Example:</b> Suppose we have a service class named |
86 * <tt>java.io.spi.CharCodec</tt>. It has two abstract methods: |
86 * {@code java.io.spi.CharCodec}. It has two abstract methods: |
87 * <p/> |
87 * <p/> |
88 * <pre> |
88 * <pre> |
89 * public abstract CharEncoder getEncoder(String encodingName); |
89 * public abstract CharEncoder getEncoder(String encodingName); |
90 * public abstract CharDecoder getDecoder(String encodingName); |
90 * public abstract CharDecoder getDecoder(String encodingName); |
91 * </pre> |
91 * </pre> |
92 * <p/> |
92 * <p/> |
93 * Each method returns an appropriate object or <tt>null</tt> if it cannot |
93 * Each method returns an appropriate object or {@code null} if it cannot |
94 * translate the given encoding. Typical <tt>CharCodec</tt> providers will |
94 * translate the given encoding. Typical {@code CharCodec} providers will |
95 * support more than one encoding. |
95 * support more than one encoding. |
96 * <p/> |
96 * <p/> |
97 * <p> If <tt>sun.io.StandardCodec</tt> is a provider of the <tt>CharCodec</tt> |
97 * <p> If {@code sun.io.StandardCodec} is a provider of the {@code CharCodec} |
98 * service then its jar file would contain the file |
98 * service then its jar file would contain the file |
99 * <tt>META-INF/services/java.io.spi.CharCodec</tt>. This file would contain |
99 * {@code META-INF/services/java.io.spi.CharCodec}. This file would contain |
100 * the single line: |
100 * the single line: |
101 * <p/> |
101 * <p/> |
102 * <pre> |
102 * <pre> |
103 * sun.io.StandardCodec # Standard codecs for the platform |
103 * sun.io.StandardCodec # Standard codecs for the platform |
104 * </pre> |
104 * </pre> |
137 * Locates and incrementally instantiates the available providers of a |
137 * Locates and incrementally instantiates the available providers of a |
138 * given service using the given class loader. |
138 * given service using the given class loader. |
139 * <p/> |
139 * <p/> |
140 * <p> This method transforms the name of the given service class into a |
140 * <p> This method transforms the name of the given service class into a |
141 * provider-configuration filename as described above and then uses the |
141 * provider-configuration filename as described above and then uses the |
142 * <tt>getResources</tt> method of the given class loader to find all |
142 * {@code getResources} method of the given class loader to find all |
143 * available files with that name. These files are then read and parsed to |
143 * available files with that name. These files are then read and parsed to |
144 * produce a list of provider-class names. The iterator that is returned |
144 * produce a list of provider-class names. The iterator that is returned |
145 * uses the given class loader to lookup and then instantiate each element |
145 * uses the given class loader to lookup and then instantiate each element |
146 * of the list. |
146 * of the list. |
147 * <p/> |
147 * <p/> |
149 * Java virtual machine, this method may return different results each time |
149 * Java virtual machine, this method may return different results each time |
150 * it is invoked. <p> |
150 * it is invoked. <p> |
151 * |
151 * |
152 * @param service The service's abstract service class |
152 * @param service The service's abstract service class |
153 * @param loader The class loader to be used to load provider-configuration files |
153 * @param loader The class loader to be used to load provider-configuration files |
154 * and instantiate provider classes, or <tt>null</tt> if the system |
154 * and instantiate provider classes, or {@code null} if the system |
155 * class loader (or, failing that the bootstrap class loader) is to |
155 * class loader (or, failing that the bootstrap class loader) is to |
156 * be used |
156 * be used |
157 * @throws ServiceConfigurationError If a provider-configuration file violates the specified format |
157 * @throws ServiceConfigurationError If a provider-configuration file violates the specified format |
158 * or names a provider class that cannot be found and instantiated |
158 * or names a provider class that cannot be found and instantiated |
159 * @see #find(Class) |
159 * @see #find(Class) |
191 } |
191 } |
192 |
192 |
193 /** |
193 /** |
194 * Returns discovered objects incrementally. |
194 * Returns discovered objects incrementally. |
195 * |
195 * |
196 * @return An <tt>Iterator</tt> that yields provider objects for the given |
196 * @return An {@code Iterator} that yields provider objects for the given |
197 * service, in some arbitrary order. The iterator will throw a |
197 * service, in some arbitrary order. The iterator will throw a |
198 * <tt>ServiceConfigurationError</tt> if a provider-configuration |
198 * {@code ServiceConfigurationError} if a provider-configuration |
199 * file violates the specified format or if a provider class cannot |
199 * file violates the specified format or if a provider class cannot |
200 * be found and instantiated. |
200 * be found and instantiated. |
201 */ |
201 */ |
202 public Iterator<T> iterator() { |
202 public Iterator<T> iterator() { |
203 return new LazyIterator<T>(serviceClass,classLoader); |
203 return new LazyIterator<T>(serviceClass,classLoader); |
282 * @param service The service class for which providers are being sought; |
282 * @param service The service class for which providers are being sought; |
283 * used to construct error detail strings |
283 * used to construct error detail strings |
284 * @param u The URL naming the configuration file to be parsed |
284 * @param u The URL naming the configuration file to be parsed |
285 * @param returned A Set containing the names of provider classes that have already |
285 * @param returned A Set containing the names of provider classes that have already |
286 * been returned. This set will be updated to contain the names |
286 * been returned. This set will be updated to contain the names |
287 * that will be yielded from the returned <tt>Iterator</tt>. |
287 * that will be yielded from the returned {@code Iterator}. |
288 * @return A (possibly empty) <tt>Iterator</tt> that will yield the |
288 * @return A (possibly empty) {@code Iterator} that will yield the |
289 * provider-class names in the given configuration file that are |
289 * provider-class names in the given configuration file that are |
290 * not yet members of the returned set |
290 * not yet members of the returned set |
291 * @throws ServiceConfigurationError If an I/O error occurs while reading from the given URL, or |
291 * @throws ServiceConfigurationError If an I/O error occurs while reading from the given URL, or |
292 * if a configuration-file format error is detected |
292 * if a configuration-file format error is detected |
293 */ |
293 */ |