icu4jsrc

[Dictionary.git] / jars / icu4j-4_2_1-src / src / com / ibm / icu / impl / ICUService.java

/**\r
 *******************************************************************************\r
 * Copyright (C) 2001-2008, International Business Machines Corporation and    *\r
 * others. All Rights Reserved.                                                *\r
 *******************************************************************************\r
 */\r
package com.ibm.icu.impl;\r
\r
import java.lang.ref.SoftReference;\r
import java.util.ArrayList;\r
import java.util.Collections;\r
import java.util.Comparator;\r
import java.util.EventListener;\r
import java.util.HashMap;\r
import java.util.HashSet;\r
import java.util.Iterator;\r
import java.util.List;\r
import java.util.ListIterator;\r
import java.util.Map;\r
import java.util.Map.Entry;\r
import java.util.Set;\r
import java.util.SortedMap;\r
import java.util.TreeMap;\r
\r
import com.ibm.icu.util.ULocale;\r
\r
/**\r
 * <p>A Service provides access to service objects that implement a\r
 * particular service, e.g. transliterators.  Users provide a String\r
 * id (for example, a locale string) to the service, and get back an\r
 * object for that id.  Service objects can be any kind of object.\r
 * The service object is cached and returned for later queries, so\r
 * generally it should not be mutable, or the caller should clone the\r
 * object before modifying it.</p>\r
 *\r
 * <p>Services 'canonicalize' the query id and use the canonical id to\r
 * query for the service.  The service also defines a mechanism to\r
 * 'fallback' the id multiple times.  Clients can optionally request\r
 * the actual id that was matched by a query when they use an id to\r
 * retrieve a service object.</p>\r
 *\r
 * <p>Service objects are instantiated by Factory objects registered with\r
 * the service.  The service queries each Factory in turn, from most recently\r
 * registered to earliest registered, until one returns a service object.\r
 * If none responds with a service object, a fallback id is generated,\r
 * and the process repeats until a service object is returned or until\r
 * the id has no further fallbacks.</p>\r
 *\r
 * <p>Factories can be dynamically registered and unregistered with the\r
 * service.  When registered, a Factory is installed at the head of\r
 * the factory list, and so gets 'first crack' at any keys or fallback\r
 * keys.  When unregistered, it is removed from the service and can no\r
 * longer be located through it.  Service objects generated by this\r
 * factory and held by the client are unaffected.</p>\r
 *\r
 * <p>ICUService uses Keys to query factories and perform\r
 * fallback.  The Key defines the canonical form of the id, and\r
 * implements the fallback strategy.  Custom Keys can be defined that\r
 * parse complex IDs into components that Factories can more easily\r
 * use.  The Key can cache the results of this parsing to save\r
 * repeated effort.  ICUService provides convenience APIs that\r
 * take Strings and generate default Keys for use in querying.</p>\r
 *\r
 * <p>ICUService provides API to get the list of ids publicly\r
 * supported by the service (although queries aren't restricted to\r
 * this list).  This list contains only 'simple' IDs, and not fully\r
 * unique ids.  Factories are associated with each simple ID and\r
 * the responsible factory can also return a human-readable localized\r
 * version of the simple ID, for use in user interfaces.  ICUService\r
 * can also provide a sorted collection of the all the localized visible\r
 * ids.</p>\r
 *\r
 * <p>ICUService implements ICUNotifier, so that clients can register\r
 * to receive notification when factories are added or removed from\r
 * the service.  ICUService provides a default EventListener subinterface,\r
 * ServiceListener, which can be registered with the service.  When\r
 * the service changes, the ServiceListener's serviceChanged method\r
 * is called, with the service as the only argument.</p>\r
 *\r
 * <p>The ICUService API is both rich and generic, and it is expected\r
 * that most implementations will statically 'wrap' ICUService to\r
 * present a more appropriate API-- for example, to declare the type\r
 * of the objects returned from get, to limit the factories that can\r
 * be registered with the service, or to define their own listener\r
 * interface with a custom callback method.  They might also customize\r
 * ICUService by overriding it, for example, to customize the Key and\r
 * fallback strategy.  ICULocaleService is a customized service that\r
 * uses Locale names as ids and uses Keys that implement the standard\r
 * resource bundle fallback strategy.<p>\r
 */\r
public class ICUService extends ICUNotifier {\r
    /**\r
     * Name used for debugging.\r
     */\r
    protected final String name;\r
\r
    /**\r
     * Constructor.\r
     */\r
    public ICUService() {\r
        name = "";\r
    }\r
\r
    private static final boolean DEBUG = ICUDebug.enabled("service");\r
    /**\r
     * Construct with a name (useful for debugging).\r
     */\r
    public ICUService(String name) {\r
        this.name = name;\r
    }\r
\r
    /**\r
     * Access to factories is protected by a read-write lock.  This is\r
     * to allow multiple threads to read concurrently, but keep\r
     * changes to the factory list atomic with respect to all readers.\r
     */\r
    private final ICURWLock factoryLock = new ICURWLock();\r
\r
    /**\r
     * All the factories registered with this service.\r
     */\r
    private final List factories = new ArrayList();\r
\r
    /**\r
     * Record the default number of factories for this service.\r
     * Can be set by markDefault.\r
     */\r
    private int defaultSize = 0;\r
\r
    /**\r
     * Keys are used to communicate with factories to generate an\r
     * instance of the service.  Keys define how ids are\r
     * canonicalized, provide both a current id and a current\r
     * descriptor to use in querying the cache and factories, and\r
     * determine the fallback strategy.</p>\r
     *\r
     * <p>Keys provide both a currentDescriptor and a currentID.\r
     * The descriptor contains an optional prefix, followed by '/'\r
     * and the currentID.  Factories that handle complex keys,\r
     * for example number format factories that generate multiple\r
     * kinds of formatters for the same locale, use the descriptor\r
     * to provide a fully unique identifier for the service object,\r
     * while using the currentID (in this case, the locale string),\r
     * as the visible IDs that can be localized.\r
     *\r
     * <p> The default implementation of Key has no fallbacks and\r
     * has no custom descriptors.</p>\r
     */\r
    public static class Key {\r
        private final String id;\r
\r
        /**\r
         * Construct a key from an id.\r
         */\r
        public Key(String id) {\r
            this.id = id;\r
        }\r
\r
        /**\r
         * Return the original ID used to construct this key.\r
         */\r
        public final String id() {\r
            return id;\r
        }\r
\r
        /**\r
         * Return the canonical version of the original ID.  This implementation\r
         * returns the original ID unchanged.\r
         */\r
        public String canonicalID() {\r
            return id;\r
        }\r
\r
        /**\r
         * Return the (canonical) current ID.  This implementation\r
         * returns the canonical ID.\r
         */\r
        public String currentID() {\r
            return canonicalID();\r
        }\r
\r
        /**\r
         * Return the current descriptor.  This implementation returns\r
         * the current ID.  The current descriptor is used to fully\r
         * identify an instance of the service in the cache.  A\r
         * factory may handle all descriptors for an ID, or just a\r
         * particular descriptor.  The factory can either parse the\r
         * descriptor or use custom API on the key in order to\r
         * instantiate the service.\r
         */\r
        public String currentDescriptor() {\r
            return "/" + currentID();\r
        }\r
\r
        /**\r
         * If the key has a fallback, modify the key and return true,\r
         * otherwise return false.  The current ID will change if there\r
         * is a fallback.  No currentIDs should be repeated, and fallback\r
         * must eventually return false.  This implmentation has no fallbacks\r
         * and always returns false.\r
         */\r
        public boolean fallback() {\r
            return false;\r
        }\r
\r
        /**\r
         * If a key created from id would eventually fallback to match the\r
         * canonical ID of this key, return true.\r
         */\r
        public boolean isFallbackOf(String idToCheck) {\r
            return canonicalID().equals(idToCheck);\r
        }\r
    }\r
\r
    /**\r
     * Factories generate the service objects maintained by the\r
     * service.  A factory generates a service object from a key,\r
     * updates id->factory mappings, and returns the display name for\r
     * a supported id.\r
     */\r
    public static interface Factory {\r
\r
        /**\r
         * Create a service object from the key, if this factory\r
         * supports the key.  Otherwise, return null.\r
         *\r
         * <p>If the factory supports the key, then it can call\r
         * the service's getKey(Key, String[], Factory) method\r
         * passing itself as the factory to get the object that\r
         * the service would have created prior to the factory's\r
         * registration with the service.  This can change the\r
         * key, so any information required from the key should\r
         * be extracted before making such a callback.\r
         */\r
        public Object create(Key key, ICUService service);\r
\r
        /**\r
         * Update the result IDs (not descriptors) to reflect the IDs\r
         * this factory handles.  This function and getDisplayName are\r
         * used to support ICUService.getDisplayNames.  Basically, the\r
         * factory has to determine which IDs it will permit to be\r
         * available, and of those, which it will provide localized\r
         * display names for.  In most cases this reflects the IDs that\r
         * the factory directly supports.\r
         */\r
        public void updateVisibleIDs(Map result);\r
\r
        /**\r
         * Return the display name for this id in the provided locale.\r
         * This is an localized id, not a descriptor.  If the id is\r
         * not visible or not defined by the factory, return null.\r
         * If locale is null, return id unchanged.\r
         */\r
        public String getDisplayName(String id, ULocale locale);\r
    }\r
\r
    /**\r
     * A default implementation of factory.  This provides default\r
     * implementations for subclasses, and implements a singleton\r
     * factory that matches a single id  and returns a single\r
     * (possibly deferred-initialized) instance.  This implements\r
     * updateVisibleIDs to add a mapping from its ID to itself\r
     * if visible is true, or to remove any existing mapping\r
     * for its ID if visible is false.\r
     */\r
    public static class SimpleFactory implements Factory {\r
        protected Object instance;\r
        protected String id;\r
        protected boolean visible;\r
\r
        /**\r
         * Convenience constructor that calls SimpleFactory(Object, String, boolean)\r
         * with visible true.\r
         */\r
        public SimpleFactory(Object instance, String id) {\r
            this(instance, id, true);\r
        }\r
\r
        /**\r
         * Construct a simple factory that maps a single id to a single\r
         * service instance.  If visible is true, the id will be visible.\r
         * Neither the instance nor the id can be null.\r
         */\r
        public SimpleFactory(Object instance, String id, boolean visible) {\r
            if (instance == null || id == null) {\r
                throw new IllegalArgumentException("Instance or id is null");\r
            }\r
            this.instance = instance;\r
            this.id = id;\r
            this.visible = visible;\r
        }\r
\r
        /**\r
         * Return the service instance if the factory's id is equal to\r
         * the key's currentID.  Service is ignored.\r
         */\r
        public Object create(Key key, ICUService service) {\r
            if (id.equals(key.currentID())) {\r
                return instance;\r
            }\r
            return null;\r
        }\r
\r
        /**\r
         * If visible, adds a mapping from id -> this to the result,\r
         * otherwise removes id from result.\r
         */\r
        public void updateVisibleIDs(Map result) {\r
            if (visible) {\r
                result.put(id, this);\r
            } else {\r
                result.remove(id);\r
            }\r
        }\r
\r
        /**\r
         * If this.id equals id, returns id regardless of locale,\r
         * otherwise returns null.  (This default implementation has\r
         * no localized id information.)\r
         */\r
        public String getDisplayName(String identifier, ULocale locale) {\r
            return (visible && id.equals(identifier)) ? identifier : null;\r
        }\r
\r
        /**\r
         * For debugging.\r
         */\r
        public String toString() {\r
            StringBuffer buf = new StringBuffer(super.toString());\r
            buf.append(", id: ");\r
            buf.append(id);\r
            buf.append(", visible: ");\r
            buf.append(visible);\r
            return buf.toString();\r
        }\r
    }\r
\r
    /**\r
     * Convenience override for get(String, String[]). This uses\r
     * createKey to create a key for the provided descriptor.\r
     */\r
    public Object get(String descriptor) {\r
        return getKey(createKey(descriptor), null);\r
    }\r
\r
    /**\r
     * Convenience override for get(Key, String[]).  This uses\r
     * createKey to create a key from the provided descriptor.\r
     */\r
    public Object get(String descriptor, String[] actualReturn) {\r
        if (descriptor == null) {\r
            throw new NullPointerException("descriptor must not be null");\r
        }\r
        return getKey(createKey(descriptor), actualReturn);\r
    }\r
\r
    /**\r
     * Convenience override for get(Key, String[]).\r
     */\r
    public Object getKey(Key key) {\r
        return getKey(key, null);\r
    }\r
\r
    /**\r
     * <p>Given a key, return a service object, and, if actualReturn\r
     * is not null, the descriptor with which it was found in the\r
     * first element of actualReturn.  If no service object matches\r
     * this key, return null, and leave actualReturn unchanged.</p>\r
     *\r
     * <p>This queries the cache using the key's descriptor, and if no\r
     * object in the cache matches it, tries the key on each\r
     * registered factory, in order.  If none generates a service\r
     * object for the key, repeats the process with each fallback of\r
     * the key, until either one returns a service object, or the key\r
     * has no fallback.</p>\r
     *\r
     * <p>If key is null, just returns null.</p>\r
     */\r
    public Object getKey(Key key, String[] actualReturn) {\r
        return getKey(key, actualReturn, null);\r
    }\r
\r
    // debugging\r
    // Map hardRef;\r
\r
    public Object getKey(Key key, String[] actualReturn, Factory factory) {\r
        if (factories.size() == 0) {\r
            return handleDefault(key, actualReturn);\r
        }\r
\r
        if (DEBUG) System.out.println("Service: " + name + " key: " + key.canonicalID());\r
\r
        CacheEntry result = null;\r
        if (key != null) {\r
            try {\r
                // The factory list can't be modified until we're done,\r
                // otherwise we might update the cache with an invalid result.\r
                // The cache has to stay in synch with the factory list.\r
                factoryLock.acquireRead();\r
\r
                Map cache = null;\r
                SoftReference cref = cacheref; // copy so we don't need to sync on this\r
                if (cref != null) {\r
                    if (DEBUG) System.out.println("Service " + name + " ref exists");\r
                    cache = (Map)cref.get();\r
                }\r
                if (cache == null) {\r
                    if (DEBUG) System.out.println("Service " + name + " cache was empty");\r
                    // synchronized since additions and queries on the cache must be atomic\r
                    // they can be interleaved, though\r
                    cache = Collections.synchronizedMap(new HashMap());\r
//                  hardRef = cache; // debug\r
                    cref = new SoftReference(cache);\r
                }\r
\r
                String currentDescriptor = null;\r
                ArrayList cacheDescriptorList = null;\r
                boolean putInCache = false;\r
\r
                int NDebug = 0;\r
\r
                int startIndex = 0;\r
                int limit = factories.size();\r
                boolean cacheResult = true;\r
                if (factory != null) {\r
                    for (int i = 0; i < limit; ++i) {\r
                        if (factory == factories.get(i)) {\r
                            startIndex = i + 1;\r
                            break;\r
                        }\r
                    }\r
                    if (startIndex == 0) {\r
                        throw new IllegalStateException("Factory " + factory + "not registered with service: " + this);\r
                    }\r
                    cacheResult = false;\r
                }\r
\r
            outer:\r
                do {\r
                    currentDescriptor = key.currentDescriptor();\r
                    if (DEBUG) System.out.println(name + "[" + NDebug++ + "] looking for: " + currentDescriptor);\r
                    result = (CacheEntry)cache.get(currentDescriptor);\r
                    if (result != null) {\r
                        if (DEBUG) System.out.println(name + " found with descriptor: " + currentDescriptor);\r
                        break outer;\r
                    } else {\r
                        if (DEBUG) System.out.println("did not find: " + currentDescriptor + " in cache");\r
                    }\r
\r
                    // first test of cache failed, so we'll have to update\r
                    // the cache if we eventually succeed-- that is, if we're\r
                    // going to update the cache at all.\r
                    putInCache = cacheResult;\r
\r
                    //  int n = 0;\r
                    int index = startIndex;\r
                    while (index < limit) {\r
                        Factory f = (Factory)factories.get(index++);\r
                        if (DEBUG) System.out.println("trying factory[" + (index-1) + "] " + f.toString());\r
                        Object service = f.create(key, this);\r
                        if (service != null) {\r
                            result = new CacheEntry(currentDescriptor, service);\r
                            if (DEBUG) System.out.println(name + " factory supported: " + currentDescriptor + ", caching");\r
                            break outer;\r
                        } else {\r
                            if (DEBUG) System.out.println("factory did not support: " + currentDescriptor);\r
                        }\r
                    }\r
\r
                    // prepare to load the cache with all additional ids that\r
                    // will resolve to result, assuming we'll succeed.  We\r
                    // don't want to keep querying on an id that's going to\r
                    // fallback to the one that succeeded, we want to hit the\r
                    // cache the first time next goaround.\r
                    if (cacheDescriptorList == null) {\r
                        cacheDescriptorList = new ArrayList(5);\r
                    }\r
                    cacheDescriptorList.add(currentDescriptor);\r
\r
                } while (key.fallback());\r
\r
                if (result != null) {\r
                    if (putInCache) {\r
                        if (DEBUG) System.out.println("caching '" + result.actualDescriptor + "'");\r
                        cache.put(result.actualDescriptor, result);\r
                        if (cacheDescriptorList != null) {\r
                            Iterator iter = cacheDescriptorList.iterator();\r
                            while (iter.hasNext()) {\r
                                String desc = (String)iter.next();\r
                                if (DEBUG) System.out.println(name + " adding descriptor: '" + desc + "' for actual: '" + result.actualDescriptor + "'");\r
\r
                                cache.put(desc, result);\r
                            }\r
                        }\r
                        // Atomic update.  We held the read lock all this time\r
                        // so we know our cache is consistent with the factory list.\r
                        // We might stomp over a cache that some other thread\r
                        // rebuilt, but that's the breaks.  They're both good.\r
                        cacheref = cref;\r
                    }\r
\r
                    if (actualReturn != null) {\r
                        // strip null prefix\r
                        if (result.actualDescriptor.indexOf("/") == 0) {\r
                            actualReturn[0] = result.actualDescriptor.substring(1);\r
                        } else {\r
                            actualReturn[0] = result.actualDescriptor;\r
                        }\r
                    }\r
\r
                    if (DEBUG) System.out.println("found in service: " + name);\r
\r
                    return result.service;\r
                }\r
            }\r
            finally {\r
                factoryLock.releaseRead();\r
            }\r
        }\r
\r
        if (DEBUG) System.out.println("not found in service: " + name);\r
\r
        return handleDefault(key, actualReturn);\r
    }\r
    private SoftReference cacheref;\r
\r
    // Record the actual id for this service in the cache, so we can return it\r
    // even if we succeed later with a different id.\r
    private static final class CacheEntry {\r
        final String actualDescriptor;\r
        final Object service;\r
        CacheEntry(String actualDescriptor, Object service) {\r
            this.actualDescriptor = actualDescriptor;\r
            this.service = service;\r
        }\r
    }\r
\r
\r
    /**\r
     * Default handler for this service if no factory in the list\r
     * handled the key.\r
     */\r
    protected Object handleDefault(Key key, String[] actualIDReturn) {\r
        return null;\r
    }\r
\r
    /**\r
     * Convenience override for getVisibleIDs(String) that passes null\r
     * as the fallback, thus returning all visible IDs.\r
     */\r
    public Set getVisibleIDs() {\r
        return getVisibleIDs(null);\r
    }\r
\r
    /**\r
     * <p>Return a snapshot of the visible IDs for this service.  This\r
     * set will not change as Factories are added or removed, but the\r
     * supported ids will, so there is no guarantee that all and only\r
     * the ids in the returned set are visible and supported by the\r
     * service in subsequent calls.</p>\r
     *\r
     * <p>matchID is passed to createKey to create a key.  If the\r
     * key is not null, it is used to filter out ids that don't have\r
     * the key as a fallback.\r
     */\r
    public Set getVisibleIDs(String matchID) {\r
        Set result = getVisibleIDMap().keySet();\r
\r
        Key fallbackKey = createKey(matchID);\r
\r
        if (fallbackKey != null) {\r
            Set temp = new HashSet(result.size());\r
            Iterator iter = result.iterator();\r
            while (iter.hasNext()) {\r
                String id = (String)iter.next();\r
                if (fallbackKey.isFallbackOf(id)) {\r
                    temp.add(id);\r
                }\r
            }\r
            result = temp;\r
        }\r
        return result;\r
    }\r
\r
    /**\r
     * Return a map from visible ids to factories.\r
     */\r
    private Map getVisibleIDMap() {\r
        Map idcache = null;\r
        SoftReference ref = idref;\r
        if (ref != null) {\r
            idcache = (Map)ref.get();\r
        }\r
        while (idcache == null) {\r
            synchronized (this) { // or idref-only lock?\r
                if (ref == idref || idref == null) {\r
                    // no other thread updated idref before we got the lock, so\r
                    // grab the factory list and update it ourselves\r
                    try {\r
                        factoryLock.acquireRead();\r
                        idcache = new HashMap();\r
                        ListIterator lIter = factories.listIterator(factories.size());\r
                        while (lIter.hasPrevious()) {\r
                            Factory f = (Factory)lIter.previous();\r
                            f.updateVisibleIDs(idcache);\r
                        }\r
                        idcache = Collections.unmodifiableMap(idcache);\r
                        idref = new SoftReference(idcache);\r
                    }\r
                    finally {\r
                        factoryLock.releaseRead();\r
                    }\r
                } else {\r
                    // another thread updated idref, but gc may have stepped\r
                    // in and undone its work, leaving idcache null.  If so,\r
                    // retry.\r
                    ref = idref;\r
                    idcache = (Map)ref.get();\r
                }\r
            }\r
        }\r
\r
        return idcache;\r
    }\r
    private SoftReference idref;\r
\r
    /**\r
     * Convenience override for getDisplayName(String, ULocale) that\r
     * uses the current default locale.\r
     */\r
    public String getDisplayName(String id) {\r
        return getDisplayName(id, ULocale.getDefault());\r
    }\r
\r
    /**\r
     * Given a visible id, return the display name in the requested locale.\r
     * If there is no directly supported id corresponding to this id, return\r
     * null.\r
     */\r
    public String getDisplayName(String id, ULocale locale) {\r
        Map m = getVisibleIDMap();\r
        Factory f = (Factory)m.get(id);\r
        if (f != null) {\r
            return f.getDisplayName(id, locale);\r
        }\r
\r
        Key key = createKey(id);\r
        while (key.fallback()) {\r
            f = (Factory)m.get(key.currentID());\r
            if (f != null) {\r
                return f.getDisplayName(id, locale);\r
            }\r
        }\r
        \r
        return null;\r
    }\r
\r
    /**\r
     * Convenience override of getDisplayNames(ULocale, Comparator, String) that \r
     * uses the current default Locale as the locale, null as\r
     * the comparator, and null for the matchID.\r
     */\r
    public SortedMap getDisplayNames() {\r
        ULocale locale = ULocale.getDefault();\r
        return getDisplayNames(locale, null, null);\r
    }\r
\r
    /**\r
     * Convenience override of getDisplayNames(ULocale, Comparator, String) that\r
     * uses null for the comparator, and null for the matchID.\r
     */\r
    public SortedMap getDisplayNames(ULocale locale) {\r
        return getDisplayNames(locale, null, null);\r
    }\r
\r
    /**\r
     * Convenience override of getDisplayNames(ULocale, Comparator, String) that\r
     * uses null for the matchID, thus returning all display names.\r
     */\r
    public SortedMap getDisplayNames(ULocale locale, Comparator com) {\r
        return getDisplayNames(locale, com, null);\r
    }\r
\r
    /**\r
     * Convenience override of getDisplayNames(ULocale, Comparator, String) that\r
     * uses null for the comparator.\r
     */\r
    public SortedMap getDisplayNames(ULocale locale, String matchID) {\r
        return getDisplayNames(locale, null, matchID);\r
    }\r
\r
    /**\r
     * Return a snapshot of the mapping from display names to visible\r
     * IDs for this service.  This set will not change as factories\r
     * are added or removed, but the supported ids will, so there is\r
     * no guarantee that all and only the ids in the returned map will\r
     * be visible and supported by the service in subsequent calls,\r
     * nor is there any guarantee that the current display names match\r
     * those in the set.  The display names are sorted based on the\r
     * comparator provided.\r
     */\r
    public SortedMap getDisplayNames(ULocale locale, Comparator com, String matchID) {\r
        SortedMap dncache = null;\r
        LocaleRef ref = dnref;\r
\r
        if (ref != null) {\r
            dncache = ref.get(locale, com);\r
        }\r
\r
        while (dncache == null) {\r
            synchronized (this) {\r
                if (ref == dnref || dnref == null) {\r
                    dncache = new TreeMap(com); // sorted\r
                    \r
                    Map m = getVisibleIDMap();\r
                    Iterator ei = m.entrySet().iterator();\r
                    while (ei.hasNext()) {\r
                        Entry e = (Entry)ei.next();\r
                        String id = (String)e.getKey();\r
                        Factory f = (Factory)e.getValue();\r
                        dncache.put(f.getDisplayName(id, locale), id);\r
                    }\r
\r
                    dncache = Collections.unmodifiableSortedMap(dncache);\r
                    dnref = new LocaleRef(dncache, locale, com);\r
                } else {\r
                    ref = dnref;\r
                    dncache = ref.get(locale, com);\r
                }\r
            }\r
        }\r
\r
        Key matchKey = createKey(matchID);\r
        if (matchKey == null) {\r
            return dncache;\r
        }\r
\r
        SortedMap result = new TreeMap(dncache);\r
        Iterator iter = result.entrySet().iterator();\r
        while (iter.hasNext()) {\r
            Entry e = (Entry)iter.next();\r
            if (!matchKey.isFallbackOf((String)e.getValue())) {\r
                iter.remove();\r
            }\r
        }\r
        return result;\r
    }\r
\r
    // we define a class so we get atomic simultaneous access to the\r
    // locale, comparator, and corresponding map.\r
    private static class LocaleRef {\r
        private final ULocale locale;\r
        private SoftReference ref;\r
        private Comparator com;\r
\r
        LocaleRef(Map dnCache, ULocale locale, Comparator com) {\r
            this.locale = locale;\r
            this.com = com;\r
            this.ref = new SoftReference(dnCache);\r
        }\r
\r
\r
        SortedMap get(ULocale loc, Comparator comp) {\r
            SortedMap m = (SortedMap)ref.get();\r
            if (m != null &&\r
                this.locale.equals(loc) &&\r
                (this.com == comp || (this.com != null && this.com.equals(comp)))) {\r
\r
                return m;\r
            }\r
            return null;\r
        }\r
    }\r
    private LocaleRef dnref;\r
\r
    /**\r
     * Return a snapshot of the currently registered factories.  There\r
     * is no guarantee that the list will still match the current\r
     * factory list of the service subsequent to this call.\r
     */\r
    public final List factories() {\r
        try {\r
            factoryLock.acquireRead();\r
            return new ArrayList(factories);\r
        }\r
        finally{\r
            factoryLock.releaseRead();\r
        }\r
    }\r
\r
    /**\r
     * A convenience override of registerObject(Object, String, boolean)\r
     * that defaults visible to true.\r
     */\r
    public Factory registerObject(Object obj, String id) {\r
        return registerObject(obj, id, true);\r
    }\r
\r
    /**\r
     * Register an object with the provided id.  The id will be\r
     * canonicalized.  The canonicalized ID will be returned by\r
     * getVisibleIDs if visible is true.\r
     */\r
    public Factory registerObject(Object obj, String id, boolean visible) {\r
        String canonicalID = createKey(id).canonicalID();\r
        return registerFactory(new SimpleFactory(obj, canonicalID, visible));\r
    }\r
\r
    /**\r
     * Register a Factory.  Returns the factory if the service accepts\r
     * the factory, otherwise returns null.  The default implementation\r
     * accepts all factories.\r
     */\r
    public final Factory registerFactory(Factory factory) {\r
        if (factory == null) {\r
            throw new NullPointerException();\r
        }\r
        try {\r
            factoryLock.acquireWrite();\r
            factories.add(0, factory);\r
            clearCaches();\r
        }\r
        finally {\r
            factoryLock.releaseWrite();\r
        }\r
        notifyChanged();\r
        return factory;\r
    }\r
\r
    /**\r
     * Unregister a factory.  The first matching registered factory will\r
     * be removed from the list.  Returns true if a matching factory was\r
     * removed.\r
     */\r
    public final boolean unregisterFactory(Factory factory) {\r
        if (factory == null) {\r
            throw new NullPointerException();\r
        }\r
\r
        boolean result = false;\r
        try {\r
            factoryLock.acquireWrite();\r
            if (factories.remove(factory)) {\r
                result = true;\r
                clearCaches();\r
            }\r
        }\r
        finally {\r
            factoryLock.releaseWrite();\r
        }\r
\r
        if (result) {\r
            notifyChanged();\r
        }\r
        return result;\r
    }\r
\r
    /**\r
     * Reset the service to the default factories.  The factory\r
     * lock is acquired and then reInitializeFactories is called.\r
     */\r
    public final void reset() {\r
        try {\r
            factoryLock.acquireWrite();\r
            reInitializeFactories();\r
            clearCaches();\r
        }\r
        finally {\r
            factoryLock.releaseWrite();\r
        }\r
        notifyChanged();\r
    }\r
\r
    /**\r
     * Reinitialize the factory list to its default state.  By default\r
     * this clears the list.  Subclasses can override to provide other\r
     * default initialization of the factory list.  Subclasses must\r
     * not call this method directly, as it must only be called while\r
     * holding write access to the factory list.\r
     */\r
    protected void reInitializeFactories() {\r
        factories.clear();\r
    }\r
\r
    /**\r
     * Return true if the service is in its default state.  The default\r
     * implementation returns true if there are no factories registered.\r
     */\r
    public boolean isDefault() {\r
        return factories.size() == defaultSize;\r
    }\r
\r
    /**\r
     * Set the default size to the current number of registered factories.\r
     * Used by subclasses to customize the behavior of isDefault.\r
     */\r
    protected void markDefault() {\r
        defaultSize = factories.size();\r
    }\r
\r
    /**\r
     * Create a key from an id.  This creates a Key instance.\r
     * Subclasses can override to define more useful keys appropriate\r
     * to the factories they accept.  If id is null, returns null.\r
     */\r
    public Key createKey(String id) {\r
        return id == null ? null : new Key(id);\r
    }\r
\r
    /**\r
     * Clear caches maintained by this service.  Subclasses can\r
     * override if they implement additional that need to be cleared\r
     * when the service changes. Subclasses should generally not call\r
     * this method directly, as it must only be called while\r
     * synchronized on this.\r
     */\r
    protected void clearCaches() {\r
        // we don't synchronize on these because methods that use them\r
        // copy before use, and check for changes if they modify the\r
        // caches.\r
        cacheref = null;\r
        idref = null;\r
        dnref = null;\r
    }\r
\r
    /**\r
     * Clears only the service cache.\r
     * This can be called by subclasses when a change affects the service\r
     * cache but not the id caches, e.g., when the default locale changes\r
     * the resolution of ids changes, but not the visible ids themselves.\r
     */\r
    protected void clearServiceCache() {\r
        cacheref = null;\r
    }\r
\r
    /**\r
     * ServiceListener is the listener that ICUService provides by default.\r
     * ICUService will notifiy this listener when factories are added to\r
     * or removed from the service.  Subclasses can provide\r
     * different listener interfaces that extend EventListener, and modify\r
     * acceptsListener and notifyListener as appropriate.\r
     */\r
    public static interface ServiceListener extends EventListener {\r
        public void serviceChanged(ICUService service);\r
    }\r
\r
    /**\r
     * Return true if the listener is accepted; by default this\r
     * requires a ServiceListener.  Subclasses can override to accept\r
     * different listeners.\r
     */\r
    protected boolean acceptsListener(EventListener l) {\r
        return l instanceof ServiceListener;\r
    }\r
\r
    /**\r
     * Notify the listener, which by default is a ServiceListener.\r
     * Subclasses can override to use a different listener.\r
     */\r
    protected void notifyListener(EventListener l) {\r
        ((ServiceListener)l).serviceChanged(this);\r
    }\r
\r
    /**\r
     * Return a string describing the statistics for this service.\r
     * This also resets the statistics. Used for debugging purposes.\r
     */\r
    public String stats() {\r
        ICURWLock.Stats stats = factoryLock.resetStats();\r
        if (stats != null) {\r
            return stats.toString();\r
        }\r
        return "no stats";\r
    }\r
\r
    /**\r
     * Return the name of this service. This will be the empty string if none was assigned.\r
     */\r
    public String getName() {\r
        return name;\r
    }\r
\r
    /**\r
     * Returns the result of super.toString, appending the name in curly braces.\r
     */\r
    public String toString() {\r
        return super.toString() + "{" + name + "}";\r
    }\r
}\r