< prev index next >

src/java.desktop/share/classes/javax/imageio/spi/ServiceRegistry.java

Print this page

        

@@ -44,11 +44,11 @@
  * implement the interface or subclass the class defined by the
  * service itself.
  *
  * <p> Service providers are stored in one or more <i>categories</i>,
  * each of which is defined by a class of interface (described by a
- * <code>Class</code> object) that all of its members must implement.
+ * {@code Class} object) that all of its members must implement.
  *
  * <p>The set of categories supported is limited
  * to the following standard Image I/O service types:
  *
  * <ul>

@@ -63,30 +63,30 @@
  * above types will result in {@code IllegalArgumentException}. For
  * a general mechanism to load service providers, see
  * {@link java.util.ServiceLoader ServiceLoader}.
  *
  * <p> Only a single instance of a given leaf class (that is, the
- * actual class returned by <code>getClass()</code>, as opposed to any
+ * actual class returned by {@code getClass()}, as opposed to any
  * inherited classes or interfaces) may be registered.  That is,
  * suppose that the
- * <code>com.mycompany.mypkg.GreenImageReaderProvider</code> class
- * is a subclass of <code>javax.imageio.spi.ImageReaderSpi</code>.
- * If a <code>GreenImageReaderProvider</code> instance is
+ * {@code com.mycompany.mypkg.GreenImageReaderProvider} class
+ * is a subclass of {@code javax.imageio.spi.ImageReaderSpi}.
+ * If a {@code GreenImageReaderProvider} instance is
  * registered, it will be stored in the category defined by the
- * <code>ImageReaderSpi</code> class.  If a new instance of
- * <code>GreenImageReaderProvider</code> is registered, it will replace
+ * {@code ImageReaderSpi} class.  If a new instance of
+ * {@code GreenImageReaderProvider} is registered, it will replace
  * the previous instance.  In practice, service provider objects are
  * usually singletons so this behavior is appropriate.
  *
- * <p> To declare a service provider, a <code>services</code>
- * subdirectory is placed within the <code>META-INF</code> directory
+ * <p> To declare a service provider, a {@code services}
+ * subdirectory is placed within the {@code META-INF} directory
  * that is present in every JAR file.  This directory contains a file
  * for each service provider interface that has one or more
  * implementation classes present in the JAR file.  For example, if
  * the JAR file contained a class named
- * <code>com.mycompany.mypkg.GreenImageReaderProvider</code> which implements the
- * <code>javax.imageio.spi.ImageReaderSpi</code> interface, the JAR file
+ * {@code com.mycompany.mypkg.GreenImageReaderProvider} which implements the
+ * {@code javax.imageio.spi.ImageReaderSpi} interface, the JAR file
  * would contain a file named: <pre>
  * META-INF/services/javax.imageio.spi.ImageReaderSpi</pre>
  *
  * containing the line:
  *

@@ -115,20 +115,20 @@
 
     // Class -> Registry
     private Map<Class<?>, SubRegistry> categoryMap = new HashMap<>();
 
     /**
-     * Constructs a <code>ServiceRegistry</code> instance with a
-     * set of categories taken from the <code>categories</code>
+     * Constructs a {@code ServiceRegistry} instance with a
+     * set of categories taken from the {@code categories}
      * argument. The categories must all be members of the set
      * of service types listed in the class specification.
      *
-     * @param categories an <code>Iterator</code> containing
-     * <code>Class</code> objects to be used to define categories.
+     * @param categories an {@code Iterator} containing
+     * {@code Class} objects to be used to define categories.
      *
      * @exception IllegalArgumentException if
-     * <code>categories</code> is <code>null</code>, or if
+     * {@code categories} is {@code null}, or if
      * one of the categories is not an allowed service type.
      */
     public ServiceRegistry(Iterator<Class<?>> categories) {
         if (categories == null) {
             throw new IllegalArgumentException("categories == null!");

@@ -149,39 +149,39 @@
      * in the class specification. If it is not, {@code IllegalArgumentException}
      * will be thrown.
      *
      * <p> This method transforms the name of the given service class
      * into a provider-configuration filename as described in the
-     * class comment and then uses the <code>getResources</code>
+     * class comment 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 look up and then
      * instantiate each element of the list.
      *
      * <p> Because it is possible for extensions to be installed into
      * a running Java virtual machine, this method may return
      * different results each time it is invoked.
      *
-     * @param providerClass a <code>Class</code>object indicating the
+     * @param providerClass a {@code Class} object indicating the
      * class or interface of the service providers being detected.
      *
      * @param loader the class loader to be used to load
      * provider-configuration files and instantiate provider classes,
-     * or <code>null</code> if the system class loader (or, failing that
+     * or {@code null} if the system class loader (or, failing that
      * the bootstrap class loader) is to be used.
      *
      * @param <T> the type of the providerClass.
      *
-     * @return An <code>Iterator</code> that yields provider objects
+     * @return An {@code Iterator} that yields provider objects
      * for the given service, in some arbitrary order.  The iterator
-     * will throw an <code>Error</code> if a provider-configuration
+     * will throw an {@code Error} if a provider-configuration
      * file violates the specified format or if a provider class
      * cannot be found and instantiated.
      *
      * @exception IllegalArgumentException if
-     * <code>providerClass</code> is <code>null</code>, or if it is
+     * {@code providerClass} is {@code null}, or if it is
      * not one of the allowed service types.
      */
     public static <T> Iterator<T> lookupProviders(Class<T> providerClass,
                                                   ClassLoader loader)
     {

@@ -204,23 +204,23 @@
      *
      * <p>The service class must be one of the service types listed
      * in the class specification. If it is not, {@code IllegalArgumentException}
      * will be thrown.
      *
-     * @param providerClass a <code>Class</code>object indicating the
+     * @param providerClass a {@code Class} object indicating the
      * class or interface of the service providers being detected.
      *
      * @param <T> the type of the providerClass.
      *
-     * @return An <code>Iterator</code> that yields provider objects
+     * @return An {@code Iterator} that yields provider objects
      * for the given service, in some arbitrary order.  The iterator
-     * will throw an <code>Error</code> if a provider-configuration
+     * will throw an {@code Error} if a provider-configuration
      * file violates the specified format or if a provider class
      * cannot be found and instantiated.
      *
      * @exception IllegalArgumentException if
-     * <code>providerClass</code> is <code>null</code>, or if it is
+     * {@code providerClass} is {@code null}, or if it is
      * not one of the allowed service types.
      */
     public static <T> Iterator<T> lookupProviders(Class<T> providerClass) {
         if (providerClass == null) {
             throw new IllegalArgumentException("providerClass == null!");

@@ -228,16 +228,16 @@
         checkClassAllowed(providerClass);
         return ServiceLoader.load(providerClass).iterator();
     }
 
     /**
-     * Returns an <code>Iterator</code> of <code>Class</code> objects
+     * Returns an {@code Iterator} of {@code Class} objects
      * indicating the current set of categories.  The iterator will be
      * empty if no categories exist.
      *
-     * @return an <code>Iterator</code> containing
-     * <code>Class</code>objects.
+     * @return an {@code Iterator} containing
+     * {@code Class} objects.
      */
     public Iterator<Class<?>> getCategories() {
         Set<Class<?>> keySet = categoryMap.keySet();
         return keySet.iterator();
     }

@@ -260,14 +260,14 @@
 
     /**
      * Adds a service provider object to the registry.  The provider
      * is associated with the given category.
      *
-     * <p> If <code>provider</code> implements the
-     * <code>RegisterableService</code> interface, its
-     * <code>onRegistration</code> method will be called.  Its
-     * <code>onDeregistration</code> method will be called each time
+     * <p> If {@code provider} implements the
+     * {@code RegisterableService} interface, its
+     * {@code onRegistration} method will be called.  Its
+     * {@code onDeregistration} method will be called each time
      * it is deregistered from a category, for example if a
      * category is removed or the registry is garbage collected.
      *
      * @param provider the service provide object to be registered.
      * @param category the category under which to register the

@@ -275,16 +275,16 @@
      * @param <T> the type of the provider.
      *
      * @return true if no provider of the same class was previously
      * registered in the same category category.
      *
-     * @exception IllegalArgumentException if <code>provider</code> is
-     * <code>null</code>.
+     * @exception IllegalArgumentException if {@code provider} is
+     * {@code null}.
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      * @exception ClassCastException if provider does not implement
-     * the <code>Class</code> defined by <code>category</code>.
+     * the {@code Class} defined by {@code category}.
      */
     public <T> boolean registerServiceProvider(T provider,
                                                Class<T> category) {
         if (provider == null) {
             throw new IllegalArgumentException("provider == null!");

@@ -301,24 +301,24 @@
     }
 
     /**
      * Adds a service provider object to the registry.  The provider
      * is associated within each category present in the registry
-     * whose <code>Class</code> it implements.
+     * whose {@code Class} it implements.
      *
-     * <p> If <code>provider</code> implements the
-     * <code>RegisterableService</code> interface, its
-     * <code>onRegistration</code> method will be called once for each
+     * <p> If {@code provider} implements the
+     * {@code RegisterableService} interface, its
+     * {@code onRegistration} method will be called once for each
      * category it is registered under.  Its
-     * <code>onDeregistration</code> method will be called each time
+     * {@code onDeregistration} method will be called each time
      * it is deregistered from a category or when the registry is
      * finalized.
      *
      * @param provider the service provider object to be registered.
      *
      * @exception IllegalArgumentException if
-     * <code>provider</code> is <code>null</code>.
+     * {@code provider} is {@code null}.
      */
     public void registerServiceProvider(Object provider) {
         if (provider == null) {
             throw new IllegalArgumentException("provider == null!");
         }

@@ -329,27 +329,27 @@
         }
     }
 
     /**
      * Adds a set of service provider objects, taken from an
-     * <code>Iterator</code> to the registry.  Each provider is
+     * {@code Iterator} to the registry.  Each provider is
      * associated within each category present in the registry whose
-     * <code>Class</code> it implements.
+     * {@code Class} it implements.
      *
-     * <p> For each entry of <code>providers</code> that implements
-     * the <code>RegisterableService</code> interface, its
-     * <code>onRegistration</code> method will be called once for each
+     * <p> For each entry of {@code providers} that implements
+     * the {@code RegisterableService} interface, its
+     * {@code onRegistration} method will be called once for each
      * category it is registered under.  Its
-     * <code>onDeregistration</code> method will be called each time
+     * {@code onDeregistration} method will be called each time
      * it is deregistered from a category or when the registry is
      * finalized.
      *
      * @param providers an Iterator containing service provider
      * objects to be registered.
      *
-     * @exception IllegalArgumentException if <code>providers</code>
-     * is <code>null</code> or contains a <code>null</code> entry.
+     * @exception IllegalArgumentException if {@code providers}
+     * is {@code null} or contains a {@code null} entry.
      */
     public void registerServiceProviders(Iterator<?> providers) {
         if (providers == null) {
             throw new IllegalArgumentException("provider == null!");
         }

@@ -359,35 +359,35 @@
     }
 
     /**
      * Removes a service provider object from the given category.  If
      * the provider was not previously registered, nothing happens and
-     * <code>false</code> is returned.  Otherwise, <code>true</code>
+     * {@code false} is returned.  Otherwise, {@code true}
      * is returned.  If an object of the same class as
-     * <code>provider</code> but not equal (using <code>==</code>) to
-     * <code>provider</code> is registered, it will not be
+     * {@code provider} but not equal (using {@code ==}) to
+     * {@code provider} is registered, it will not be
      * deregistered.
      *
-     * <p> If <code>provider</code> implements the
-     * <code>RegisterableService</code> interface, its
-     * <code>onDeregistration</code> method will be called.
+     * <p> If {@code provider} implements the
+     * {@code RegisterableService} interface, its
+     * {@code onDeregistration} method will be called.
      *
      * @param provider the service provider object to be deregistered.
      * @param category the category from which to deregister the
      * provider.
      * @param <T> the type of the provider.
      *
-     * @return <code>true</code> if the provider was previously
+     * @return {@code true} if the provider was previously
      * registered in the same category category,
-     * <code>false</code> otherwise.
+     * {@code false} otherwise.
      *
-     * @exception IllegalArgumentException if <code>provider</code> is
-     * <code>null</code>.
+     * @exception IllegalArgumentException if {@code provider} is
+     * {@code null}.
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      * @exception ClassCastException if provider does not implement
-     * the class defined by <code>category</code>.
+     * the class defined by {@code category}.
      */
     public <T> boolean deregisterServiceProvider(T provider,
                                                  Class<T> category) {
         if (provider == null) {
             throw new IllegalArgumentException("provider == null!");

@@ -406,12 +406,12 @@
      * Removes a service provider object from all categories that
      * contain it.
      *
      * @param provider the service provider object to be deregistered.
      *
-     * @exception IllegalArgumentException if <code>provider</code> is
-     * <code>null</code>.
+     * @exception IllegalArgumentException if {@code provider} is
+     * {@code null}.
      */
     public void deregisterServiceProvider(Object provider) {
         if (provider == null) {
             throw new IllegalArgumentException("provider == null!");
         }

@@ -421,20 +421,20 @@
             reg.deregisterServiceProvider(provider);
         }
     }
 
     /**
-     * Returns <code>true</code> if <code>provider</code> is currently
+     * Returns {@code true} if {@code provider} is currently
      * registered.
      *
      * @param provider the service provider object to be queried.
      *
-     * @return <code>true</code> if the given provider has been
+     * @return {@code true} if the given provider has been
      * registered.
      *
-     * @exception IllegalArgumentException if <code>provider</code> is
-     * <code>null</code>.
+     * @exception IllegalArgumentException if {@code provider} is
+     * {@code null}.
      */
     public boolean contains(Object provider) {
         if (provider == null) {
             throw new IllegalArgumentException("provider == null!");
         }

@@ -448,29 +448,29 @@
 
         return false;
     }
 
     /**
-     * Returns an <code>Iterator</code> containing all registered
+     * Returns an {@code Iterator} containing all registered
      * service providers in the given category.  If
-     * <code>useOrdering</code> is <code>false</code>, the iterator
+     * {@code useOrdering} is {@code false}, the iterator
      * will return all of the server provider objects in an arbitrary
      * order.  Otherwise, the ordering will respect any pairwise
      * orderings that have been set.  If the graph of pairwise
      * orderings contains cycles, any providers that belong to a cycle
      * will not be returned.
      *
      * @param category the category to be retrieved from.
-     * @param useOrdering <code>true</code> if pairwise orderings
+     * @param useOrdering {@code true} if pairwise orderings
      * should be taken account in ordering the returned objects.
      * @param <T> the type of the category.
      *
-     * @return an <code>Iterator</code> containing service provider
+     * @return an {@code Iterator} containing service provider
      * objects from the given category, possibly in order.
      *
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      */
     public <T> Iterator<T> getServiceProviders(Class<T> category,
                                                boolean useOrdering) {
         SubRegistry reg = categoryMap.get(category);
         if (reg == null) {

@@ -481,54 +481,54 @@
         return it;
     }
 
     /**
      * A simple filter interface used by
-     * <code>ServiceRegistry.getServiceProviders</code> to select
+     * {@code ServiceRegistry.getServiceProviders} to select
      * providers matching an arbitrary criterion.  Classes that
      * implement this interface should be defined in order to make use
-     * of the <code>getServiceProviders</code> method of
-     * <code>ServiceRegistry</code> that takes a <code>Filter</code>.
+     * of the {@code getServiceProviders} method of
+     * {@code ServiceRegistry} that takes a {@code Filter}.
      *
      * @see ServiceRegistry#getServiceProviders(Class, ServiceRegistry.Filter, boolean)
      */
     public interface Filter {
 
         /**
-         * Returns <code>true</code> if the given
-         * <code>provider</code> object matches the criterion defined
-         * by this <code>Filter</code>.
+         * Returns {@code true} if the given
+         * {@code provider} object matches the criterion defined
+         * by this {@code Filter}.
          *
-         * @param provider a service provider <code>Object</code>.
+         * @param provider a service provider {@code Object}.
          *
          * @return true if the provider matches the criterion.
          */
         boolean filter(Object provider);
     }
 
     /**
-     * Returns an <code>Iterator</code> containing service provider
+     * Returns an {@code Iterator} containing service provider
      * objects within a given category that satisfy a criterion
-     * imposed by the supplied <code>ServiceRegistry.Filter</code>
-     * object's <code>filter</code> method.
+     * imposed by the supplied {@code ServiceRegistry.Filter}
+     * object's {@code filter} method.
      *
-     * <p> The <code>useOrdering</code> argument controls the
+     * <p> The {@code useOrdering} argument controls the
      * ordering of the results using the same rules as
-     * <code>getServiceProviders(Class, boolean)</code>.
+     * {@code getServiceProviders(Class, boolean)}.
      *
      * @param category the category to be retrieved from.
-     * @param filter an instance of <code>ServiceRegistry.Filter</code>
-     * whose <code>filter</code> method will be invoked.
-     * @param useOrdering <code>true</code> if pairwise orderings
+     * @param filter an instance of {@code ServiceRegistry.Filter}
+     * whose {@code filter} method will be invoked.
+     * @param useOrdering {@code true} if pairwise orderings
      * should be taken account in ordering the returned objects.
      * @param <T> the type of the category.
      *
-     * @return an <code>Iterator</code> containing service provider
+     * @return an {@code Iterator} containing service provider
      * objects from the given category, possibly in order.
      *
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      */
     public <T> Iterator<T> getServiceProviders(Class<T> category,
                                                Filter filter,
                                                boolean useOrdering) {
         SubRegistry reg = categoryMap.get(category);

@@ -541,23 +541,23 @@
 
     /**
      * Returns the currently registered service provider object that
      * is of the given class type.  At most one object of a given
      * class is allowed to be registered at any given time.  If no
-     * registered object has the desired class type, <code>null</code>
+     * registered object has the desired class type, {@code null}
      * is returned.
      *
-     * @param providerClass the <code>Class</code> of the desired
+     * @param providerClass the {@code Class} of the desired
      * service provider object.
      * @param <T> the type of the provider.
      *
      * @return a currently registered service provider object with the
-     * desired <code>Class</code>type, or <code>null</code> is none is
+     * desired {@code Class} type, or {@code null} is none is
      * present.
      *
-     * @exception IllegalArgumentException if <code>providerClass</code> is
-     * <code>null</code>.
+     * @exception IllegalArgumentException if {@code providerClass} is
+     * {@code null}.
      */
     public <T> T getServiceProviderByClass(Class<T> providerClass) {
         if (providerClass == null) {
             throw new IllegalArgumentException("providerClass == null!");
         }

@@ -578,32 +578,32 @@
     /**
      * Sets a pairwise ordering between two service provider objects
      * within a given category.  If one or both objects are not
      * currently registered within the given category, or if the
      * desired ordering is already set, nothing happens and
-     * <code>false</code> is returned.  If the providers previously
+     * {@code false} is returned.  If the providers previously
      * were ordered in the reverse direction, that ordering is
      * removed.
      *
      * <p> The ordering will be used by the
-     * <code>getServiceProviders</code> methods when their
-     * <code>useOrdering</code> argument is <code>true</code>.
+     * {@code getServiceProviders} methods when their
+     * {@code useOrdering} argument is {@code true}.
      *
-     * @param category a <code>Class</code> object indicating the
+     * @param category a {@code Class} object indicating the
      * category under which the preference is to be established.
      * @param firstProvider the preferred provider.
      * @param secondProvider the provider to which
-     * <code>firstProvider</code> is preferred.
+     * {@code firstProvider} is preferred.
      * @param <T> the type of the category.
      *
-     * @return <code>true</code> if a previously unset ordering
+     * @return {@code true} if a previously unset ordering
      * was established.
      *
      * @exception IllegalArgumentException if either provider is
-     * <code>null</code> or they are the same object.
+     * {@code null} or they are the same object.
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      */
     public <T> boolean setOrdering(Class<T> category,
                                    T firstProvider,
                                    T secondProvider) {
         if (firstProvider == null || secondProvider == null) {

@@ -626,30 +626,30 @@
     /**
      * Sets a pairwise ordering between two service provider objects
      * within a given category.  If one or both objects are not
      * currently registered within the given category, or if no
      * ordering is currently set between them, nothing happens
-     * and <code>false</code> is returned.
+     * and {@code false} is returned.
      *
      * <p> The ordering will be used by the
-     * <code>getServiceProviders</code> methods when their
-     * <code>useOrdering</code> argument is <code>true</code>.
+     * {@code getServiceProviders} methods when their
+     * {@code useOrdering} argument is {@code true}.
      *
-     * @param category a <code>Class</code> object indicating the
+     * @param category a {@code Class} object indicating the
      * category under which the preference is to be disestablished.
      * @param firstProvider the formerly preferred provider.
      * @param secondProvider the provider to which
-     * <code>firstProvider</code> was formerly preferred.
+     * {@code firstProvider} was formerly preferred.
      * @param <T> the type of the category.
      *
-     * @return <code>true</code> if a previously set ordering was
+     * @return {@code true} if a previously set ordering was
      * disestablished.
      *
      * @exception IllegalArgumentException if either provider is
-     * <code>null</code> or they are the same object.
+     * {@code null} or they are the same object.
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      */
     public <T> boolean unsetOrdering(Class<T> category,
                                      T firstProvider,
                                      T secondProvider) {
         if (firstProvider == null || secondProvider == null) {

@@ -674,11 +674,11 @@
      * under the given category.
      *
      * @param category the category to be emptied.
      *
      * @exception IllegalArgumentException if there is no category
-     * corresponding to <code>category</code>.
+     * corresponding to {@code category}.
      */
     public void deregisterAll(Class<?> category) {
         SubRegistry reg = categoryMap.get(category);
         if (reg == null) {
             throw new IllegalArgumentException("category unknown!");

@@ -698,11 +698,11 @@
         }
     }
 
     /**
      * Finalizes this object prior to garbage collection.  The
-     * <code>deregisterAll</code> method is called to deregister all
+     * {@code deregisterAll} method is called to deregister all
      * currently registered service providers.  This method should not
      * be called from application code.
      *
      * @exception Throwable if an error occurs during superclass
      * finalization.

@@ -844,11 +844,11 @@
     }
 }
 
 
 /**
- * A class for wrapping <code>Iterators</code> with a filter function.
+ * A class for wrapping {@code Iterators} with a filter function.
  * This provides an iterator for a subset without duplication.
  */
 class FilterIterator<T> implements Iterator<T> {
 
     private Iterator<? extends T> iter;
< prev index next >