123 * <i>provides</i> allow consumers of a service to be <i>linked</i> to modules |
123 * <i>provides</i> allow consumers of a service to be <i>linked</i> to modules |
124 * containing providers of the service. |
124 * containing providers of the service. |
125 * |
125 * |
126 * <p> A service provider that is packaged as a JAR file for the class path is |
126 * <p> A service provider that is packaged as a JAR file for the class path is |
127 * identified by placing a <i>provider-configuration file</i> in the resource |
127 * identified by placing a <i>provider-configuration file</i> in the resource |
128 * directory <tt>META-INF/services</tt>. The file's name is the fully-qualified |
128 * directory {@code META-INF/services}. The file's name is the fully-qualified |
129 * <a href="../lang/ClassLoader.html#name">binary name</a> of the service's |
129 * <a href="../lang/ClassLoader.html#name">binary name</a> of the service's |
130 * type. The file contains a list of fully-qualified binary names of concrete |
130 * type. The file contains a list of fully-qualified binary names of concrete |
131 * provider classes, one per line. Space and tab characters surrounding each |
131 * provider classes, one per line. Space and tab characters surrounding each |
132 * name, as well as blank lines, are ignored. The comment character is |
132 * name, as well as blank lines, are ignored. The comment character is |
133 * <tt>'#'</tt> (<tt>'\u0023'</tt>, |
133 * {@code '#'} (<code>'\u0023'</code>, |
134 * <font style="font-size:smaller;">NUMBER SIGN</font>); on |
134 * <span style="font-size:smaller;">NUMBER SIGN</span>); on |
135 * each line all characters following the first comment character are ignored. |
135 * each line all characters following the first comment character are ignored. |
136 * The file must be encoded in UTF-8. |
136 * The file must be encoded in UTF-8. |
137 * If a particular concrete provider class is named in more than one |
137 * If a particular concrete provider class is named in more than one |
138 * configuration file, or is named in the same configuration file more than |
138 * configuration file, or is named in the same configuration file more than |
139 * once, then the duplicates are ignored. The configuration file naming a |
139 * once, then the duplicates are ignored. The configuration file naming a |
255 * |
255 * |
256 * <p> Unless otherwise specified, passing a {@code null} argument to any |
256 * <p> Unless otherwise specified, passing a {@code null} argument to any |
257 * method in this class will cause a {@link NullPointerException} to be thrown. |
257 * method in this class will cause a {@link NullPointerException} to be thrown. |
258 * |
258 * |
259 * <h2> Example </h2> |
259 * <h2> Example </h2> |
260 * <p> Suppose we have a service type <tt>com.example.CodecSet</tt> which is |
260 * <p> Suppose we have a service type {@code com.example.CodecSet} which is |
261 * intended to represent sets of encoder/decoder pairs for some protocol. In |
261 * intended to represent sets of encoder/decoder pairs for some protocol. In |
262 * this case it is an abstract class with two abstract methods: |
262 * this case it is an abstract class with two abstract methods: |
263 * |
263 * |
264 * <blockquote><pre> |
264 * <blockquote><pre> |
265 * public abstract Encoder getEncoder(String encodingName); |
265 * public abstract Encoder getEncoder(String encodingName); |
266 * public abstract Decoder getDecoder(String encodingName);</pre></blockquote> |
266 * public abstract Decoder getDecoder(String encodingName);</pre></blockquote> |
267 * |
267 * |
268 * Each method returns an appropriate object or <tt>null</tt> if the provider |
268 * Each method returns an appropriate object or {@code null} if the provider |
269 * does not support the given encoding. Typical providers support more than |
269 * does not support the given encoding. Typical providers support more than |
270 * one encoding. |
270 * one encoding. |
271 * |
271 * |
272 * <p> The <tt>CodecSet</tt> class creates and saves a single service instance |
272 * <p> The {@code CodecSet} class creates and saves a single service instance |
273 * at initialization: |
273 * at initialization: |
274 * |
274 * |
275 * <pre>{@code |
275 * <pre>{@code |
276 * private static ServiceLoader<CodecSet> codecSetLoader |
276 * private static ServiceLoader<CodecSet> codecSetLoader |
277 * = ServiceLoader.load(CodecSet.class); |
277 * = ServiceLoader.load(CodecSet.class); |
1400 * @param service |
1400 * @param service |
1401 * The interface or abstract class representing the service |
1401 * The interface or abstract class representing the service |
1402 * |
1402 * |
1403 * @param loader |
1403 * @param loader |
1404 * The class loader to be used to load provider-configuration files |
1404 * The class loader to be used to load provider-configuration files |
1405 * and provider classes, or <tt>null</tt> if the system class |
1405 * and provider classes, or {@code null} if the system class |
1406 * loader (or, failing that, the bootstrap class loader) is to be |
1406 * loader (or, failing that, the bootstrap class loader) is to be |
1407 * used |
1407 * used |
1408 * |
1408 * |
1409 * @param callerModule |
1409 * @param callerModule |
1410 * The caller's module for which a new service loader is created |
1410 * The caller's module for which a new service loader is created |