< prev index next >
src/java.xml.ws/share/classes/com/sun/xml/internal/ws/util/ServiceFinder.java
Print this page
*** 74,89 ****
* interface could possibly unify them, so no such class has been defined. The
* only requirement enforced here is that provider classes must have a
* zero-argument constructor so that they may be instantiated during lookup.
* <p/>
* <p> A service provider identifies itself by placing a provider-configuration
! * file in the resource directory <tt>META-INF/services</tt>. The file's name
* should consist of the fully-qualified name of the abstract service class.
* The file should contain a list of fully-qualified concrete provider-class
* names, one per line. Space and tab characters surrounding each name, as
! * well as blank lines, are ignored. The comment character is <tt>'#'</tt>
! * (<tt>0x23</tt>); on each line all characters following the first comment
* character are ignored. The file must be encoded in UTF-8.
* <p/>
* <p> If a particular concrete provider class is named in more than one
* configuration file, or is named in the same configuration file more than
* once, then the duplicates will be ignored. The configuration file naming a
--- 74,89 ----
* interface could possibly unify them, so no such class has been defined. The
* only requirement enforced here is that provider classes must have a
* zero-argument constructor so that they may be instantiated during lookup.
* <p/>
* <p> A service provider identifies itself by placing a provider-configuration
! * file in the resource directory {@code META-INF/services}. The file's name
* should consist of the fully-qualified name of the abstract service class.
* The file should contain a list of fully-qualified concrete provider-class
* names, one per line. Space and tab characters surrounding each name, as
! * well as blank lines, are ignored. The comment character is {@code '#'}
! * ({@code 0x23}); on each line all characters following the first comment
* character are ignored. The file must be encoded in UTF-8.
* <p/>
* <p> If a particular concrete provider class is named in more than one
* configuration file, or is named in the same configuration file more than
* once, then the duplicates will be ignored. The configuration file naming a
*** 91,114 ****
* unit as the provider itself. The provider must be accessible from the same
* class loader that was initially queried to locate the configuration file;
* note that this is not necessarily the class loader that found the file.
* <p/>
* <p> <b>Example:</b> Suppose we have a service class named
! * <tt>java.io.spi.CharCodec</tt>. It has two abstract methods:
* <p/>
* <pre>
* public abstract CharEncoder getEncoder(String encodingName);
* public abstract CharDecoder getDecoder(String encodingName);
* </pre>
* <p/>
! * Each method returns an appropriate object or <tt>null</tt> if it cannot
! * translate the given encoding. Typical <tt>CharCodec</tt> providers will
* support more than one encoding.
* <p/>
! * <p> If <tt>sun.io.StandardCodec</tt> is a provider of the <tt>CharCodec</tt>
* service then its jar file would contain the file
! * <tt>META-INF/services/java.io.spi.CharCodec</tt>. This file would contain
* the single line:
* <p/>
* <pre>
* sun.io.StandardCodec # Standard codecs for the platform
* </pre>
--- 91,114 ----
* unit as the provider itself. The provider must be accessible from the same
* class loader that was initially queried to locate the configuration file;
* note that this is not necessarily the class loader that found the file.
* <p/>
* <p> <b>Example:</b> Suppose we have a service class named
! * {@code java.io.spi.CharCodec}. It has two abstract methods:
* <p/>
* <pre>
* public abstract CharEncoder getEncoder(String encodingName);
* public abstract CharDecoder getDecoder(String encodingName);
* </pre>
* <p/>
! * Each method returns an appropriate object or {@code null} if it cannot
! * translate the given encoding. Typical {@code CharCodec} providers will
* support more than one encoding.
* <p/>
! * <p> If {@code sun.io.StandardCodec} is a provider of the {@code CharCodec}
* service then its jar file would contain the file
! * {@code META-INF/services/java.io.spi.CharCodec}. This file would contain
* the single line:
* <p/>
* <pre>
* sun.io.StandardCodec # Standard codecs for the platform
* </pre>
*** 167,177 ****
* Locates and incrementally instantiates the available providers of a
* given service using the given class loader.
* <p/>
* <p> This method transforms the name of the given service class into a
* provider-configuration filename as described above and then uses the
! * <tt>getResources</tt> method of the given class loader to find all
* available files with that name. These files are then read and parsed to
* produce a list of provider-class names. The iterator that is returned
* uses the given class loader to lookup and then instantiate each element
* of the list.
* <p/>
--- 167,177 ----
* Locates and incrementally instantiates the available providers of a
* given service using the given class loader.
* <p/>
* <p> This method transforms the name of the given service class into a
* provider-configuration filename as described above and then uses the
! * {@code getResources} method of the given class loader to find all
* available files with that name. These files are then read and parsed to
* produce a list of provider-class names. The iterator that is returned
* uses the given class loader to lookup and then instantiate each element
* of the list.
* <p/>
*** 179,189 ****
* Java virtual machine, this method may return different results each time
* it is invoked. <p>
*
* @param service The service's abstract service class
* @param loader The class loader to be used to load provider-configuration files
! * and instantiate provider classes, or <tt>null</tt> if the system
* class loader (or, failing that the bootstrap class loader) is to
* be used
* @throws ServiceConfigurationError If a provider-configuration file violates the specified format
* or names a provider class that cannot be found and instantiated
* @see #find(Class)
--- 179,189 ----
* Java virtual machine, this method may return different results each time
* it is invoked. <p>
*
* @param service The service's abstract service class
* @param loader The class loader to be used to load provider-configuration files
! * and instantiate provider classes, or {@code null} if the system
* class loader (or, failing that the bootstrap class loader) is to
* be used
* @throws ServiceConfigurationError If a provider-configuration file violates the specified format
* or names a provider class that cannot be found and instantiated
* @see #find(Class)
*** 225,237 ****
}
/**
* Returns discovered objects incrementally.
*
! * @return An <tt>Iterator</tt> that yields provider objects for the given
* service, in some arbitrary order. The iterator will throw a
! * <tt>ServiceConfigurationError</tt> if a provider-configuration
* file violates the specified format or if a provider class cannot
* be found and instantiated.
*/
@SuppressWarnings("unchecked")
public Iterator<T> iterator() {
--- 225,237 ----
}
/**
* Returns discovered objects incrementally.
*
! * @return An {@code Iterator} that yields provider objects for the given
* service, in some arbitrary order. The iterator will throw a
! * {@code ServiceConfigurationError} if a provider-configuration
* file violates the specified format or if a provider class cannot
* be found and instantiated.
*/
@SuppressWarnings("unchecked")
public Iterator<T> iterator() {
*** 317,328 ****
* @param service The service class for which providers are being sought;
* used to construct error detail strings
* @param u The URL naming the configuration file to be parsed
* @param returned A Set containing the names of provider classes that have already
* been returned. This set will be updated to contain the names
! * that will be yielded from the returned <tt>Iterator</tt>.
! * @return A (possibly empty) <tt>Iterator</tt> that will yield the
* provider-class names in the given configuration file that are
* not yet members of the returned set
* @throws ServiceConfigurationError If an I/O error occurs while reading from the given URL, or
* if a configuration-file format error is detected
*/
--- 317,328 ----
* @param service The service class for which providers are being sought;
* used to construct error detail strings
* @param u The URL naming the configuration file to be parsed
* @param returned A Set containing the names of provider classes that have already
* been returned. This set will be updated to contain the names
! * that will be yielded from the returned {@code Iterator}.
! * @return A (possibly empty) {@code Iterator} that will yield the
* provider-class names in the given configuration file that are
* not yet members of the returned set
* @throws ServiceConfigurationError If an I/O error occurs while reading from the given URL, or
* if a configuration-file format error is detected
*/
< prev index next >