| java.lang.Object
 com.ibm.icu.impl.ICUNotifier
com.ibm.icu.impl.ICUService
All known Subclasses: com.ibm.icu.impl.ICULocaleService,
| ICUService | | public class ICUService extends ICUNotifier (Code) | | 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.
|
| Inner Class :public static class Key | |
| Inner Class :public static interface Factory | |
| Inner Class :public static class SimpleFactory implements Factory | |
| Inner Class :public static interface ServiceListener extends EventListener | |
| Field Summary | |
| final protected String | name
Name used for debugging. |
| Method Summary | |
| protected boolean | acceptsListener(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. | | public Key | createKey(String id)
Create a key from an id. | | final public List | 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 | 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 | getDisplayNames(ULocale locale)
Convenience override of getDisplayNames(ULocale, Comparator, String) that
uses null for the comparator, and null for the matchID. | | public SortedMap | getDisplayNames(ULocale locale, Comparator com)
Convenience override of getDisplayNames(ULocale, Comparator, String) that
uses null for the matchID, thus returning all display names. | | public SortedMap | getDisplayNames(ULocale locale, String matchID)
Convenience override of getDisplayNames(ULocale, Comparator, String) that
uses null for the comparator. | | public SortedMap | getDisplayNames(ULocale locale, Comparator com, String matchID)
Return a snapshot of the mapping from display names to visible
IDs for this service. | | public Object | getKey(Key key)
Convenience override for get(Key, String[]). | | public Object | getKey(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(Key key, String[] actualReturn, Factory factory)
| | public String | getName()
Return the name of this service. | | public Set | getVisibleIDs()
Convenience override for getVisibleIDs(String) that passes null
as the fallback, thus returning all visible IDs. | | public Set | getVisibleIDs(String matchID)
Return a snapshot of the visible IDs for this service. | | protected Object | handleDefault(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)
Notify the listener, which by default is a ServiceListener. | | protected void | reInitializeFactories()
Reinitialize the factory list to its default state. | | final public Factory | registerFactory(Factory factory)
Register a Factory. | | public Factory | registerObject(Object obj, String id)
A convenience override of registerObject(Object, String, boolean)
that defaults visible to true. | | public Factory | registerObject(Object obj, String id, boolean visible)
Register an object with the provided id. | | final public void | reset()
Reset the service to the default factories. | | public String | stats()
Return a string describing the statistics for this service.
This also resets the statistics. | | public String | toString()
Returns the result of super.toString, appending the name in curly braces. | | final public boolean | unregisterFactory(Factory factory)
Unregister a factory. |
| name | | final protected String name(Code) | | Name used for debugging.
|
| ICUService | | public ICUService()(Code) | | Constructor.
|
| ICUService | | public ICUService(String name)(Code) | | Construct with a name (useful for debugging).
|
| acceptsListener | | protected boolean acceptsListener(EventListener l)(Code) | | Return true if the listener is accepted; by default this
requires a ServiceListener. Subclasses can override to accept
different listeners.
|
| clearCaches | | protected void clearCaches()(Code) | | 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()(Code) | | 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.
|
| createKey | | public Key createKey(String id)(Code) | | 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.
|
| factories | | final public List factories()(Code) | | 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.
|
| get | | public Object get(String descriptor)(Code) | | Convenience override for get(String, String[]). This uses
createKey to create a key for the provided descriptor.
|
| get | | public Object get(String descriptor, String[] actualReturn)(Code) | | Convenience override for get(Key, String[]). This uses
createKey to create a key from the provided descriptor.
|
| getDisplayName | | public String getDisplayName(String id)(Code) | | Convenience override for getDisplayName(String, ULocale) that
uses the current default locale.
|
| getDisplayName | | public String getDisplayName(String id, ULocale locale)(Code) | | 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 SortedMap getDisplayNames()(Code) | | 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 SortedMap getDisplayNames(ULocale locale)(Code) | | Convenience override of getDisplayNames(ULocale, Comparator, String) that
uses null for the comparator, and null for the matchID.
|
| getDisplayNames | | public SortedMap getDisplayNames(ULocale locale, Comparator com)(Code) | | Convenience override of getDisplayNames(ULocale, Comparator, String) that
uses null for the matchID, thus returning all display names.
|
| getDisplayNames | | public SortedMap getDisplayNames(ULocale locale, String matchID)(Code) | | Convenience override of getDisplayNames(ULocale, Comparator, String) that
uses null for the comparator.
|
| getDisplayNames | | public SortedMap getDisplayNames(ULocale locale, Comparator com, String matchID)(Code) | | 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.
|
| getKey | | public Object getKey(Key key)(Code) | | Convenience override for get(Key, String[]).
|
| getKey | | public Object getKey(Key key, String[] actualReturn)(Code) | | 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.
|
| getName | | public String getName()(Code) | | Return the name of this service. This will be the empty string if none was assigned.
|
| getVisibleIDs | | public Set getVisibleIDs()(Code) | | Convenience override for getVisibleIDs(String) that passes null
as the fallback, thus returning all visible IDs.
|
| getVisibleIDs | | public Set getVisibleIDs(String matchID)(Code) | | 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.
|
| handleDefault | | protected Object handleDefault(Key key, String[] actualIDReturn)(Code) | | Default handler for this service if no factory in the list
handled the key.
|
| isDefault | | public boolean isDefault()(Code) | | 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()(Code) | | Set the default size to the current number of registered factories.
Used by subclasses to customize the behavior of isDefault.
|
| notifyListener | | protected void notifyListener(EventListener l)(Code) | | Notify the listener, which by default is a ServiceListener.
Subclasses can override to use a different listener.
|
| reInitializeFactories | | protected void reInitializeFactories()(Code) | | 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.
|
| registerFactory | | final public Factory registerFactory(Factory factory)(Code) | | Register a Factory. Returns the factory if the service accepts
the factory, otherwise returns null. The default implementation
accepts all factories.
|
| registerObject | | public Factory registerObject(Object obj, String id)(Code) | | A convenience override of registerObject(Object, String, boolean)
that defaults visible to true.
|
| registerObject | | public Factory registerObject(Object obj, String id, boolean visible)(Code) | | Register an object with the provided id. The id will be
canonicalized. The canonicalized ID will be returned by
getVisibleIDs if visible is true.
|
| reset | | final public void reset()(Code) | | Reset the service to the default factories. The factory
lock is acquired and then reInitializeFactories is called.
|
| stats | | public String stats()(Code) | | Return a string describing the statistics for this service.
This also resets the statistics. Used for debugging purposes.
|
| toString | | public String toString()(Code) | | Returns the result of super.toString, appending the name in curly braces.
|
| unregisterFactory | | final public boolean unregisterFactory(Factory factory)(Code) | | Unregister a factory. The first matching registered factory will
be removed from the list. Returns true if a matching factory was
removed.
|
|
|