imageio/spi/ServiceRegistry.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
/**
 * @author Rustem V. Rafikov
 * @version $Revision: 1.3 $
 */

package javax.imageio.spi;

import java.util.*;
import java.util.Map.Entry;

/**
 * The ServiceRegistry class provides ability to register, deregister, look up
 * and obtain service provider instances (SPIs). A service means a set of
 * interfaces and classes, and a service provider is an implementation of a
 * service. Service providers can be associated with one or more categories.
 * Each category is defined by a class or interface. Only a single instance of a
 * each class is allowed to be registered as a category.
 *
 * @since Android 1.0
 */
public class ServiceRegistry {

    /**
     * The categories.
     */
    CategoriesMap categories = new CategoriesMap(this);

    /**
     * Instantiates a new ServiceRegistry with the specified categories.
     *
     * @param categoriesIterator
     *            an Iterator of Class objects for defining of categories.
     */
    public ServiceRegistry(Iterator<Class<?>> categoriesIterator) {
        if (null == categoriesIterator) {
            throw new IllegalArgumentException("categories iterator should not be NULL");
        }
        while (categoriesIterator.hasNext()) {
            Class<?> c = categoriesIterator.next();
            categories.addCategory(c);
        }
    }

    /**
     * Looks up and instantiates the available providers of this service using
     * the specified class loader.
     *
     * @param providerClass
     *            the Class object of the provider to be looked up.
     * @param loader
     *            the class loader to be used.
     * @return the iterator of providers objects for this service.
     */
    public static <T> Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader loader) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Looks up and instantiates the available providers of this service using
     * the context class loader.
     *
     * @param providerClass
     *            the Class object of the provider to be looked up.
     * @return the iterator of providers objects for this service.
     */
    public static <T> Iterator<T> lookupProviders(Class<T> providerClass) {
        return lookupProviders(providerClass, Thread.currentThread().getContextClassLoader());
    }

    /**
     * Registers the specified service provider object in the specified
     * categories.
     *
     * @param provider
     *            the specified provider to be registered.
     * @param category
     *            the category.
     * @return true, if no provider of the same class is registered in this
     *         category, false otherwise.
     */
    public <T> boolean registerServiceProvider(T provider, Class<T> category) {
        return categories.addProvider(provider, category);
    }

    /**
     * Registers a list of service providers.
     *
     * @param providers
     *            the list of service providers.
     */
    public void registerServiceProviders(Iterator<?> providers) {
        for (Iterator<?> iterator = providers; iterator.hasNext();) {
            categories.addProvider(iterator.next(), null);
        }
    }

    /**
     * Registers the specified service provider object in all categories.
     *
     * @param provider
     *            the service provider.
     */
    public void registerServiceProvider(Object provider) {
        categories.addProvider(provider, null);
    }

    /**
     * Deregisters the specifies service provider from the specified category.
     *
     * @param provider
     *            the service provider to be deregistered.
     * @param category
     *            the specified category.
     * @return true, if the provider was already registered in the specified
     *         category, false otherwise.
     */
    public <T> boolean deregisterServiceProvider(T provider, Class<T> category) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Deregisters the specified service provider from all categories.
     *
     * @param provider
     *            the specified service provider.
     */
    public void deregisterServiceProvider(Object provider) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Gets an Iterator of registered service providers in the specified
     * category which satisfy the specified Filter. The useOrdering parameter
     * indicates whether the iterator will return all of the server provider
     * objects in a set order.
     *
     * @param category
     *            the specified category.
     * @param filter
     *            the specified filter.
     * @param useOrdering
     *            the flag indicating that providers are ordered in the returned
     *            Iterator.
     * @return the iterator of registered service providers.
     */
    @SuppressWarnings("unchecked")
    public <T> Iterator<T> getServiceProviders(Class<T> category, Filter filter, boolean useOrdering) {
        return new FilteredIterator<T>(filter, (Iterator<T>)categories.getProviders(category,
                useOrdering));
    }

    /**
     * Gets an Iterator of all registered service providers in the specified
     * category. The useOrdering parameter indicates whether the iterator will
     * return all of the server provider objects in a set order.
     *
     * @param category
     *            the specified category.
     * @param useOrdering
     *            the flag indicating that providers are ordered in the returned
     *            Iterator.
     * @return the Iterator of service providers.
     */
    @SuppressWarnings("unchecked")
    public <T> Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering) {
        return (Iterator<T>)categories.getProviders(category, useOrdering);
    }

    /**
     * Gets the registered service provider object that has the specified class
     * type.
     *
     * @param providerClass
     *            the specified provider class.
     * @return the service provider object.
     */
    public <T> T getServiceProviderByClass(Class<T> providerClass) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Sets an ordering between two service provider objects within the
     * specified category.
     *
     * @param category
     *            the specified category.
     * @param firstProvider
     *            the first provider.
     * @param secondProvider
     *            the second provider.
     * @return true, if a previously unset order was set.
     */
    public <T> boolean setOrdering(Class<T> category, T firstProvider, T secondProvider) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Unsets an ordering between two service provider objects within the
     * specified category.
     *
     * @param category
     *            the specified category.
     * @param firstProvider
     *            the first provider.
     * @param secondProvider
     *            the second provider.
     * @return true, if a previously unset order was removed.
     */
    public <T> boolean unsetOrdering(Class<T> category, T firstProvider, T secondProvider) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Deregisters all providers from the specified category.
     *
     * @param category
     *            the specified category.
     */
    public void deregisterAll(Class<?> category) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Deregister all providers from all categories.
     */
    public void deregisterAll() {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Finalizes this object.
     *
     * @throws Throwable
     *             if an error occurs during finalization.
     */
    @Override
    public void finalize() throws Throwable {
        // TODO uncomment when deregisterAll is implemented
        // deregisterAll();
    }

    /**
     * Checks whether the specified provider has been already registered.
     *
     * @param provider
     *            the provider to be checked.
     * @return true, if the specified provider has been already registered,
     *         false otherwise.
     */
    public boolean contains(Object provider) {
        throw new UnsupportedOperationException("Not supported yet");
    }

    /**
     * Gets an iterator of Class objects representing the current categories.
     *
     * @return the Iterator of Class objects.
     */
    public Iterator<Class<?>> getCategories() {
        return categories.list();
    }

    /**
     * The ServiceRegistry.Filter interface is used by
     * ServiceRegistry.getServiceProviders to filter providers according to the
     * specified criterion.
     *
     * @since Android 1.0
     */
    public static interface Filter {

        /**
         * Returns true if the specified provider satisfies the criterion of
         * this Filter.
         *
         * @param provider
         *            the provider.
         * @return true, if the specified provider satisfies the criterion of
         *         this Filter, false otherwise.
         */
        boolean filter(Object provider);
    }

    /**
     * The Class CategoriesMap.
     */
    private static class CategoriesMap {

        /**
         * The categories.
         */
        Map<Class<?>, ProvidersMap> categories = new HashMap<Class<?>, ProvidersMap>();

        /**
         * The registry.
         */
        ServiceRegistry registry;

        /**
         * Instantiates a new categories map.
         *
         * @param registry
         *            the registry.
         */
        public CategoriesMap(ServiceRegistry registry) {
            this.registry = registry;
        }

        // -- TODO: useOrdering
        /**
         * Gets the providers.
         *
         * @param category
         *            the category.
         * @param useOrdering
         *            the use ordering.
         * @return the providers.
         */
        Iterator<?> getProviders(Class<?> category, boolean useOrdering) {
            ProvidersMap providers = categories.get(category);
            if (null == providers) {
                throw new IllegalArgumentException("Unknown category: " + category);
            }
            return providers.getProviders(useOrdering);
        }

        /**
         * List.
         *
         * @return the iterator< class<?>>.
         */
        Iterator<Class<?>> list() {
            return categories.keySet().iterator();
        }

        /**
         * Adds the category.
         *
         * @param category
         *            the category.
         */
        void addCategory(Class<?> category) {
            categories.put(category, new ProvidersMap());
        }

        /**
         * Adds a provider to the category. If <code>category</code> is
         * <code>null</code> then the provider will be added to all categories
         * which the provider is assignable from.
         *
         * @param provider
         *            provider to add.
         * @param category
         *            category to add provider to.
         * @return true, if there were such provider in some category.
         */
        boolean addProvider(Object provider, Class<?> category) {
            if (provider == null) {
                throw new IllegalArgumentException("provider should be != NULL");
            }

            boolean rt;
            if (category == null) {
                rt = findAndAdd(provider);
            } else {
                rt = addToNamed(provider, category);
            }

            if (provider instanceof RegisterableService) {
                ((RegisterableService)provider).onRegistration(registry, category);
            }

            return rt;
        }

        /**
         * Adds the to named.
         *
         * @param provider
         *            the provider.
         * @param category
         *            the category.
         * @return true, if successful.
         */
        private boolean addToNamed(Object provider, Class<?> category) {
            Object obj = categories.get(category);

            if (null == obj) {
                throw new IllegalArgumentException("Unknown category: " + category);
            }

            return ((ProvidersMap)obj).addProvider(provider);
        }

        /**
         * Find and add.
         *
         * @param provider
         *            the provider.
         * @return true, if successful.
         */
        private boolean findAndAdd(Object provider) {
            boolean rt = false;
            for (Entry<Class<?>, ProvidersMap> e : categories.entrySet()) {
                if (e.getKey().isAssignableFrom(provider.getClass())) {
                    rt |= e.getValue().addProvider(provider);
                }
            }
            return rt;
        }
    }

    /**
     * The Class ProvidersMap.
     */
    private static class ProvidersMap {
        // -- TODO: providers ordering support

        /**
         * The providers.
         */
        Map<Class<?>, Object> providers = new HashMap<Class<?>, Object>();

        /**
         * Adds the provider.
         *
         * @param provider
         *            the provider.
         * @return true, if successful.
         */
        boolean addProvider(Object provider) {
            return providers.put(provider.getClass(), provider) != null;
        }

        /**
         * Gets the provider classes.
         *
         * @return the provider classes.
         */
        Iterator<Class<?>> getProviderClasses() {
            return providers.keySet().iterator();
        }

        // -- TODO ordering
        /**
         * Gets the providers.
         *
         * @param userOrdering
         *            the user ordering.
         * @return the providers.
         */
        Iterator<?> getProviders(boolean userOrdering) {
            return providers.values().iterator();
        }
    }

    /**
     * The Class FilteredIterator.
     */
    private static class FilteredIterator<E> implements Iterator<E> {

        /**
         * The filter.
         */
        private Filter filter;

        /**
         * The backend.
         */
        private Iterator<E> backend;

        /**
         * The next obj.
         */
        private E nextObj;

        /**
         * Instantiates a new filtered iterator.
         *
         * @param filter
         *            the filter.
         * @param backend
         *            the backend.
         */
        public FilteredIterator(Filter filter, Iterator<E> backend) {
            this.filter = filter;
            this.backend = backend;
            findNext();
        }

        /**
         * Next.
         *
         * @return the e.
         */
        public E next() {
            if (nextObj == null) {
                throw new NoSuchElementException();
            }
            E tmp = nextObj;
            findNext();
            return tmp;
        }

        /**
         * Checks for next.
         *
         * @return true, if successful.
         */
        public boolean hasNext() {
            return nextObj != null;
        }

        /**
         * Removes the.
         */
        public void remove() {
            throw new UnsupportedOperationException();
        }

        /**
         * Sets nextObj to a next provider matching the criterion given by the
         * filter.
         */
        private void findNext() {
            nextObj = null;
            while (backend.hasNext()) {
                E o = backend.next();
                if (filter.filter(o)) {
                    nextObj = o;
                    return;
                }
            }
        }
    }
}