74 * interface could possibly unify them, so no such class has been defined. The |
74 * interface could possibly unify them, so no such class has been defined. The |
75 * only requirement enforced here is that provider classes must have a |
75 * only requirement enforced here is that provider classes must have a |
76 * zero-argument constructor so that they may be instantiated during lookup. |
76 * zero-argument constructor so that they may be instantiated during lookup. |
77 * <p/> |
77 * <p/> |
78 * <p> A service provider identifies itself by placing a provider-configuration |
78 * <p> A service provider identifies itself by placing a provider-configuration |
79 * file in the resource directory <tt>META-INF/services</tt>. The file's name |
79 * file in the resource directory {@code META-INF/services}. The file's name |
80 * should consist of the fully-qualified name of the abstract service class. |
80 * should consist of the fully-qualified name of the abstract service class. |
81 * The file should contain a list of fully-qualified concrete provider-class |
81 * The file should contain a list of fully-qualified concrete provider-class |
82 * names, one per line. Space and tab characters surrounding each name, as |
82 * names, one per line. Space and tab characters surrounding each name, as |
83 * well as blank lines, are ignored. The comment character is <tt>'#'</tt> |
83 * well as blank lines, are ignored. The comment character is {@code '#'} |
84 * (<tt>0x23</tt>); on each line all characters following the first comment |
84 * ({@code 0x23}); on each line all characters following the first comment |
85 * character are ignored. The file must be encoded in UTF-8. |
85 * character are ignored. The file must be encoded in UTF-8. |
86 * <p/> |
86 * <p/> |
87 * <p> If a particular concrete provider class is named in more than one |
87 * <p> If a particular concrete provider class is named in more than one |
88 * configuration file, or is named in the same configuration file more than |
88 * configuration file, or is named in the same configuration file more than |
89 * once, then the duplicates will be ignored. The configuration file naming a |
89 * once, then the duplicates will be ignored. The configuration file naming a |
91 * unit as the provider itself. The provider must be accessible from the same |
91 * unit as the provider itself. The provider must be accessible from the same |
92 * class loader that was initially queried to locate the configuration file; |
92 * class loader that was initially queried to locate the configuration file; |
93 * note that this is not necessarily the class loader that found the file. |
93 * note that this is not necessarily the class loader that found the file. |
94 * <p/> |
94 * <p/> |
95 * <p> <b>Example:</b> Suppose we have a service class named |
95 * <p> <b>Example:</b> Suppose we have a service class named |
96 * <tt>java.io.spi.CharCodec</tt>. It has two abstract methods: |
96 * {@code java.io.spi.CharCodec}. It has two abstract methods: |
97 * <p/> |
97 * <p/> |
98 * <pre> |
98 * <pre> |
99 * public abstract CharEncoder getEncoder(String encodingName); |
99 * public abstract CharEncoder getEncoder(String encodingName); |
100 * public abstract CharDecoder getDecoder(String encodingName); |
100 * public abstract CharDecoder getDecoder(String encodingName); |
101 * </pre> |
101 * </pre> |
102 * <p/> |
102 * <p/> |
103 * Each method returns an appropriate object or <tt>null</tt> if it cannot |
103 * Each method returns an appropriate object or {@code null} if it cannot |
104 * translate the given encoding. Typical <tt>CharCodec</tt> providers will |
104 * translate the given encoding. Typical {@code CharCodec} providers will |
105 * support more than one encoding. |
105 * support more than one encoding. |
106 * <p/> |
106 * <p/> |
107 * <p> If <tt>sun.io.StandardCodec</tt> is a provider of the <tt>CharCodec</tt> |
107 * <p> If {@code sun.io.StandardCodec} is a provider of the {@code CharCodec} |
108 * service then its jar file would contain the file |
108 * service then its jar file would contain the file |
109 * <tt>META-INF/services/java.io.spi.CharCodec</tt>. This file would contain |
109 * {@code META-INF/services/java.io.spi.CharCodec}. This file would contain |
110 * the single line: |
110 * the single line: |
111 * <p/> |
111 * <p/> |
112 * <pre> |
112 * <pre> |
113 * sun.io.StandardCodec # Standard codecs for the platform |
113 * sun.io.StandardCodec # Standard codecs for the platform |
114 * </pre> |
114 * </pre> |
167 * Locates and incrementally instantiates the available providers of a |
167 * Locates and incrementally instantiates the available providers of a |
168 * given service using the given class loader. |
168 * given service using the given class loader. |
169 * <p/> |
169 * <p/> |
170 * <p> This method transforms the name of the given service class into a |
170 * <p> This method transforms the name of the given service class into a |
171 * provider-configuration filename as described above and then uses the |
171 * provider-configuration filename as described above and then uses the |
172 * <tt>getResources</tt> method of the given class loader to find all |
172 * {@code getResources} method of the given class loader to find all |
173 * available files with that name. These files are then read and parsed to |
173 * available files with that name. These files are then read and parsed to |
174 * produce a list of provider-class names. The iterator that is returned |
174 * produce a list of provider-class names. The iterator that is returned |
175 * uses the given class loader to lookup and then instantiate each element |
175 * uses the given class loader to lookup and then instantiate each element |
176 * of the list. |
176 * of the list. |
177 * <p/> |
177 * <p/> |
179 * Java virtual machine, this method may return different results each time |
179 * Java virtual machine, this method may return different results each time |
180 * it is invoked. <p> |
180 * it is invoked. <p> |
181 * |
181 * |
182 * @param service The service's abstract service class |
182 * @param service The service's abstract service class |
183 * @param loader The class loader to be used to load provider-configuration files |
183 * @param loader The class loader to be used to load provider-configuration files |
184 * and instantiate provider classes, or <tt>null</tt> if the system |
184 * and instantiate provider classes, or {@code null} if the system |
185 * class loader (or, failing that the bootstrap class loader) is to |
185 * class loader (or, failing that the bootstrap class loader) is to |
186 * be used |
186 * be used |
187 * @throws ServiceConfigurationError If a provider-configuration file violates the specified format |
187 * @throws ServiceConfigurationError If a provider-configuration file violates the specified format |
188 * or names a provider class that cannot be found and instantiated |
188 * or names a provider class that cannot be found and instantiated |
189 * @see #find(Class) |
189 * @see #find(Class) |
225 } |
225 } |
226 |
226 |
227 /** |
227 /** |
228 * Returns discovered objects incrementally. |
228 * Returns discovered objects incrementally. |
229 * |
229 * |
230 * @return An <tt>Iterator</tt> that yields provider objects for the given |
230 * @return An {@code Iterator} that yields provider objects for the given |
231 * service, in some arbitrary order. The iterator will throw a |
231 * service, in some arbitrary order. The iterator will throw a |
232 * <tt>ServiceConfigurationError</tt> if a provider-configuration |
232 * {@code ServiceConfigurationError} if a provider-configuration |
233 * file violates the specified format or if a provider class cannot |
233 * file violates the specified format or if a provider class cannot |
234 * be found and instantiated. |
234 * be found and instantiated. |
235 */ |
235 */ |
236 @SuppressWarnings("unchecked") |
236 @SuppressWarnings("unchecked") |
237 public Iterator<T> iterator() { |
237 public Iterator<T> iterator() { |
317 * @param service The service class for which providers are being sought; |
317 * @param service The service class for which providers are being sought; |
318 * used to construct error detail strings |
318 * used to construct error detail strings |
319 * @param u The URL naming the configuration file to be parsed |
319 * @param u The URL naming the configuration file to be parsed |
320 * @param returned A Set containing the names of provider classes that have already |
320 * @param returned A Set containing the names of provider classes that have already |
321 * been returned. This set will be updated to contain the names |
321 * been returned. This set will be updated to contain the names |
322 * that will be yielded from the returned <tt>Iterator</tt>. |
322 * that will be yielded from the returned {@code Iterator}. |
323 * @return A (possibly empty) <tt>Iterator</tt> that will yield the |
323 * @return A (possibly empty) {@code Iterator} that will yield the |
324 * provider-class names in the given configuration file that are |
324 * provider-class names in the given configuration file that are |
325 * not yet members of the returned set |
325 * not yet members of the returned set |
326 * @throws ServiceConfigurationError If an I/O error occurs while reading from the given URL, or |
326 * @throws ServiceConfigurationError If an I/O error occurs while reading from the given URL, or |
327 * if a configuration-file format error is detected |
327 * if a configuration-file format error is detected |
328 */ |
328 */ |