Class ICUService
- java.lang.Object
-
- com.ibm.icu.impl.ICUNotifier
-
- com.ibm.icu.impl.ICUService
-
- Direct Known Subclasses:
ICULocaleService
public class ICUService extends ICUNotifier
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 Class Summary
Nested Classes Modifier and Type Class Description private static class
ICUService.CacheEntry
static interface
ICUService.Factory
Factories generate the service objects maintained by the service.static class
ICUService.Key
Keys are used to communicate with factories to generate an instance of the service.private static class
ICUService.LocaleRef
static interface
ICUService.ServiceListener
ServiceListener is the listener that ICUService provides by default.static class
ICUService.SimpleFactory
A default implementation of factory.
-
Field Summary
Fields Modifier and Type Field Description private java.util.Map<java.lang.String,ICUService.CacheEntry>
cache
private static boolean
DEBUG
private int
defaultSize
Record the default number of factories for this service.private ICUService.LocaleRef
dnref
private java.util.List<ICUService.Factory>
factories
All the factories registered with this service.private ICURWLock
factoryLock
Access to factories is protected by a read-write lock.private java.util.Map<java.lang.String,ICUService.Factory>
idcache
protected java.lang.String
name
Name used for debugging.
-
Constructor Summary
Constructors Constructor Description ICUService()
Constructor.ICUService(java.lang.String name)
Construct with a name (useful for debugging).
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected boolean
acceptsListener(java.util.EventListener l)
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.ICUService.Key
createKey(java.lang.String id)
Create a key from an id.java.util.List<ICUService.Factory>
factories()
Return a snapshot of the currently registered factories.java.lang.Object
get(java.lang.String descriptor)
Convenience override for get(String, String[]).java.lang.Object
get(java.lang.String descriptor, java.lang.String[] actualReturn)
Convenience override for get(Key, String[]).java.lang.String
getDisplayName(java.lang.String id)
Convenience override for getDisplayName(String, ULocale) that uses the current default locale.java.lang.String
getDisplayName(java.lang.String id, ULocale locale)
Given a visible id, return the display name in the requested locale.java.util.SortedMap<java.lang.String,java.lang.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.java.util.SortedMap<java.lang.String,java.lang.String>
getDisplayNames(ULocale locale)
Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator, and null for the matchID.java.util.SortedMap<java.lang.String,java.lang.String>
getDisplayNames(ULocale locale, java.lang.String matchID)
Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator.java.util.SortedMap<java.lang.String,java.lang.String>
getDisplayNames(ULocale locale, java.util.Comparator<java.lang.Object> com)
Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the matchID, thus returning all display names.java.util.SortedMap<java.lang.String,java.lang.String>
getDisplayNames(ULocale locale, java.util.Comparator<java.lang.Object> com, java.lang.String matchID)
Return a snapshot of the mapping from display names to visible IDs for this service.java.lang.Object
getKey(ICUService.Key key)
Convenience override for get(Key, String[]).java.lang.Object
getKey(ICUService.Key key, java.lang.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.java.lang.Object
getKey(ICUService.Key key, java.lang.String[] actualReturn, ICUService.Factory factory)
java.lang.String
getName()
Return the name of this service.private java.util.Map<java.lang.String,ICUService.Factory>
getVisibleIDMap()
Return a map from visible ids to factories.java.util.Set<java.lang.String>
getVisibleIDs()
Convenience override for getVisibleIDs(String) that passes null as the fallback, thus returning all visible IDs.java.util.Set<java.lang.String>
getVisibleIDs(java.lang.String matchID)
Return a snapshot of the visible IDs for this service.protected java.lang.Object
handleDefault(ICUService.Key key, java.lang.String[] actualIDReturn)
Default handler for this service if no factory in the list handled the key.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(java.util.EventListener l)
Notify the listener, which by default is a ServiceListener.ICUService.Factory
registerFactory(ICUService.Factory factory)
Register a Factory.ICUService.Factory
registerObject(java.lang.Object obj, java.lang.String id)
A convenience override of registerObject(Object, String, boolean) that defaults visible to true.ICUService.Factory
registerObject(java.lang.Object obj, java.lang.String id, boolean visible)
Register an object with the provided id.protected void
reInitializeFactories()
Reinitialize the factory list to its default state.void
reset()
Reset the service to the default factories.java.lang.String
stats()
When the statistics for this service is already enabled, return the log and resets he statistics.java.lang.String
toString()
Returns the result of super.toString, appending the name in curly braces.boolean
unregisterFactory(ICUService.Factory factory)
Unregister a factory.-
Methods inherited from class com.ibm.icu.impl.ICUNotifier
addListener, notifyChanged, removeListener
-
-
-
-
Field Detail
-
name
protected final java.lang.String name
Name used for debugging.
-
DEBUG
private static final boolean DEBUG
-
factoryLock
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.
-
factories
private final java.util.List<ICUService.Factory> factories
All the factories registered with this service.
-
defaultSize
private int defaultSize
Record the default number of factories for this service. Can be set by markDefault.
-
cache
private java.util.Map<java.lang.String,ICUService.CacheEntry> cache
-
idcache
private java.util.Map<java.lang.String,ICUService.Factory> idcache
-
dnref
private ICUService.LocaleRef dnref
-
-
Method Detail
-
get
public java.lang.Object get(java.lang.String descriptor)
Convenience override for get(String, String[]). This uses createKey to create a key for the provided descriptor.
-
get
public java.lang.Object get(java.lang.String descriptor, java.lang.String[] actualReturn)
Convenience override for get(Key, String[]). This uses createKey to create a key from the provided descriptor.
-
getKey
public java.lang.Object getKey(ICUService.Key key)
Convenience override for get(Key, String[]).
-
getKey
public java.lang.Object getKey(ICUService.Key key, java.lang.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.
-
getKey
public java.lang.Object getKey(ICUService.Key key, java.lang.String[] actualReturn, ICUService.Factory factory)
-
handleDefault
protected java.lang.Object handleDefault(ICUService.Key key, java.lang.String[] actualIDReturn)
Default handler for this service if no factory in the list handled the key.
-
getVisibleIDs
public java.util.Set<java.lang.String> getVisibleIDs()
Convenience override for getVisibleIDs(String) that passes null as the fallback, thus returning all visible IDs.
-
getVisibleIDs
public java.util.Set<java.lang.String> getVisibleIDs(java.lang.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.
-
getVisibleIDMap
private java.util.Map<java.lang.String,ICUService.Factory> getVisibleIDMap()
Return a map from visible ids to factories.
-
getDisplayName
public java.lang.String getDisplayName(java.lang.String id)
Convenience override for getDisplayName(String, ULocale) that uses the current default locale.
-
getDisplayName
public java.lang.String getDisplayName(java.lang.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.
-
getDisplayNames
public java.util.SortedMap<java.lang.String,java.lang.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.
-
getDisplayNames
public java.util.SortedMap<java.lang.String,java.lang.String> getDisplayNames(ULocale locale)
Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator, and null for the matchID.
-
getDisplayNames
public java.util.SortedMap<java.lang.String,java.lang.String> getDisplayNames(ULocale locale, java.util.Comparator<java.lang.Object> com)
Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the matchID, thus returning all display names.
-
getDisplayNames
public java.util.SortedMap<java.lang.String,java.lang.String> getDisplayNames(ULocale locale, java.lang.String matchID)
Convenience override of getDisplayNames(ULocale, Comparator, String) that uses null for the comparator.
-
getDisplayNames
public java.util.SortedMap<java.lang.String,java.lang.String> getDisplayNames(ULocale locale, java.util.Comparator<java.lang.Object> com, java.lang.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.
-
factories
public final java.util.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.
-
registerObject
public ICUService.Factory registerObject(java.lang.Object obj, java.lang.String id)
A convenience override of registerObject(Object, String, boolean) that defaults visible to true.
-
registerObject
public ICUService.Factory registerObject(java.lang.Object obj, java.lang.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.
-
registerFactory
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.
-
unregisterFactory
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.
-
reset
public final void reset()
Reset the service to the default factories. The factory lock is acquired and then reInitializeFactories is called.
-
reInitializeFactories
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.
-
isDefault
public boolean isDefault()
Return true if the service is in its default state. The default implementation returns true if there are no factories registered.
-
markDefault
protected void markDefault()
Set the default size to the current number of registered factories. Used by subclasses to customize the behavior of isDefault.
-
createKey
public ICUService.Key createKey(java.lang.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.
-
clearCaches
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.
-
clearServiceCache
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.
-
acceptsListener
protected boolean acceptsListener(java.util.EventListener l)
Return true if the listener is accepted; by default this requires a ServiceListener. Subclasses can override to accept different listeners.- Specified by:
acceptsListener
in classICUNotifier
-
notifyListener
protected void notifyListener(java.util.EventListener l)
Notify the listener, which by default is a ServiceListener. Subclasses can override to use a different listener.- Specified by:
notifyListener
in classICUNotifier
-
stats
public java.lang.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.
-
getName
public java.lang.String getName()
Return the name of this service. This will be the empty string if none was assigned.
-
toString
public java.lang.String toString()
Returns the result of super.toString, appending the name in curly braces.- Overrides:
toString
in classjava.lang.Object
-
-