src/com/ibm/icu/impl/ICUService.java - external/github.com/unicode-org/icu - Git at Google

 /**
  *******************************************************************************
  * Copyright (C) 2001-2002, International Business Machines Corporation and    *
  * others. All Rights Reserved.                                                *
  *******************************************************************************
  *
  * $Source: /xsrl/Nsvn/icu/icu4j/src/com/ibm/icu/impl/ICUService.java,v $
  * $Date: 2002/08/13 23:40:52 $
  * $Revision: 1.7 $
  *
  *******************************************************************************
  */
 package com.ibm.icu.impl;

 import java.lang.ref.SoftReference;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.EventListener;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
 import java.util.ListIterator;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Set;
 import java.util.TreeMap;

 /**
  * <p>A Service provides access to service objects that implement a
  * particular service, e.g. transliterators.  Users provide a String
  * id (for example, a locale string) to the service, and get back an
  * object for that id.  Service objects can be any kind of object.
  * The service object is cached and returned for later queries, so
  * generally it should not be mutable, or the caller should clone the
  * object before modifying it.</p>
  *
  * <p>Services 'canonicalize' the query id and use the canonical id
  * to query for the service.  The service also defines a mechanism
  * to 'fallback' the id multiple times.  Clients can optionally
  * request the actual id that was matched by a query when they
  * use an id to retrieve a service object.</p>
  *
  * <p>Service objects are instantiated by Factory objects registered with
  * the service.  The service queries each Factory in turn, from most recently
  * registered to earliest registered, until one returns a service object.
  * If none responds with a service object, a fallback id is generated,
  * and the process repeats until a service object is returned or until
  * the id has no further fallbacks.</p>
  *
  * <p>Factories can be dynamically registered and unregistered with the
  * service.  When registered, a Factory is installed at the head of
  * the factory list, and so gets 'first crack' at any keys or fallback
  * keys.  When unregistered, it is removed from the service and can no
  * longer be located through it.  Service objects generated by this
  * factory and held by the client are unaffected.</p>
  *
  * <p>Internally, ICUService uses Keys to query factories and perform
  * fallback.  The Key defines the canonical form of the id, and
  * implements the fallback strategy.  Custom Keys can be defined that
  * parse complex IDs into components that Factories can more easily
  * use.  The Key can cache the results of this parsing to save
  * repeated effort.</p>
  *
  * <p>ICUService implements ICUNotifier, so that clients can register
  * to receive notification when factories are added or removed from
  * the service.  ICUService provides a default EventListener subinterface,
  * ServiceListener, which can be registered with the service.  When
  * the service changes, the ServiceListener's serviceChanged method
  * is called, with the service as the only argument.</p>
  *
  * <p>The ICUService API is both rich and generic, and it is expected
  * that most implementations will statically 'wrap' ICUService to
  * present a more appropriate API-- for example, to declare the type
  * of the objects returned from get, to limit the factories that can
  * be registered with the service, or to define their own listener
  * interface with a custom callback method.  They might also customize
  * ICUService by overriding it, for example, to customize the Key and
  * fallback strategy.  ICULocaleService is a customized service that
  * uses Locale names as ids and uses Keys that implement the standard
  * resource bundle fallback strategy.<p>
  */
 public class ICUService extends ICUNotifier {
     /**
      * Access to factories is protected by a read-write lock.  This is
      * to allow multiple threads to read concurrently, but keep
      * changes to the factory list atomic with respect to all readers.
      */
     private final ICURWLock factoryLock = new ICURWLock();

     /**
      * All the factories registered with this service.
      */
     private final List factories = new ArrayList();

     /**
      * Keys define how ids are canonicalized, and determine the
      * fallback strategy used when querying the factories.  The default
      * key just takes as its canonicalID the id assigned to it when it
      * is constructed, and has no fallbacks.
      */
     public static class Key {
         private final String id;

 	/**
 	 * Construct a key from an id.
 	 */
         public Key(String id) {
             this.id = id;
         }

         /**
          * Return the original ID.
          */
         public final String id() {
             return id;
         }

         /**
          * Return the canonical version of the original ID.  This implementation
 	 * returns the original ID unchanged.
          */
         public String canonicalID() {
             return id;
         }

         /**
          * Return the (canonical) current ID.  This implementation returns the
 	 * canonical ID.
          */
         public String currentID() {
             return canonicalID();
         }

         /**
          * If the key has a fallback, modify the key and return true,
          * otherwise return false.  The current ID will change if there
 	 * is a fallback.  No currentIDs should be repeated, and fallback
 	 * must eventually return false.  This implmentation has no fallbacks
 	 * and always returns false.
 	 */
         public boolean fallback() {
             return false;
         }
     }

     /**
      * Factories generate the service objects maintained by the
      * service.  A factory generates a service object from a key,
      * updates id->factory mappings, and returns the display name for
      * a supported id.
      */
     public static interface Factory {
         /**
          * Create a service object from the key, if this factory
          * supports the key.  Otherwise, return null.
 	 */
         public Object create(Key key);

 	/**
 	 * Add IDs understood by this factory to the result map, with
 	 * this factory as the value. If this factory hides IDs
 	 * currently in result, it should remove or reset the mappings
 	 * for those IDs.
 	 */
 	public void updateVisibleIDs(Map result);

 	/**
 	 * Return the display name for this id in the provided locale.
 	 * If the id is not visible or not defined by the factory,
 	 * return null.
 	 */
 	public String getDisplayName(String id, Locale locale);
     }

     /**
      * A default implementation of factory.  This provides default
      * implementations for subclasses, and implements a singleton
      * factory that matches a single id and returns a single
      * (possibly deferred-initialized) instance.  If visible is
      * true, updates the map passed to updateVisibleIDs with a
      * mapping from id to itself.
      */
     public static class SimpleFactory implements Factory {
 	protected Object instance;
 	protected String id;
 	protected boolean visible;

 	/**
 	 * Convenience constructor that calls SimpleFactory(Object, String, boolean)
 	 * with visible true.
 	 */
 	public SimpleFactory(Object instance, String id) {
 	    this(instance, id, true);
 	}

 	/**
 	 * Construct a simple factory that maps a single id to a single
 	 * service instance.  If visible is true, the id will be visible.
 	 * Neither the instance nor the id can be null.
 	 */
 	public SimpleFactory(Object instance, String id, boolean visible) {
 	    if (instance == null || id == null) {
 		throw new IllegalArgumentException("Instance or id is null");
 	    }
 	    this.instance = instance;
 	    this.id = id;
 	    this.visible = visible;
 	}

 	/**
 	 * Return the service instance if id equals the key's currentID.
 	 */
 	public Object create(Key key) {
 	    if (id.equals(key.currentID())) {
 		return instance;
 	    }
 	    return null;
 	}

 	/**
 	 * If visible, adds a mapping from id -> this to the result.
 	 */
 	public void updateVisibleIDs(Map result) {
 	    if (visible) result.put(id, this);
 	}

 	/**
 	 * If id equals this.id, returns id regardless of locale, otherwise
 	 * returns null.
 	 */
 	public String getDisplayName(String id, Locale locale) {
 	    return (visible && id.equals(this.id)) ? id : null;
 	}
     }

     /**
      * Convenience override for get(String, String[]).
      */
     public Object get(String id) {
 	return get(id, null);
     }

     /**
      * <p>Given an id, return a service object, and, if actualIDReturn
      * is not null, the actual id under which it was found in the
      * first element of actualIDReturn.  If no service object matches
      * this id, return null, and leave actualIDReturn unchanged.</p>
      *
      * <p>This tries each registered factory in order, and if none can
      * generate a service object for the key, repeats the process with
      * each fallback of the key until one returns a service object, or
      * the key has no fallback.</p>
      */
     public Object get(String id, String[] actualIDReturn) {
 	if (id == null) {
 	    throw new NullPointerException();
 	}
 	if (factories.size() == 0) {
 	    return null;
 	}

 	CacheEntry result = null;
 	Key key = createKey(id);
 	if (key != null) {
 	    try {
 		// The factory list can't be modified until we're done,
 		// otherwise we might update the cache with an invalid result.
 		// The cache has to stay in synch with the factory list.
 		factoryLock.acquireRead();

 		Map cache = null;
 		SoftReference cref = cacheref; // copy so we don't need to sync on this
 		if (cref != null) {
 		    cache = (Map)cref.get();
 		}
 		if (cache == null) {
 		    // synchronized since additions and queries on the cache must be atomic
 		    // they can be interleaved, though
 		    cache = Collections.synchronizedMap(new HashMap());
 		    cref = new SoftReference(cache);
 		}

 		String currentID = null;
 		ArrayList cacheIDList = null;
 		boolean putInCache = false;
 	    outer:
 		do {
 		    currentID = key.currentID();

 		    result = (CacheEntry)cache.get(currentID);
 		    if (result != null) {
 			break outer;
 		    }

 		    // first test of cache failed, so we'll have to update
 		    // the cache if we eventually succeed.
 		    putInCache = true;

 		    Iterator fi = factories.iterator();
 		    while (fi.hasNext()) {
 			Object service = ((Factory)fi.next()).create(key);
 			if (service != null) {
 			    result = new CacheEntry(currentID, service);
 			    break outer;
 			}
 		    }

 		    // prepare to load the cache with all additional ids that
 		    // will resolve to result, assuming we'll succeed.  We
 		    // don't want to keep querying on an id that's going to
 		    // fallback to the one that succeeded, we want to hit the
 		    // cache the first time next goaround.
 		    if (cacheIDList == null) {
 			cacheIDList = new ArrayList(5);
 		    }
 		    cacheIDList.add(currentID);

 		} while (key.fallback());

 		if (result != null) {
 		    if (putInCache) {
 			cache.put(result.actualID, result);
 			if (cacheIDList != null) {
 			    Iterator iter = cacheIDList.iterator();
 			    while (iter.hasNext()) {
 				cache.put((String)iter.next(), result);
 			    }
 			}
 			// Atomic update.  We held the read lock all this time
 			// so we know our cache is consistent with the factory list.
 			// We might stomp over a cache that some other thread
 			// rebuilt, but that's the breaks.  They're both good.
 			cacheref = cref;
 		    }

 		    if (actualIDReturn != null) {
 			actualIDReturn[0] = result.actualID;
 		    }

 		    return result.service;
 		}
 	    }
 	    finally {
 		factoryLock.releaseRead();
 	    }
 	}

 	return null;
     }
     private SoftReference cacheref;

     // Record the actual id for this service in the cache, so we can return it
     // even if we succeed later with a different id.
     private static final class CacheEntry {
 	String actualID;
 	Object service;
 	CacheEntry(String actualID, Object service) {
 	    this.actualID = actualID;
 	    this.service = service;
 	}
     }

     /**
      * Return a snapshot of the visible IDs for this service.  This
      * set will not change as Factories are added or removed, but the
      * supported ids will, so there is no guarantee that all and only
      * the ids in the returned set are visible and supported by the
      * service in subsequent calls.
      */
     public Set getVisibleIDs() {
 	return getVisibleIDMap().keySet();
     }

     /**
      * Return a map from visible ids to factories.
      */
     private Map getVisibleIDMap() {
         Map idcache = null;
 	SoftReference ref = idref;
         if (ref != null) {
             idcache = (Map)ref.get();
         }
         while (idcache == null) {
 	    synchronized (this) { // or idref-only lock?
 		if (ref == idref || idref == null) {
 		    // no other thread updated idref before we got the lock, so
 		    // grab the factory list and update it ourselves
 		    try {
 			factoryLock.acquireRead();

 			idcache = new TreeMap(String.CASE_INSENSITIVE_ORDER);

 			ListIterator lIter = factories.listIterator(factories.size());
 			while (lIter.hasPrevious()) {
 			    Factory f = (Factory)lIter.previous();
 			    f.updateVisibleIDs(idcache);
 			}
 			idcache = Collections.unmodifiableMap(idcache);
 			idref = new SoftReference(idcache);
 		    }
 		    finally {
 			factoryLock.releaseRead();
 		    }
 		} else {
 		    // another thread updated idref, but gc may have stepped
 		    // in and undone its work, leaving idcache null.  If so,
 		    // retry.
 		    ref = idref;
 		    idcache = (Map)ref.get();
 		}
 	    }
         }

         return idcache;
     }
     private SoftReference idref;

     /**
      * Convenience override for getDisplayName(String, Locale) that
      * uses the current default locale.
      */
     public String getDisplayName(String id) {
 	return getDisplayName(id, Locale.getDefault());
     }

     /**
      * Given a visible id, return the display name in the requested locale.
      * If there is no directly supported id corresponding to this id, return
      * null.
      */
     public String getDisplayName(String id, Locale locale) {
 	Map m = getVisibleIDMap();
 	Factory f = (Factory)m.get(id);
 	return f != null ? f.getDisplayName(id, locale) : null;
     }

     /**
      * Convenience override of getDisplayNames(Locale) that uses the
      * current default Locale.
      */
     public Map getDisplayNames() {
 	return getDisplayNames(Locale.getDefault());
     }

     /**
      * Return a snapshot of the mapping from display names to visible
      * IDs for this service.  This set will not change as factories
      * are added or removed, but the supported ids will, so there is
      * no guarantee that all and only the ids in the returned map will
      * be visible and supported by the service in subsequent calls,
      * nor is there any guarantee that the current display names match
      * those in the set.
      */
     public Map getDisplayNames(Locale locale) {
         Map dncache = null;
 	LocaleRef ref = dnref;
         if (ref != null) {
             dncache = ref.get(locale);
         }
         while (dncache == null) {
 	    synchronized (this) {
 		if (ref == dnref || dnref == null) {
 		    dncache = new TreeMap(String.CASE_INSENSITIVE_ORDER);
 		    //dncache = new TreeMap(/* locale-specific collator */);

 		    Map m = getVisibleIDMap();
 		    Iterator ei = m.entrySet().iterator();
 		    while (ei.hasNext()) {
 			Entry e = (Entry)ei.next();
 			String id = (String)e.getKey();
 			Factory f = (Factory)e.getValue();
 			dncache.put(f.getDisplayName(id, locale), id);
 		    }

 		    dncache = Collections.unmodifiableMap(dncache);
 		    dnref = new LocaleRef(dncache, locale);
 		} else {
 		    ref = dnref;
 		    dncache = ref.get(locale);
 		}
 	    }
         }

         return dncache;
     }
     // we define a class so we get atomic simultaneous access to both the
     // locale and corresponding map
     private static class LocaleRef {
 	Locale locale;
 	SoftReference ref;

 	LocaleRef(Map dnCache, Locale locale) {
 	    this.locale = locale;
 	    this.ref = new SoftReference(dnCache);
 	}

 	Map get(Locale locale) {
 	    if (this.locale.equals(locale)) {
 		return (Map)ref.get();
 	    }
 	    return null;
 	}
     }
     private LocaleRef dnref;

     /**
      * Return a snapshot of the currently registered factories.  There
      * is no guarantee that the list will still match the current
      * factory list of the service subsequent to this call.
      */
     public final List factories() {
 	try {
 	    factoryLock.acquireRead();
 	    return new ArrayList(factories);
 	}
 	finally{
 	    factoryLock.releaseRead();
 	}
     }

     /**
      * A convenience override of registerObject(Object, String, boolean)
      * that defaults visible to true.
      */
     public Factory registerObject(Object obj, String id) {
         return registerObject(obj, id, true);
     }

     /**
      * Register an object with the provided id.  The id will be
      * canonicalized.  The canonicalized ID will be returned by
      * getVisibleIDs if visible is true.
      */
     public Factory registerObject(Object obj, String id, boolean visible) {
 	id = createKey(id).canonicalID();
 	return registerFactory(new SimpleFactory(obj, id, visible));
     }

     /**
      * Register a Factory.  Returns the factory if the service accepts
      * the factory, otherwise returns null.  The default implementation
      * accepts all factories.
      */
     public final Factory registerFactory(Factory factory) {
         if (factory == null) {
             throw new NullPointerException();
         }
 	try {
 	    factoryLock.acquireWrite();
 	    factories.add(0, factory);
 	    clearCaches();
 	}
 	finally {
 	    factoryLock.releaseWrite();
 	}
 	notifyChanged();
 	return factory;
     }

     /**
      * Unregister a factory.  The first matching registered factory will
      * be removed from the list.  Returns true if a matching factory was
      * removed.
      */
     public final boolean unregisterFactory(Factory factory) {
 	if (factory == null) {
 	    throw new NullPointerException();
 	}

 	boolean result = false;
 	try {
 	    factoryLock.acquireWrite();
 	    if (factories.remove(factory)) {
 		result = true;
 		clearCaches();
 	    }
 	}
 	finally {
 	    factoryLock.releaseWrite();
 	}

 	if (result) {
 	    notifyChanged();
 	}
 	return result;
     }

     /**
      * Reset the service to the default factories.  The factory
      * lock is acquired and then reInitializeFactories is called.
      */
     public final void reset() {
 	try {
 	    factoryLock.acquireWrite();
 	    reInitializeFactories();
 	    clearCaches();
 	}
 	finally {
 	    factoryLock.releaseWrite();
 	}
 	notifyChanged();
     }

     /**
      * Reinitialize the factory list to its default state.  By default
      * this clears the list.  Subclasses can override to provide other
      * default initialization of the factory list.  Subclasses must
      * not call this method directly, as it must only be called while
      * holding write access to the factory list.
      */
     protected void reInitializeFactories() {
 	factories.clear();
     }

     /**
      * Create a key from an id.  This creates a Key instance.
      * Subclasses can override to define more useful keys appropriate
      * to the factories they accept.
      */
     protected Key createKey(String id) {
         return new Key(id);
     }

     /**
      * Clear caches maintained by this service.  Subclasses can
      * override if they implement additional that need to be cleared
      * when the service changes. Subclasses should generally not call
      * this method directly, as it must only be called while
      * synchronized on this.
      */
     protected void clearCaches() {
 	// we don't synchronize on these because methods that use them
 	// copy before use, and check for changes if they modify the
 	// caches.
 	cacheref = null;
 	idref = null;
 	dnref = null;
     }

     /**
      * Clears only the service cache.
      * This can be called by subclasses when a change affects the service
      * cache but not the id caches, e.g., when the default locale changes
      * the resolution of ids changes, but not the visible ids themselves.
      */
     protected void clearServiceCache() {
 	cacheref = null;
     }

     /**
      * ServiceListener is the listener that ICUService provides by default.
      * ICUService will notifiy this listener when factories are added to
      * or removed from the service.  Subclasses can provide
      * different listener interfaces that extend EventListener, and modify
      * acceptsListener and notifyListener as appropriate.
      */
     public static interface ServiceListener extends EventListener {
 	public void serviceChanged(ICUService service);
     }

     /**
      * Return true if the listener is accepted; by default this
      * requires a ServiceListener.  Subclasses can override to accept
      * different listeners.
      */
     protected boolean acceptsListener(EventListener l) {
 	return l instanceof ServiceListener;
     }

     /**
      * Notify the listener, which by default is a ServiceListener.
      * Subclasses can override to use a different listener.
      */
     protected void notifyListener(EventListener l) {
 	((ServiceListener)l).serviceChanged(this);
     }

     /**
      * Return a string describing the statistics for this service.
      * This also resets the statistics. Used for debugging purposes.
      */
     public String stats() {
 	ICURWLock.Stats stats = factoryLock.resetStats();
 	if (stats != null) {
 	    return stats.toString();
 	}
 	return "no stats";
     }
 }
	/**
	*******************************************************************************
	* Copyright (C) 2001-2002, International Business Machines Corporation and *
	* others. All Rights Reserved. *
	*******************************************************************************
	*
	* $Source: /xsrl/Nsvn/icu/icu4j/src/com/ibm/icu/impl/ICUService.java,v $
	* $Date: 2002/08/13 23:40:52 $
	* $Revision: 1.7 $
	*
	*******************************************************************************
	*/
	package com.ibm.icu.impl;

	import java.lang.ref.SoftReference;
	import java.lang.reflect.InvocationTargetException;
	import java.lang.reflect.Method;
	import java.util.ArrayList;
	import java.util.Collections;
	import java.util.EventListener;
	import java.util.HashMap;
	import java.util.HashSet;
	import java.util.Iterator;
	import java.util.List;
	import java.util.ListIterator;
	import java.util.Locale;
	import java.util.Map;
	import java.util.Map.Entry;
	import java.util.Set;
	import java.util.TreeMap;

	/**
	* <p>A Service provides access to service objects that implement a
	* particular service, e.g. transliterators. Users provide a String
	* id (for example, a locale string) to the service, and get back an
	* object for that id. Service objects can be any kind of object.
	* The service object is cached and returned for later queries, so
	* generally it should not be mutable, or the caller should clone the
	* object before modifying it.</p>
	*
	* <p>Services 'canonicalize' the query id and use the canonical id
	* to query for the service. The service also defines a mechanism
	* to 'fallback' the id multiple times. Clients can optionally
	* request the actual id that was matched by a query when they
	* use an id to retrieve a service object.</p>
	*
	* <p>Service objects are instantiated by Factory objects registered with
	* the service. The service queries each Factory in turn, from most recently
	* registered to earliest registered, until one returns a service object.
	* If none responds with a service object, a fallback id is generated,
	* and the process repeats until a service object is returned or until
	* the id has no further fallbacks.</p>
	*
	* <p>Factories can be dynamically registered and unregistered with the
	* service. When registered, a Factory is installed at the head of
	* the factory list, and so gets 'first crack' at any keys or fallback
	* keys. When unregistered, it is removed from the service and can no
	* longer be located through it. Service objects generated by this
	* factory and held by the client are unaffected.</p>
	*
	* <p>Internally, ICUService uses Keys to query factories and perform
	* fallback. The Key defines the canonical form of the id, and
	* implements the fallback strategy. Custom Keys can be defined that
	* parse complex IDs into components that Factories can more easily
	* use. The Key can cache the results of this parsing to save
	* repeated effort.</p>
	*
	* <p>ICUService implements ICUNotifier, so that clients can register
	* to receive notification when factories are added or removed from
	* the service. ICUService provides a default EventListener subinterface,
	* ServiceListener, which can be registered with the service. When
	* the service changes, the ServiceListener's serviceChanged method
	* is called, with the service as the only argument.</p>
	*
	* <p>The ICUService API is both rich and generic, and it is expected
	* that most implementations will statically 'wrap' ICUService to
	* present a more appropriate API-- for example, to declare the type
	* of the objects returned from get, to limit the factories that can
	* be registered with the service, or to define their own listener
	* interface with a custom callback method. They might also customize
	* ICUService by overriding it, for example, to customize the Key and
	* fallback strategy. ICULocaleService is a customized service that
	* uses Locale names as ids and uses Keys that implement the standard
	* resource bundle fallback strategy.<p>
	*/
	public class ICUService extends ICUNotifier {
	/**
	* Access to factories is protected by a read-write lock. This is
	* to allow multiple threads to read concurrently, but keep
	* changes to the factory list atomic with respect to all readers.
	*/
	private final ICURWLock factoryLock = new ICURWLock();

	/**
	* All the factories registered with this service.
	*/
	private final List factories = new ArrayList();

	/**
	* Keys define how ids are canonicalized, and determine the
	* fallback strategy used when querying the factories. The default
	* key just takes as its canonicalID the id assigned to it when it
	* is constructed, and has no fallbacks.
	*/
	public static class Key {
	private final String id;

	/**
	* Construct a key from an id.
	*/
	public Key(String id) {
	this.id = id;
	}

	/**
	* Return the original ID.
	*/
	public final String id() {
	return id;
	}

	/**
	* Return the canonical version of the original ID. This implementation
	* returns the original ID unchanged.
	*/
	public String canonicalID() {
	return id;
	}

	/**
	* Return the (canonical) current ID. This implementation returns the
	* canonical ID.
	*/
	public String currentID() {
	return canonicalID();
	}

	/**
	* If the key has a fallback, modify the key and return true,
	* otherwise return false. The current ID will change if there
	* is a fallback. No currentIDs should be repeated, and fallback
	* must eventually return false. This implmentation has no fallbacks
	* and always returns false.
	*/
	public boolean fallback() {
	return false;
	}
	}

	/**
	* Factories generate the service objects maintained by the
	* service. A factory generates a service object from a key,
	* updates id->factory mappings, and returns the display name for
	* a supported id.
	*/
	public static interface Factory {
	/**
	* Create a service object from the key, if this factory
	* supports the key. Otherwise, return null.
	*/
	public Object create(Key key);

	/**
	* Add IDs understood by this factory to the result map, with
	* this factory as the value. If this factory hides IDs
	* currently in result, it should remove or reset the mappings
	* for those IDs.
	*/
	public void updateVisibleIDs(Map result);

	/**
	* Return the display name for this id in the provided locale.
	* If the id is not visible or not defined by the factory,
	* return null.
	*/
	public String getDisplayName(String id, Locale locale);
	}

	/**
	* A default implementation of factory. This provides default
	* implementations for subclasses, and implements a singleton
	* factory that matches a single id and returns a single
	* (possibly deferred-initialized) instance. If visible is
	* true, updates the map passed to updateVisibleIDs with a
	* mapping from id to itself.
	*/
	public static class SimpleFactory implements Factory {
	protected Object instance;
	protected String id;
	protected boolean visible;

	/**
	* Convenience constructor that calls SimpleFactory(Object, String, boolean)
	* with visible true.
	*/
	public SimpleFactory(Object instance, String id) {
	this(instance, id, true);
	}

	/**
	* Construct a simple factory that maps a single id to a single
	* service instance. If visible is true, the id will be visible.
	* Neither the instance nor the id can be null.
	*/
	public SimpleFactory(Object instance, String id, boolean visible) {
	if (instance == null \|\| id == null) {
	throw new IllegalArgumentException("Instance or id is null");
	}
	this.instance = instance;
	this.id = id;
	this.visible = visible;
	}

	/**
	* Return the service instance if id equals the key's currentID.
	*/
	public Object create(Key key) {
	if (id.equals(key.currentID())) {
	return instance;
	}
	return null;
	}

	/**
	* If visible, adds a mapping from id -> this to the result.
	*/
	public void updateVisibleIDs(Map result) {
	if (visible) result.put(id, this);
	}

	/**
	* If id equals this.id, returns id regardless of locale, otherwise
	* returns null.
	*/
	public String getDisplayName(String id, Locale locale) {
	return (visible && id.equals(this.id)) ? id : null;
	}
	}

	/**
	* Convenience override for get(String, String[]).
	*/
	public Object get(String id) {
	return get(id, null);
	}

	/**
	* <p>Given an id, return a service object, and, if actualIDReturn
	* is not null, the actual id under which it was found in the
	* first element of actualIDReturn. If no service object matches
	* this id, return null, and leave actualIDReturn unchanged.</p>
	*
	* <p>This tries each registered factory in order, and if none can
	* generate a service object for the key, repeats the process with
	* each fallback of the key until one returns a service object, or
	* the key has no fallback.</p>
	*/
	public Object get(String id, String[] actualIDReturn) {
	if (id == null) {
	throw new NullPointerException();
	}
	if (factories.size() == 0) {
	return null;
	}

	CacheEntry result = null;
	Key key = createKey(id);
	if (key != null) {
	try {
	// The factory list can't be modified until we're done,
	// otherwise we might update the cache with an invalid result.
	// The cache has to stay in synch with the factory list.
	factoryLock.acquireRead();

	Map cache = null;
	SoftReference cref = cacheref; // copy so we don't need to sync on this
	if (cref != null) {
	cache = (Map)cref.get();
	}
	if (cache == null) {
	// synchronized since additions and queries on the cache must be atomic
	// they can be interleaved, though
	cache = Collections.synchronizedMap(new HashMap());
	cref = new SoftReference(cache);
	}

	String currentID = null;
	ArrayList cacheIDList = null;
	boolean putInCache = false;
	outer:
	do {
	currentID = key.currentID();

	result = (CacheEntry)cache.get(currentID);
	if (result != null) {
	break outer;
	}

	// first test of cache failed, so we'll have to update
	// the cache if we eventually succeed.
	putInCache = true;

	Iterator fi = factories.iterator();
	while (fi.hasNext()) {
	Object service = ((Factory)fi.next()).create(key);
	if (service != null) {
	result = new CacheEntry(currentID, service);
	break outer;
	}
	}

	// prepare to load the cache with all additional ids that
	// will resolve to result, assuming we'll succeed. We
	// don't want to keep querying on an id that's going to
	// fallback to the one that succeeded, we want to hit the
	// cache the first time next goaround.
	if (cacheIDList == null) {
	cacheIDList = new ArrayList(5);
	}
	cacheIDList.add(currentID);

	} while (key.fallback());

	if (result != null) {
	if (putInCache) {
	cache.put(result.actualID, result);
	if (cacheIDList != null) {
	Iterator iter = cacheIDList.iterator();
	while (iter.hasNext()) {
	cache.put((String)iter.next(), result);
	}
	}
	// Atomic update. We held the read lock all this time
	// so we know our cache is consistent with the factory list.
	// We might stomp over a cache that some other thread
	// rebuilt, but that's the breaks. They're both good.
	cacheref = cref;
	}

	if (actualIDReturn != null) {
	actualIDReturn[0] = result.actualID;
	}

	return result.service;
	}
	}
	finally {
	factoryLock.releaseRead();
	}
	}

	return null;
	}
	private SoftReference cacheref;

	// Record the actual id for this service in the cache, so we can return it
	// even if we succeed later with a different id.
	private static final class CacheEntry {
	String actualID;
	Object service;
	CacheEntry(String actualID, Object service) {
	this.actualID = actualID;
	this.service = service;
	}
	}

	/**
	* Return a snapshot of the visible IDs for this service. This
	* set will not change as Factories are added or removed, but the
	* supported ids will, so there is no guarantee that all and only
	* the ids in the returned set are visible and supported by the
	* service in subsequent calls.
	*/
	public Set getVisibleIDs() {
	return getVisibleIDMap().keySet();
	}

	/**
	* Return a map from visible ids to factories.
	*/
	private Map getVisibleIDMap() {
	Map idcache = null;
	SoftReference ref = idref;
	if (ref != null) {
	idcache = (Map)ref.get();
	}
	while (idcache == null) {
	synchronized (this) { // or idref-only lock?
	if (ref == idref \|\| idref == null) {
	// no other thread updated idref before we got the lock, so
	// grab the factory list and update it ourselves
	try {
	factoryLock.acquireRead();

	idcache = new TreeMap(String.CASE_INSENSITIVE_ORDER);

	ListIterator lIter = factories.listIterator(factories.size());
	while (lIter.hasPrevious()) {
	Factory f = (Factory)lIter.previous();
	f.updateVisibleIDs(idcache);
	}
	idcache = Collections.unmodifiableMap(idcache);
	idref = new SoftReference(idcache);
	}
	finally {
	factoryLock.releaseRead();
	}
	} else {
	// another thread updated idref, but gc may have stepped
	// in and undone its work, leaving idcache null. If so,
	// retry.
	ref = idref;
	idcache = (Map)ref.get();
	}
	}
	}

	return idcache;
	}
	private SoftReference idref;

	/**
	* Convenience override for getDisplayName(String, Locale) that
	* uses the current default locale.
	*/
	public String getDisplayName(String id) {
	return getDisplayName(id, Locale.getDefault());
	}

	/**
	* Given a visible id, return the display name in the requested locale.
	* If there is no directly supported id corresponding to this id, return
	* null.
	*/
	public String getDisplayName(String id, Locale locale) {
	Map m = getVisibleIDMap();
	Factory f = (Factory)m.get(id);
	return f != null ? f.getDisplayName(id, locale) : null;
	}

	/**
	* Convenience override of getDisplayNames(Locale) that uses the
	* current default Locale.
	*/
	public Map getDisplayNames() {
	return getDisplayNames(Locale.getDefault());
	}

	/**
	* Return a snapshot of the mapping from display names to visible
	* IDs for this service. This set will not change as factories
	* are added or removed, but the supported ids will, so there is
	* no guarantee that all and only the ids in the returned map will
	* be visible and supported by the service in subsequent calls,
	* nor is there any guarantee that the current display names match
	* those in the set.
	*/
	public Map getDisplayNames(Locale locale) {
	Map dncache = null;
	LocaleRef ref = dnref;
	if (ref != null) {
	dncache = ref.get(locale);
	}
	while (dncache == null) {
	synchronized (this) {
	if (ref == dnref \|\| dnref == null) {
	dncache = new TreeMap(String.CASE_INSENSITIVE_ORDER);
	//dncache = new TreeMap(/* locale-specific collator */);

	Map m = getVisibleIDMap();
	Iterator ei = m.entrySet().iterator();
	while (ei.hasNext()) {
	Entry e = (Entry)ei.next();
	String id = (String)e.getKey();
	Factory f = (Factory)e.getValue();
	dncache.put(f.getDisplayName(id, locale), id);
	}

	dncache = Collections.unmodifiableMap(dncache);
	dnref = new LocaleRef(dncache, locale);
	} else {
	ref = dnref;
	dncache = ref.get(locale);
	}
	}
	}

	return dncache;
	}
	// we define a class so we get atomic simultaneous access to both the
	// locale and corresponding map
	private static class LocaleRef {
	Locale locale;
	SoftReference ref;

	LocaleRef(Map dnCache, Locale locale) {
	this.locale = locale;
	this.ref = new SoftReference(dnCache);
	}

	Map get(Locale locale) {
	if (this.locale.equals(locale)) {
	return (Map)ref.get();
	}
	return null;
	}
	}
	private LocaleRef dnref;

	/**
	* Return a snapshot of the currently registered factories. There
	* is no guarantee that the list will still match the current
	* factory list of the service subsequent to this call.
	*/
	public final List factories() {
	try {
	factoryLock.acquireRead();
	return new ArrayList(factories);
	}
	finally{
	factoryLock.releaseRead();
	}
	}

	/**
	* A convenience override of registerObject(Object, String, boolean)
	* that defaults visible to true.
	*/
	public Factory registerObject(Object obj, String id) {
	return registerObject(obj, id, true);
	}

	/**
	* Register an object with the provided id. The id will be
	* canonicalized. The canonicalized ID will be returned by
	* getVisibleIDs if visible is true.
	*/
	public Factory registerObject(Object obj, String id, boolean visible) {
	id = createKey(id).canonicalID();
	return registerFactory(new SimpleFactory(obj, id, visible));
	}

	/**
	* Register a Factory. Returns the factory if the service accepts
	* the factory, otherwise returns null. The default implementation
	* accepts all factories.
	*/
	public final Factory registerFactory(Factory factory) {
	if (factory == null) {
	throw new NullPointerException();
	}
	try {
	factoryLock.acquireWrite();
	factories.add(0, factory);
	clearCaches();
	}
	finally {
	factoryLock.releaseWrite();
	}
	notifyChanged();
	return factory;
	}

	/**
	* Unregister a factory. The first matching registered factory will
	* be removed from the list. Returns true if a matching factory was
	* removed.
	*/
	public final boolean unregisterFactory(Factory factory) {
	if (factory == null) {
	throw new NullPointerException();
	}

	boolean result = false;
	try {
	factoryLock.acquireWrite();
	if (factories.remove(factory)) {
	result = true;
	clearCaches();
	}
	}
	finally {
	factoryLock.releaseWrite();
	}

	if (result) {
	notifyChanged();
	}
	return result;
	}

	/**
	* Reset the service to the default factories. The factory
	* lock is acquired and then reInitializeFactories is called.
	*/
	public final void reset() {
	try {
	factoryLock.acquireWrite();
	reInitializeFactories();
	clearCaches();
	}
	finally {
	factoryLock.releaseWrite();
	}
	notifyChanged();
	}

	/**
	* Reinitialize the factory list to its default state. By default
	* this clears the list. Subclasses can override to provide other
	* default initialization of the factory list. Subclasses must
	* not call this method directly, as it must only be called while
	* holding write access to the factory list.
	*/
	protected void reInitializeFactories() {
	factories.clear();
	}

	/**
	* Create a key from an id. This creates a Key instance.
	* Subclasses can override to define more useful keys appropriate
	* to the factories they accept.
	*/
	protected Key createKey(String id) {
	return new Key(id);
	}

	/**
	* Clear caches maintained by this service. Subclasses can
	* override if they implement additional that need to be cleared
	* when the service changes. Subclasses should generally not call
	* this method directly, as it must only be called while
	* synchronized on this.
	*/
	protected void clearCaches() {
	// we don't synchronize on these because methods that use them
	// copy before use, and check for changes if they modify the
	// caches.
	cacheref = null;
	idref = null;
	dnref = null;
	}

	/**
	* Clears only the service cache.
	* This can be called by subclasses when a change affects the service
	* cache but not the id caches, e.g., when the default locale changes
	* the resolution of ids changes, but not the visible ids themselves.
	*/
	protected void clearServiceCache() {
	cacheref = null;
	}

	/**
	* ServiceListener is the listener that ICUService provides by default.
	* ICUService will notifiy this listener when factories are added to
	* or removed from the service. Subclasses can provide
	* different listener interfaces that extend EventListener, and modify
	* acceptsListener and notifyListener as appropriate.
	*/
	public static interface ServiceListener extends EventListener {
	public void serviceChanged(ICUService service);
	}

	/**
	* Return true if the listener is accepted; by default this
	* requires a ServiceListener. Subclasses can override to accept
	* different listeners.
	*/
	protected boolean acceptsListener(EventListener l) {
	return l instanceof ServiceListener;
	}

	/**
	* Notify the listener, which by default is a ServiceListener.
	* Subclasses can override to use a different listener.
	*/
	protected void notifyListener(EventListener l) {
	((ServiceListener)l).serviceChanged(this);
	}

	/**
	* Return a string describing the statistics for this service.
	* This also resets the statistics. Used for debugging purposes.
	*/
	public String stats() {
	ICURWLock.Stats stats = factoryLock.resetStats();
	if (stats != null) {
	return stats.toString();
	}
	return "no stats";
	}
	}