Top Description Inners Fields Constructors Methods
com.ibm.icu.impl

public Class ICUService

extends ICUNotifier
Class Inheritance
Known Direct Subclasses
com.ibm.icu.impl.ICULocaleService
Imports
java.util.ArrayList, .Collections, .Comparator, .EventListener, .HashMap, .HashSet, .Iterator, .List, .ListIterator, .Map, .Map.Entry, .Set, .SortedMap, .TreeMap, java.util.concurrent.ConcurrentHashMap, com.ibm.icu.util.ULocale, .ULocale.Category

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.

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.

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.

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.

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. ICUService provides convenience APIs that take Strings and generate default Keys for use in querying.

ICUService provides API to get the list of ids publicly supported by the service (although queries aren't restricted to this list). This list contains only 'simple' IDs, and not fully unique ids. Factories are associated with each simple ID and the responsible factory can also return a human-readable localized version of the simple ID, for use in user interfaces. ICUService can also provide a sorted collection of the all the localized visible ids.

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.

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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
public static interface
ICUService.Factory

Factories generate the service objects maintained by the service.

public static class
ICUService.Key

Keys are used to communicate with factories to generate an instance of the service.

private static class
public static interface
ICUService.ServiceListener

ServiceListener is the listener that ICUService provides by default.

public static class
ICUService.SimpleFactory

A default implementation of factory.

Field Summary

Modifier and TypeField and Description
private Map<String, ICUService.CacheEntry>
private static final boolean
private int
defaultSize

Record the default number of factories for this service.

private ICUService.LocaleRef
private final List<ICUService.Factory>
factories

All the factories registered with this service.

private final ICURWLock
factoryLock

Access to factories is protected by a read-write lock.

private Map<String, ICUService.Factory>
protected final String
name

Name used for debugging.

Constructor Summary

AccessConstructor and Description
public
ICUService()

Constructor.

public
ICUService(String name)

Construct with a name (useful for debugging).

Method Summary

Modifier and TypeMethod and Description
protected boolean
acceptsListener(EventListener l)

Implements abstract com.ibm.icu.impl.ICUNotifier.acceptsListener.

Return true if the listener is accepted; by default this requires a ServiceListener.
protected void
clearCaches()

Clear caches maintained by this service.

protected void
clearServiceCache()

Clears only the service cache.

public ICUService.Key
createKey(String id)

Create a key from an id. This creates a Key instance.

public final List<ICUService.Factory>
factories()

Return a snapshot of the currently registered factories.

public Object
get(String descriptor)

Convenience override for get(String, String[]).

public Object
get(String descriptor, String[] actualReturn)

Convenience override for get(Key, String[]).

public String
getDisplayName(String id)

Convenience override for getDisplayName(String, ULocale) that uses the current default locale.

public String
getDisplayName(String id, ULocale locale)

Given a visible id, return the display name in the requested locale.

public SortedMap<String, String>
getDisplayNames()

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses the current default Locale as the locale, null as the comparator, and null for the matchID.

public SortedMap<String, String>
getDisplayNames(ULocale locale)

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator, and null for the matchID.

public SortedMap<String, String>
getDisplayNames(ULocale locale, Comparator<Object> com)

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the matchID, thus returning all display names.

public SortedMap<String, String>
getDisplayNames(ULocale locale, String matchID)

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator.

public SortedMap<String, String>
getDisplayNames(ULocale locale, Comparator<Object> com, String matchID)

Return a snapshot of the mapping from display names to visible IDs for this service.

public Object
getKey(ICUService.Key key)

Convenience override for get(Key, String[]).

public Object
getKey(ICUService.Key key, String[] actualReturn)

Given a key, return a service object, and, if actualReturn is not null, the descriptor with which it was found in the first element of actualReturn.

public Object
getKey(ICUService.Key key, String[] actualReturn, ICUService.Factory factory)

public String
getName()

Return the name of this service.

private Map<String, ICUService.Factory>
getVisibleIDMap()

Return a map from visible ids to factories.

public Set<String>
getVisibleIDs()

Convenience override for getVisibleIDs(String) that passes null as the fallback, thus returning all visible IDs.

public Set<String>
getVisibleIDs(String matchID)

Return a snapshot of the visible IDs for this service.

protected Object
handleDefault(ICUService.Key key, String[] actualIDReturn)

Default handler for this service if no factory in the list handled the key.

public boolean
isDefault()

Return true if the service is in its default state.

protected void
markDefault()

Set the default size to the current number of registered factories.

protected void
notifyListener(EventListener l)

Implements abstract com.ibm.icu.impl.ICUNotifier.notifyListener.

Notify the listener, which by default is a ServiceListener.
public final ICUService.Factory
registerFactory(ICUService.Factory factory)

Register a Factory.

public ICUService.Factory
registerObject(Object obj, String id)

A convenience override of registerObject(Object, String, boolean) that defaults visible to true.

public ICUService.Factory
registerObject(Object obj, String id, boolean visible)

Register an object with the provided id. The id will be canonicalized.

protected void
reInitializeFactories()

Reinitialize the factory list to its default state.

public final void
reset()

Reset the service to the default factories.

public String
stats()

When the statistics for this service is already enabled, return the log and resets he statistics.

public String
toString()

Overrides java.lang.Object.toString.

Returns the result of super.toString, appending the name in curly braces.
public final boolean
unregisterFactory(ICUService.Factory factory)

Unregister a factory.

Inherited from com.ibm.icu.impl.ICUNotifier:
addListenernotifyChangedremoveListener

Field Detail

cacheback to summary
private Map<String, ICUService.CacheEntry> cache
DEBUGback to summary
private static final boolean DEBUG
defaultSizeback to summary
private int defaultSize

Record the default number of factories for this service. Can be set by markDefault.

dnrefback to summary
private ICUService.LocaleRef dnref
factoriesback to summary
private final List<ICUService.Factory> factories

All the factories registered with this service.

factoryLockback to summary
private final ICURWLock factoryLock

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.

idcacheback to summary
private Map<String, ICUService.Factory> idcache
nameback to summary
protected final String name

Name used for debugging.

Constructor Detail

ICUServiceback to summary
public ICUService()

Constructor.

ICUServiceback to summary
public ICUService(String name)

Construct with a name (useful for debugging).

Method Detail

acceptsListenerback to summary
protected boolean acceptsListener(EventListener l)

Implements abstract com.ibm.icu.impl.ICUNotifier.acceptsListener.

Return true if the listener is accepted; by default this requires a ServiceListener. Subclasses can override to accept different listeners.

Annotations
@Override
clearCachesback to summary
protected void clearCaches()

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.

clearServiceCacheback to summary
protected void clearServiceCache()

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.

createKeyback to summary
public ICUService.Key createKey(String id)

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. If id is null, returns null.

factoriesback to summary
public final List<ICUService.Factory> factories()

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.

getback to summary
public Object get(String descriptor)

Convenience override for get(String, String[]). This uses createKey to create a key for the provided descriptor.

getback to summary
public Object get(String descriptor, String[] actualReturn)

Convenience override for get(Key, String[]). This uses createKey to create a key from the provided descriptor.

getDisplayNameback to summary
public String getDisplayName(String id)

Convenience override for getDisplayName(String, ULocale) that uses the current default locale.

getDisplayNameback to summary
public String getDisplayName(String id, ULocale locale)

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.

getDisplayNamesback to summary
public SortedMap<String, String> getDisplayNames()

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses the current default Locale as the locale, null as the comparator, and null for the matchID.

getDisplayNamesback to summary
public SortedMap<String, String> getDisplayNames(ULocale locale)

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator, and null for the matchID.

getDisplayNamesback to summary
public SortedMap<String, String> getDisplayNames(ULocale locale, Comparator<Object> com)

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the matchID, thus returning all display names.

getDisplayNamesback to summary
public SortedMap<String, String> getDisplayNames(ULocale locale, String matchID)

Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator.

getDisplayNamesback to summary
public SortedMap<String, String> getDisplayNames(ULocale locale, Comparator<Object> com, String matchID)

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. The display names are sorted based on the comparator provided.

getKeyback to summary
public Object getKey(ICUService.Key key)

Convenience override for get(Key, String[]).

getKeyback to summary
public Object getKey(ICUService.Key key, String[] actualReturn)

Given a key, return a service object, and, if actualReturn is not null, the descriptor with which it was found in the first element of actualReturn. If no service object matches this key, return null, and leave actualReturn unchanged.

This queries the cache using the key's descriptor, and if no object in the cache matches it, tries the key on each registered factory, in order. If none generates a service object for the key, repeats the process with each fallback of the key, until either one returns a service object, or the key has no fallback.

If key is null, just returns null.

getKeyback to summary
public Object getKey(ICUService.Key key, String[] actualReturn, ICUService.Factory factory)
getNameback to summary
public String getName()

Return the name of this service. This will be the empty string if none was assigned.

getVisibleIDMapback to summary
private Map<String, ICUService.Factory> getVisibleIDMap()

Return a map from visible ids to factories.

getVisibleIDsback to summary
public Set<String> getVisibleIDs()

Convenience override for getVisibleIDs(String) that passes null as the fallback, thus returning all visible IDs.

getVisibleIDsback to summary
public Set<String> getVisibleIDs(String matchID)

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.

matchID is passed to createKey to create a key. If the key is not null, it is used to filter out ids that don't have the key as a fallback.

handleDefaultback to summary
protected Object handleDefault(ICUService.Key key, String[] actualIDReturn)

Default handler for this service if no factory in the list handled the key.

isDefaultback to summary
public boolean isDefault()

Return true if the service is in its default state. The default implementation returns true if there are no factories registered.

markDefaultback to summary
protected void markDefault()

Set the default size to the current number of registered factories. Used by subclasses to customize the behavior of isDefault.

notifyListenerback to summary
protected void notifyListener(EventListener l)

Implements abstract com.ibm.icu.impl.ICUNotifier.notifyListener.

Notify the listener, which by default is a ServiceListener. Subclasses can override to use a different listener.

Annotations
@Override
registerFactoryback to summary
public final ICUService.Factory registerFactory(ICUService.Factory factory)

Register a Factory. Returns the factory if the service accepts the factory, otherwise returns null. The default implementation accepts all factories.

registerObjectback to summary
public ICUService.Factory registerObject(Object obj, String id)

A convenience override of registerObject(Object, String, boolean) that defaults visible to true.

registerObjectback to summary
public ICUService.Factory registerObject(Object obj, String id, boolean visible)

Register an object with the provided id. The id will be canonicalized. The canonicalized ID will be returned by getVisibleIDs if visible is true.

reInitializeFactoriesback to summary
protected void reInitializeFactories()

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.

resetback to summary
public final void reset()

Reset the service to the default factories. The factory lock is acquired and then reInitializeFactories is called.

statsback to summary
public String stats()

When the statistics for this service is already enabled, return the log and resets he statistics. When the statistics is not enabled, this method enable the statistics. Used for debugging purposes.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the result of super.toString, appending the name in curly braces.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations
@Override
unregisterFactoryback to summary
public final boolean unregisterFactory(ICUService.Factory factory)

Unregister a factory. The first matching registered factory will be removed from the list. Returns true if a matching factory was removed.

com.ibm.icu.impl back to summary

private final Class ICUService.CacheEntry

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
pack-priv final String
pack-priv final Object

Constructor Summary

AccessConstructor and Description
pack-priv
CacheEntry(String actualDescriptor, Object service)

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

actualDescriptorback to summary
pack-priv final String actualDescriptor
serviceback to summary
pack-priv final Object service

Constructor Detail

CacheEntryback to summary
pack-priv CacheEntry(String actualDescriptor, Object service)
com.ibm.icu.impl back to summary

public Interface ICUService.Factory

Known Direct Implementers
com.ibm.icu.impl.ICUService.SimpleFactory, com.ibm.icu.impl.ICULocaleService.LocaleKeyFactory

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.

Method Summary

Modifier and TypeMethod and Description
public Object
create(ICUService.Key key, ICUService service)

Create a service object from the key, if this factory supports the key.

public String
getDisplayName(String id, ULocale locale)

Return the display name for this id in the provided locale.

public void
updateVisibleIDs(Map<String, ICUService.Factory> result)

Update the result IDs (not descriptors) to reflect the IDs this factory handles.

Method Detail

createback to summary
public Object create(ICUService.Key key, ICUService service)

Create a service object from the key, if this factory supports the key. Otherwise, return null.

If the factory supports the key, then it can call the service's getKey(Key, String[], Factory) method passing itself as the factory to get the object that the service would have created prior to the factory's registration with the service. This can change the key, so any information required from the key should be extracted before making such a callback.

getDisplayNameback to summary
public String getDisplayName(String id, ULocale locale)

Return the display name for this id in the provided locale. This is an localized id, not a descriptor. If the id is not visible or not defined by the factory, return null. If locale is null, return id unchanged.

updateVisibleIDsback to summary
public void updateVisibleIDs(Map<String, ICUService.Factory> result)

Update the result IDs (not descriptors) to reflect the IDs this factory handles. This function and getDisplayName are used to support ICUService.getDisplayNames. Basically, the factory has to determine which IDs it will permit to be available, and of those, which it will provide localized display names for. In most cases this reflects the IDs that the factory directly supports.

com.ibm.icu.impl back to summary

public Class ICUService.Key

extends Object
Class Inheritance
Known Direct Subclasses
com.ibm.icu.impl.ICULocaleService.LocaleKey

Keys are used to communicate with factories to generate an instance of the service. Keys define how ids are canonicalized, provide both a current id and a current descriptor to use in querying the cache and factories, and determine the fallback strategy.

Keys provide both a currentDescriptor and a currentID. The descriptor contains an optional prefix, followed by '/' and the currentID. Factories that handle complex keys, for example number format factories that generate multiple kinds of formatters for the same locale, use the descriptor to provide a fully unique identifier for the service object, while using the currentID (in this case, the locale string), as the visible IDs that can be localized.

The default implementation of Key has no fallbacks and has no custom descriptors.

Field Summary

Modifier and TypeField and Description
private final String

Constructor Summary

AccessConstructor and Description
public
Key(String id)

Construct a key from an id.

Method Summary

Modifier and TypeMethod and Description
public String
canonicalID()

Return the canonical version of the original ID. This implementation returns the original ID unchanged.

public String
currentDescriptor()

Return the current descriptor.

public String
currentID()

Return the (canonical) current ID. This implementation returns the canonical ID.

public boolean
fallback()

If the key has a fallback, modify the key and return true, otherwise return false.

public final String
id()

Return the original ID used to construct this key.

public boolean
isFallbackOf(String idToCheck)

If a key created from id would eventually fallback to match the canonical ID of this key, return true.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

idback to summary
private final String id

Constructor Detail

Keyback to summary
public Key(String id)

Construct a key from an id.

Method Detail

canonicalIDback to summary
public String canonicalID()

Return the canonical version of the original ID. This implementation returns the original ID unchanged.

currentDescriptorback to summary
public String currentDescriptor()

Return the current descriptor. This implementation returns the current ID. The current descriptor is used to fully identify an instance of the service in the cache. A factory may handle all descriptors for an ID, or just a particular descriptor. The factory can either parse the descriptor or use custom API on the key in order to instantiate the service.

currentIDback to summary
public String currentID()

Return the (canonical) current ID. This implementation returns the canonical ID.

fallbackback to summary
public boolean fallback()

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 implementation has no fallbacks and always returns false.

idback to summary
public final String id()

Return the original ID used to construct this key.

isFallbackOfback to summary
public boolean isFallbackOf(String idToCheck)

If a key created from id would eventually fallback to match the canonical ID of this key, return true.

com.ibm.icu.impl back to summary

private Class ICUService.LocaleRef

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private Comparator<Object>
private SortedMap<String, String>
private final ULocale

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
pack-priv SortedMap<String, String>
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

comback to summary
private Comparator<Object> com
dnCacheback to summary
private SortedMap<String, String> dnCache
localeback to summary
private final ULocale locale

Constructor Detail

LocaleRefback to summary
pack-priv LocaleRef(SortedMap<String, String> dnCache, ULocale locale, Comparator<Object> com)

Method Detail

getback to summary
pack-priv SortedMap<String, String> get(ULocale loc, Comparator<Object> comp)
com.ibm.icu.impl back to summary

public Interface ICUService.ServiceListener

extends EventListener

ServiceListener is the listener that ICUService provides by default. ICUService will notify 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.

Method Summary

Modifier and TypeMethod and Description
public void

Method Detail

serviceChangedback to summary
public void serviceChanged(ICUService service)
com.ibm.icu.impl back to summary

public Class ICUService.SimpleFactory

extends Object
implements Factory
Class Inheritance
All Implemented Interfaces
com.ibm.icu.impl.ICUService.Factory

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. This implements updateVisibleIDs to add a mapping from its ID to itself if visible is true, or to remove any existing mapping for its ID if visible is false.

Field Summary

Modifier and TypeField and Description
protected String
protected Object
protected boolean

Constructor Summary

AccessConstructor and Description
public
SimpleFactory(Object instance, String id)

Convenience constructor that calls SimpleFactory(Object, String, boolean) with visible true.

public
SimpleFactory(Object instance, String id, boolean visible)

Construct a simple factory that maps a single id to a single service instance.

Method Summary

Modifier and TypeMethod and Description
public Object
create(ICUService.Key key, ICUService service)

Implements com.ibm.icu.impl.ICUService.Factory.create.

Return the service instance if the factory's id is equal to the key's currentID.
public String
getDisplayName(String identifier, ULocale locale)

Implements com.ibm.icu.impl.ICUService.Factory.getDisplayName.

If this.id equals id, returns id regardless of locale, otherwise returns null.
public String
toString()

Overrides java.lang.Object.toString.

For debugging.
public void
updateVisibleIDs(Map<String, ICUService.Factory> result)

Implements com.ibm.icu.impl.ICUService.Factory.updateVisibleIDs.

If visible, adds a mapping from id -> this to the result, otherwise removes id from result.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

idback to summary
protected String id
instanceback to summary
protected Object instance
visibleback to summary
protected boolean visible

Constructor Detail

SimpleFactoryback to summary
public SimpleFactory(Object instance, String id)

Convenience constructor that calls SimpleFactory(Object, String, boolean) with visible true.

SimpleFactoryback to summary
public SimpleFactory(Object instance, String id, boolean visible)

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.

Method Detail

createback to summary
public Object create(ICUService.Key key, ICUService service)

Implements com.ibm.icu.impl.ICUService.Factory.create.

Return the service instance if the factory's id is equal to the key's currentID. Service is ignored.

Annotations
@Override
getDisplayNameback to summary
public String getDisplayName(String identifier, ULocale locale)

Implements com.ibm.icu.impl.ICUService.Factory.getDisplayName.

If this.id equals id, returns id regardless of locale, otherwise returns null. (This default implementation has no localized id information.)

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

For debugging.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations
@Override
updateVisibleIDsback to summary
public void updateVisibleIDs(Map<String, ICUService.Factory> result)

Implements com.ibm.icu.impl.ICUService.Factory.updateVisibleIDs.

If visible, adds a mapping from id -> this to the result, otherwise removes id from result.

Annotations
@Override