/*

 * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.imageio.spi;

import java.io.File;

import java.util.ArrayList;

import java.util.HashMap;

import java.util.Iterator;

import java.util.List;

import java.util.Map;

import java.util.NoSuchElementException;

import java.util.Set;

import java.util.ServiceLoader;

/**

 * A registry for service provider instances.

 *

 * <p> A <i>service</i> is a well-known set of interfaces and (usually

 * abstract) classes.  A <i>service provider</i> is a specific

 * implementation of a service.  The classes in a provider typically

 * 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.

 * The set of categories may be changed dynamically.

 *

 * <p> Only a single instance of a given leaf class (that is, the

 * actual class returned by <code>getClass()</code>, as opposed to any

 * inherited classes or interfaces) may be registered.  That is,

 * suppose that the

 * <code>com.mycompany.mypkg.GreenServiceProvider</code> class

 * implements the <code>com.mycompany.mypkg.MyService</code>

 * interface.  If a <code>GreenServiceProvider</code> instance is

 * registered, it will be stored in the category defined by the

 * <code>MyService</code> class.  If a new instance of

 * <code>GreenServiceProvider</code> 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

 * 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.MyServiceImpl</code> which implements the

 * <code>javax.someapi.SomeService</code> interface, the JAR file

 * would contain a file named: <pre>

 * META-INF/services/javax.someapi.SomeService </pre>

 *

 * containing the line:

 *

 * <pre>

 * com.mycompany.mypkg.MyService

 * </pre>

 *

 * <p> The service provider classes should be to be lightweight and

 * quick to load.  Implementations of these interfaces should avoid

 * complex dependencies on other classes and on native code. The usual

 * pattern for more complex services is to register a lightweight

 * proxy for the heavyweight service.

 *

 * <p> An application may customize the contents of a registry as it

 * sees fit, so long as it has the appropriate runtime permission.

 *

 * <p> For more details on declaring service providers, and the JAR

 * format in general, see the <a

 * href="../../../../technotes/guides/jar/jar.html">

 * JAR File Specification</a>.

 *

 * @see RegisterableService

 *

 */

public class ServiceRegistry {

    // Class -> Registry

    private Map categoryMap = new HashMap();

    /**

     * Constructs a <code>ServiceRegistry</code> instance with a

     * set of categories taken from the <code>categories</code>

     * argument.

     *

     * @param categories an <code>Iterator</code> containing

     * <code>Class</code> objects to be used to define categories.

     *

     * @exception IllegalArgumentException if

     * <code>categories</code> is <code>null</code>.

     */

    public ServiceRegistry(Iterator<Class<?>> categories) {

        if (categories == null) {

            throw new IllegalArgumentException("categories == null!");

        }

        while (categories.hasNext()) {

            Class category = (Class)categories.next();

            SubRegistry reg = new SubRegistry(this, category);

            categoryMap.put(category, reg);

        }

    }

    /**

     * Searches for implementations of a particular service class

     * using the given class loader.

     *

     * <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>

     * 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

     * 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

     * the bootstrap class loader) is to be used.

     *

     * @param <T> the type of the providerClass.

     *

     * @return An <code>Iterator</code> that yields provider objects

     * for the given service, in some arbitrary order.  The iterator

     * will throw an <code>Error</code> 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>.

     */

    public static <T> Iterator<T> lookupProviders(Class<T> providerClass,

                                                  ClassLoader loader)

    {

        if (providerClass == null) {

            throw new IllegalArgumentException("providerClass == null!");

        }

        return ServiceLoader.load(providerClass, loader).iterator();

    }

    /**

     * Locates and incrementally instantiates the available providers

     * of a given service using the context class loader.  This

     * convenience method is equivalent to:

     *

     * <pre>

     *   ClassLoader cl = Thread.currentThread().getContextClassLoader();

     *   return Service.providers(service, cl);

     * </pre>

     *

     * @param providerClass a <code>Class</code>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

     * for the given service, in some arbitrary order.  The iterator

     * will throw an <code>Error</code> 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>.

     */

    public static <T> Iterator<T> lookupProviders(Class<T> providerClass) {

        if (providerClass == null) {

            throw new IllegalArgumentException("providerClass == null!");

        }

        return ServiceLoader.load(providerClass).iterator();

    }

    /**

     * Returns an <code>Iterator</code> of <code>Class</code> 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.

     */

    public Iterator<Class<?>> getCategories() {

        Set keySet = categoryMap.keySet();

        return keySet.iterator();

    }

    /**

     * Returns an Iterator containing the subregistries to which the

     * provider belongs.

     */

    private Iterator getSubRegistries(Object provider) {

        List l = new ArrayList();

        Iterator iter = categoryMap.keySet().iterator();

        while (iter.hasNext()) {

            Class c = (Class)iter.next();

            if (c.isAssignableFrom(provider.getClass())) {

                l.add((SubRegistry)categoryMap.get(c));

            }

        }

        return l.iterator();

    }

    /**

     * 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

     * 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

     * provider.

     * @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 there is no category

     * corresponding to <code>category</code>.

     * @exception ClassCastException if provider does not implement

     * the <code>Class</code> defined by <code>category</code>.

     */

    public <T> boolean registerServiceProvider(T provider,

                                               Class<T> category) {

        if (provider == null) {

            throw new IllegalArgumentException("provider == null!");

        }

        SubRegistry reg = (SubRegistry)categoryMap.get(category);

        if (reg == null) {

            throw new IllegalArgumentException("category unknown!");

        }

        if (!category.isAssignableFrom(provider.getClass())) {

            throw new ClassCastException();

        }

        return reg.registerServiceProvider(provider);

    }

    /**

     * 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.

     *

     * <p> If <code>provider</code> implements the

     * <code>RegisterableService</code> interface, its

     * <code>onRegistration</code> method will be called once for each

     * category it is registered under.  Its

     * <code>onDeregistration</code> 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>.

     */

    public void registerServiceProvider(Object provider) {

        if (provider == null) {

            throw new IllegalArgumentException("provider == null!");

        }

        Iterator regs = getSubRegistries(provider);

        while (regs.hasNext()) {

            SubRegistry reg = (SubRegistry)regs.next();

            reg.registerServiceProvider(provider);

        }

    }

    /**

     * Adds a set of service provider objects, taken from an

     * <code>Iterator</code> to the registry.  Each provider is

     * associated within each category present in the registry whose

     * <code>Class</code> 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

     * category it is registered under.  Its

     * <code>onDeregistration</code> 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.

     */

    public void registerServiceProviders(Iterator<?> providers) {

        if (providers == null) {

            throw new IllegalArgumentException("provider == null!");

        }

        while (providers.hasNext()) {

            registerServiceProvider(providers.next());

        }

    }

    /**

     * 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>

     * 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

     * deregistered.

     *

     * <p> If <code>provider</code> implements the

     * <code>RegisterableService</code> interface, its

     * <code>onDeregistration</code> 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

     * registered in the same category category,

     * <code>false</code> otherwise.

     *

     * @exception IllegalArgumentException if <code>provider</code> is

     * <code>null</code>.

     * @exception IllegalArgumentException if there is no category

     * corresponding to <code>category</code>.

     * @exception ClassCastException if provider does not implement

     * the class defined by <code>category</code>.

     */

    public <T> boolean deregisterServiceProvider(T provider,

                                                 Class<T> category) {

        if (provider == null) {

            throw new IllegalArgumentException("provider == null!");

        }

        SubRegistry reg = (SubRegistry)categoryMap.get(category);

        if (reg == null) {

            throw new IllegalArgumentException("category unknown!");

        }

        if (!category.isAssignableFrom(provider.getClass())) {

            throw new ClassCastException();

        }

        return reg.deregisterServiceProvider(provider);

    }

    /**

     * 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>.

     */

    public void deregisterServiceProvider(Object provider) {

        if (provider == null) {

            throw new IllegalArgumentException("provider == null!");

        }

        Iterator regs = getSubRegistries(provider);

        while (regs.hasNext()) {

            SubRegistry reg = (SubRegistry)regs.next();

            reg.deregisterServiceProvider(provider);

        }

    }

    /**

     * Returns <code>true</code> if <code>provider</code> is currently

     * registered.

     *

     * @param provider the service provider object to be queried.

     *

     * @return <code>true</code> if the given provider has been

     * registered.

     *

     * @exception IllegalArgumentException if <code>provider</code> is

     * <code>null</code>.

     */

    public boolean contains(Object provider) {

        if (provider == null) {

            throw new IllegalArgumentException("provider == null!");

        }

        Iterator regs = getSubRegistries(provider);

        while (regs.hasNext()) {

            SubRegistry reg = (SubRegistry)regs.next();

            if (reg.contains(provider)) {

                return true;

            }

        }

        return false;

    }

    /**

     * Returns an <code>Iterator</code> containing all registered

     * service providers in the given category.  If

     * <code>useOrdering</code> is <code>false</code>, 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

     * should be taken account in ordering the returned objects.

     * @param <T> the type of the category.

     *

     * @return an <code>Iterator</code> containing service provider

     * objects from the given category, possibly in order.

     *

     * @exception IllegalArgumentException if there is no category

     * corresponding to <code>category</code>.

     */

    public <T> Iterator<T> getServiceProviders(Class<T> category,

                                               boolean useOrdering) {

        SubRegistry reg = (SubRegistry)categoryMap.get(category);

        if (reg == null) {

            throw new IllegalArgumentException("category unknown!");

        }

        return reg.getServiceProviders(useOrdering);

    }

    /**

     * A simple filter interface used by

     * <code>ServiceRegistry.getServiceProviders</code> 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>.

     *

     * @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>.

         *

         * @param provider a service provider <code>Object</code>.

         *

         * @return true if the provider matches the criterion.

         */

        boolean filter(Object provider);

    }

    /**

     * Returns an <code>Iterator</code> 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.

     *

     * <p> The <code>useOrdering</code> argument controls the

     * ordering of the results using the same rules as

     * <code>getServiceProviders(Class, boolean)</code>.

     *

     * @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

     * should be taken account in ordering the returned objects.

     * @param <T> the type of the category.

     *

     * @return an <code>Iterator</code> containing service provider

     * objects from the given category, possibly in order.

     *

     * @exception IllegalArgumentException if there is no category

     * corresponding to <code>category</code>.

     */

    public <T> Iterator<T> getServiceProviders(Class<T> category,

                                               Filter filter,

                                               boolean useOrdering) {

        SubRegistry reg = (SubRegistry)categoryMap.get(category);

        if (reg == null) {

            throw new IllegalArgumentException("category unknown!");

        }

        Iterator iter = getServiceProviders(category, useOrdering);

        return new FilterIterator(iter, filter);

    }

    /**

     * 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>

     * is returned.

     *

     * @param providerClass the <code>Class</code> 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

     * present.

     *

     * @exception IllegalArgumentException if <code>providerClass</code> is

     * <code>null</code>.