// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /** ******************************************************************************* * Copyright (C) 2001-2011, International Business Machines Corporation. * * All Rights Reserved. * ******************************************************************************* */ #ifndef ICUSERV_H #define ICUSERV_H #include "unicode/utypes.h" #if UCONFIG_NO_SERVICE U_NAMESPACE_BEGIN /* * Allow the declaration of APIs with pointers to ICUService * even when service is removed from the build. */ class ICUService; U_NAMESPACE_END #else #include "unicode/unistr.h" #include "unicode/locid.h" #include "unicode/umisc.h" #include "hash.h" #include "uvector.h" #include "servnotf.h" class ICUServiceTest; U_NAMESPACE_BEGIN class ICUServiceKey; class ICUServiceFactory; class SimpleFactory; class ServiceListener; class ICUService; class DNCache; /******************************************************************* * ICUServiceKey */ /** *

ICUServiceKeys are used to communicate with factories to * generate an instance of the service. ICUServiceKeys 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.

* *

ICUServiceKeys 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 ICUServiceKey has no fallbacks and * has no custom descriptors.

*/ class U_COMMON_API ICUServiceKey : public UObject { private: const UnicodeString _id; protected: static const char16_t PREFIX_DELIMITER; public: /** *

Construct a key from an id.

* * @param id the ID from which to construct the key. */ ICUServiceKey(const UnicodeString& id); /** *

Virtual destructor.

*/ virtual ~ICUServiceKey(); /** *

Return the original ID used to construct this key.

* * @return the ID used to construct this key. */ virtual const UnicodeString& getID() const; /** *

Return the canonical version of the original ID. This implementation * appends the original ID to result. Result is returned as a convenience.

* * @param result the output parameter to which the id will be appended. * @return the modified result. */ virtual UnicodeString& canonicalID(UnicodeString& result) const; /** *

Return the (canonical) current ID. This implementation appends * the canonical ID to result. Result is returned as a convenience.

* * @param result the output parameter to which the current id will be appended. * @return the modified result. */ virtual UnicodeString& currentID(UnicodeString& result) const; /** *

Return the current descriptor. This implementation appends * the current descriptor to result. Result is returned as a convenience.

* *

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.

* * @param result the output parameter to which the current id will be appended. * @return the modified result. */ virtual UnicodeString& currentDescriptor(UnicodeString& result) const; /** *

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.

* * @return true if the ICUServiceKey changed to a valid fallback value. */ virtual UBool fallback(); /** *

Return true if a key created from id matches, or would eventually * fallback to match, the canonical ID of this ICUServiceKey.

* * @param id the id to test. * @return true if this ICUServiceKey's canonical ID is a fallback of id. */ virtual UBool isFallbackOf(const UnicodeString& id) const; /** *

Return the prefix. This implementation leaves result unchanged. * Result is returned as a convenience.

* * @param result the output parameter to which the prefix will be appended. * @return the modified result. */ virtual UnicodeString& prefix(UnicodeString& result) const; /** *

A utility to parse the prefix out of a descriptor string. Only * the (undelimited) prefix, if any, remains in result. Result is returned as a * convenience.

* * @param result an input/output parameter that on entry is a descriptor, and * on exit is the prefix of that descriptor. * @return the modified result. */ static UnicodeString& parsePrefix(UnicodeString& result); /** *

A utility to parse the suffix out of a descriptor string. Only * the (undelimited) suffix, if any, remains in result. Result is returned as a * convenience.

* * @param result an input/output parameter that on entry is a descriptor, and * on exit is the suffix of that descriptor. * @return the modified result. */ static UnicodeString& parseSuffix(UnicodeString& result); public: /** * UObject RTTI boilerplate. */ static UClassID U_EXPORT2 getStaticClassID(); /** * UObject RTTI boilerplate. */ virtual UClassID getDynamicClassID() const override; #ifdef SERVICE_DEBUG public: virtual UnicodeString& debug(UnicodeString& result) const; virtual UnicodeString& debugClass(UnicodeString& result) const; #endif }; /******************************************************************* * ICUServiceFactory */ /** *

An implementing ICUServiceFactory generates 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.

*/ class U_COMMON_API ICUServiceFactory : public UObject { public: virtual ~ICUServiceFactory(); /** *

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

* *

If the factory supports the key, then it can call * the service's getKey(ICUServiceKey, String[], ICUServiceFactory) 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.

* * @param key the service key. * @param service the service with which this factory is registered. * @param status the error code status. * @return the service object, or nullptr if the factory does not support the key. */ virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const = 0; /** *

Update result to reflect the IDs (not descriptors) that this * factory publicly handles. Result contains mappings from ID to * factory. On entry it will contain all (visible) mappings from * previously-registered factories.

* *

This function, together with getDisplayName, are used to * support ICUService::getDisplayNames. The factory determines * which IDs (of those it supports) it will make visible, and of * those, which it will provide localized display names for. In * most cases it will register mappings from all IDs it supports * to itself.

* * @param result the mapping table to update. * @param status the error code status. */ virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const = 0; /** *

Return, in result, the display name of the id in the provided locale. * This is an id, not a descriptor. If the id is * not visible, sets result to bogus. If the * incoming result is bogus, it remains bogus. Result is returned as a * convenience. Results are not defined if id is not one supported by this * factory.

* * @param id a visible id supported by this factory. * @param locale the locale for which to generate the corresponding localized display name. * @param result output parameter to hold the display name. * @return result. */ virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const = 0; }; /* ****************************************************************** */ /** *

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. No localization of display * names is performed.

*/ class U_COMMON_API SimpleFactory : public ICUServiceFactory { protected: UObject* _instance; const UnicodeString _id; const UBool _visible; public: /** *

Construct a SimpleFactory that maps a single ID to a single * service instance. If visible is true, the ID will be visible. * The instance must not be nullptr. The SimpleFactory will adopt * the instance, which must not be changed subsequent to this call.

* * @param instanceToAdopt the service instance to adopt. * @param id the ID to assign to this service instance. * @param visible if true, the ID will be visible. */ SimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible = true); /** *

Destructor.

*/ virtual ~SimpleFactory(); /** *

This implementation returns a clone of the service instance if the factory's ID is equal to * the key's currentID. Service and prefix are ignored.

* * @param key the service key. * @param service the service with which this factory is registered. * @param status the error code status. * @return the service object, or nullptr if the factory does not support the key. */ virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const override; /** *

This implementation adds a mapping from ID -> this to result if visible is true, * otherwise it removes ID from result.

* * @param result the mapping table to update. * @param status the error code status. */ virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const override; /** *

This implementation returns the factory ID if it equals id and visible is true, * otherwise it returns the empty string. (This implementation provides * no localized id information.)

* * @param id a visible id supported by this factory. * @param locale the locale for which to generate the corresponding localized display name. * @param result output parameter to hold the display name. * @return result. */ virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const override; public: /** * UObject RTTI boilerplate. */ static UClassID U_EXPORT2 getStaticClassID(); /** * UObject RTTI boilerplate. */ virtual UClassID getDynamicClassID() const override; #ifdef SERVICE_DEBUG public: virtual UnicodeString& debug(UnicodeString& toAppendTo) const; virtual UnicodeString& debugClass(UnicodeString& toAppendTo) const; #endif }; /* ****************************************************************** */ /** *

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.

*/ class U_COMMON_API ServiceListener : public EventListener { public: virtual ~ServiceListener(); /** *

This method is called when the service changes. At the time of the * call this listener is registered with the service. It must * not modify the notifier in the context of this call.

* * @param service the service that changed. */ virtual void serviceChanged(const ICUService& service) const = 0; public: /** * UObject RTTI boilerplate. */ static UClassID U_EXPORT2 getStaticClassID(); /** * UObject RTTI boilerplate. */ virtual UClassID getDynamicClassID() const override; }; /* ****************************************************************** */ /** *

A StringPair holds a displayName/ID pair. ICUService uses it * as the array elements returned by getDisplayNames. */ class U_COMMON_API StringPair : public UMemory { public: /** *

The display name of the pair.

*/ const UnicodeString displayName; /** *

The ID of the pair.

*/ const UnicodeString id; /** *

Creates a string pair from a displayName and an ID.

* * @param displayName the displayName. * @param id the ID. * @param status the error code status. * @return a StringPair if the creation was successful, otherwise nullptr. */ static StringPair* create(const UnicodeString& displayName, const UnicodeString& id, UErrorCode& status); /** *

Return true if either string of the pair is bogus.

* @return true if either string of the pair is bogus. */ UBool isBogus() const; private: StringPair(const UnicodeString& displayName, const UnicodeString& id); }; /******************************************************************* * ICUService */ /** *

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. A * new service object is returned for each query. The caller is * responsible for deleting 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 ICUServiceFactory objects * registered with the service. The service queries each * ICUServiceFactory 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.

* *

In ICU 2.4, UObject (the base class of service instances) does * not define a polymorphic clone function. ICUService uses clones to * manage ownership. Thus, for now, ICUService defines an abstract * method, cloneInstance, that clients must implement to create clones * of the service instances. This may change in future releases of * ICU.

* *

ICUServiceFactories can be dynamically registered and * unregistered with the service. When registered, an * ICUServiceFactory 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.

* *

If a service has variants (e.g., the different variants of * BreakIterator) an ICUServiceFactory can use the prefix of the * ICUServiceKey to determine the variant of a service to generate. * If it does not support all variants, it can request * previously-registered factories to handle the ones it does not * support.

* *

ICUService uses ICUServiceKeys to query factories and perform * fallback. The ICUServiceKey defines the canonical form of the ID, * and implements the fallback strategy. Custom ICUServiceKeys can be * defined that parse complex IDs into components that * ICUServiceFactories can more easily use. The ICUServiceKey can * cache the results of this parsing to save repeated effort. * ICUService provides convenience APIs that take UnicodeStrings and * generate default ICUServiceKeys 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. ICUServiceFactories 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 an array of the all the localized * visible IDs and their corresponding internal 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 * 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 * ICUServiceKey and fallback strategy. ICULocaleService is a * subclass of ICUService that uses Locale names as IDs and uses * ICUServiceKeys that implement the standard resource bundle fallback * strategy. Most clients will wish to subclass it instead of * ICUService.

*/ class U_COMMON_API ICUService : public ICUNotifier { protected: /** * Name useful for debugging. */ const UnicodeString name; private: /** * Timestamp so iterators can be fail-fast. */ uint32_t timestamp; /** * All the factories registered with this service. */ UVector* factories; /** * The service cache. */ Hashtable* serviceCache; /** * The ID cache. */ Hashtable* idCache; /** * The name cache. */ DNCache* dnCache; /** * Constructor. */ public: /** *

Construct a new ICUService.

*/ ICUService(); /** *

Construct with a name (useful for debugging).

* * @param name a name to use in debugging. */ ICUService(const UnicodeString& name); /** *

Destructor.

*/ virtual ~ICUService(); /** *

Return the name of this service. This will be the empty string if none was assigned. * Returns result as a convenience.

* * @param result an output parameter to contain the name of this service. * @return the name of this service. */ UnicodeString& getName(UnicodeString& result) const; /** *

Convenience override for get(ICUServiceKey&, UnicodeString*). This uses * createKey to create a key for the provided descriptor.

* * @param descriptor the descriptor. * @param status the error code status. * @return the service instance, or nullptr. */ UObject* get(const UnicodeString& descriptor, UErrorCode& status) const; /** *

Convenience override for get(ICUServiceKey&, UnicodeString*). This uses * createKey to create a key from the provided descriptor.

* * @param descriptor the descriptor. * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or nullptr. * @param status the error code status. * @return the service instance, or nullptr. */ UObject* get(const UnicodeString& descriptor, UnicodeString* actualReturn, UErrorCode& status) const; /** *

Convenience override for get(ICUServiceKey&, UnicodeString*).

* * @param key the key. * @param status the error code status. * @return the service instance, or nullptr. */ UObject* getKey(ICUServiceKey& key, UErrorCode& status) const; /** *

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

* *

This queries the cache using the key's descriptor, and if no * object in the cache matches, 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 a factory returns a service object, or the key * has no fallback. If no object is found, the result of handleDefault * is returned.

* *

Subclasses can override this method to further customize the * result before returning it. * * @param key the key. * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or nullptr. * @param status the error code status. * @return the service instance, or nullptr. */ virtual UObject* getKey(ICUServiceKey& key, UnicodeString* actualReturn, UErrorCode& status) const; /** *

This version of getKey is only called by ICUServiceFactories within the scope * of a previous getKey call, to determine what previously-registered factories would * have returned. For details, see getKey(ICUServiceKey&, UErrorCode&). Subclasses * should not call it directly, but call through one of the other get functions.

* * @param key the key. * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or nullptr. * @param factory the factory making the recursive call. * @param status the error code status. * @return the service instance, or nullptr. */ UObject* getKey(ICUServiceKey& key, UnicodeString* actualReturn, const ICUServiceFactory* factory, UErrorCode& status) const; /** *

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

* * @param result a vector to hold the returned IDs. * @param status the error code status. * @return the result vector. */ UVector& getVisibleIDs(UVector& result, UErrorCode& status) const; /** *

Return a snapshot of the visible IDs for this service. This * list will not change as ICUServiceFactories are added or removed, but the * supported IDs will, so there is no guarantee that all and only * the IDs in the returned list will be visible and supported by the * service in subsequent calls.

* *

The IDs are returned as pointers to UnicodeStrings. The * caller owns the IDs. Previous contents of result are discarded before * new elements, if any, are added.

* *

matchID is passed to createKey to create a key. If the key * is not nullptr, its isFallbackOf method is used to filter out IDs * that don't match the key or have it as a fallback.

* * @param result a vector to hold the returned IDs. * @param matchID an ID used to filter the result, or nullptr if all IDs are desired. * @param status the error code status. * @return the result vector. */ UVector& getVisibleIDs(UVector& result, const UnicodeString* matchID, UErrorCode& status) const; /** *

Convenience override for getDisplayName(const UnicodeString&, const Locale&, UnicodeString&) that * uses the current default locale.

* * @param id the ID for which to retrieve the localized displayName. * @param result an output parameter to hold the display name. * @return the modified result. */ UnicodeString& getDisplayName(const UnicodeString& id, UnicodeString& result) const; /** *

Given a visible ID, return the display name in the requested locale. * If there is no directly supported ID corresponding to this ID, result is * set to bogus.

* * @param id the ID for which to retrieve the localized displayName. * @param result an output parameter to hold the display name. * @param locale the locale in which to localize the ID. * @return the modified result. */ UnicodeString& getDisplayName(const UnicodeString& id, UnicodeString& result, const Locale& locale) const; /** *

Convenience override of getDisplayNames(const Locale&, const UnicodeString*) that * uses the current default Locale as the locale and nullptr for * the matchID.

* * @param result a vector to hold the returned displayName/id StringPairs. * @param status the error code status. * @return the modified result vector. */ UVector& getDisplayNames(UVector& result, UErrorCode& status) const; /** *

Convenience override of getDisplayNames(const Locale&, const UnicodeString*) that * uses nullptr for the matchID.

* * @param result a vector to hold the returned displayName/id StringPairs. * @param locale the locale in which to localize the ID. * @param status the error code status. * @return the modified result vector. */ UVector& getDisplayNames(UVector& result, const Locale& locale, UErrorCode& status) const; /** *

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 result.

* *

The names are returned as pointers to StringPairs, which * contain both the displayName and the corresponding ID. The * caller owns the StringPairs. Previous contents of result are * discarded before new elements, if any, are added.

* *

matchID is passed to createKey to create a key. If the key * is not nullptr, its isFallbackOf method is used to filter out IDs * that don't match the key or have it as a fallback.

* * @param result a vector to hold the returned displayName/id StringPairs. * @param locale the locale in which to localize the ID. * @param matchID an ID used to filter the result, or nullptr if all IDs are desired. * @param status the error code status. * @return the result vector. */ UVector& getDisplayNames(UVector& result, const Locale& locale, const UnicodeString* matchID, UErrorCode& status) const; /** *

A convenience override of registerInstance(UObject*, const UnicodeString&, UBool) * that defaults visible to true.

* * @param objToAdopt the object to register and adopt. * @param id the ID to assign to this object. * @param status the error code status. * @return a registry key that can be passed to unregister to unregister * (and discard) this instance. */ URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& id, UErrorCode& status); /** *

Register a service instance with the provided ID. The ID will be * canonicalized. The canonicalized ID will be returned by * getVisibleIDs if visible is true. The service instance will be adopted and * must not be modified subsequent to this call.

* *

This issues a serviceChanged notification to registered listeners.

* *

This implementation wraps the object using * createSimpleFactory, and calls registerFactory.

* * @param objToAdopt the object to register and adopt. * @param id the ID to assign to this object. * @param visible true if getVisibleIDs is to return this ID. * @param status the error code status. * @return a registry key that can be passed to unregister() to unregister * (and discard) this instance. */ virtual URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& id, UBool visible, UErrorCode& status); /** *

Register an ICUServiceFactory. Returns a registry key that * can be used to unregister the factory. The factory * must not be modified subsequent to this call. The service owns * all registered factories. In case of an error, the factory is * deleted.

* *

This issues a serviceChanged notification to registered listeners.

* *

The default implementation accepts all factories.

* * @param factoryToAdopt the factory to register and adopt. * @param status the error code status. * @return a registry key that can be passed to unregister to unregister * (and discard) this factory. */ virtual URegistryKey registerFactory(ICUServiceFactory* factoryToAdopt, UErrorCode& status); /** *

Unregister a factory using a registry key returned by * registerInstance or registerFactory. After a successful call, * the factory will be removed from the service factory list and * deleted, and the key becomes invalid.

* *

This issues a serviceChanged notification to registered * listeners.

* * @param rkey the registry key. * @param status the error code status. * @return true if the call successfully unregistered the factory. */ virtual UBool unregister(URegistryKey rkey, UErrorCode& status); /** *

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

* *

This issues a serviceChanged notification to registered listeners.

*/ virtual void reset(); /** *

Return true if the service is in its default state.

* *

The default implementation returns true if there are no * factories registered.

*/ virtual UBool isDefault() const; /** *

Create a key from an ID. If ID is nullptr, returns nullptr.

* *

The default implementation creates an ICUServiceKey instance. * Subclasses can override to define more useful keys appropriate * to the factories they accept.

* * @param a pointer to the ID for which to create a default ICUServiceKey. * @param status the error code status. * @return the ICUServiceKey corresponding to ID, or nullptr. */ virtual ICUServiceKey* createKey(const UnicodeString* id, UErrorCode& status) const; /** *

Clone object so that caller can own the copy. In ICU2.4, UObject doesn't define * clone, so we need an instance-aware method that knows how to do this. * This is public so factories can call it, but should really be protected.

* * @param instance the service instance to clone. * @return a clone of the passed-in instance, or nullptr if cloning was unsuccessful. */ virtual UObject* cloneInstance(UObject* instance) const = 0; /************************************************************************ * Subclassing API */ protected: /** *

Create a factory that wraps a single service object. Called by registerInstance.

* *

The default implementation returns an instance of SimpleFactory.

* * @param instanceToAdopt the service instance to adopt. * @param id the ID to assign to this service instance. * @param visible if true, the ID will be visible. * @param status the error code status. * @return an instance of ICUServiceFactory that maps this instance to the provided ID. */ virtual ICUServiceFactory* createSimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible, UErrorCode& status); /** *

Reinitialize the factory list to its default state. After this call, isDefault() * must return true.

* *

This issues a serviceChanged notification to registered listeners.

* *

The default implementation clears the factory list. * Subclasses can override to provide other default initialization * of the factory list. Subclasses must not call this method * directly, since it must only be called while holding write * access to the factory list.

*/ virtual void reInitializeFactories(); /** *

Default handler for this service if no factory in the factory list * handled the key passed to getKey.

* *

The default implementation returns nullptr.

* * @param key the key. * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or nullptr. * @param status the error code status. * @return the service instance, or nullptr. */ virtual UObject* handleDefault(const ICUServiceKey& key, UnicodeString* actualReturn, UErrorCode& status) const; /** *

Clear caches maintained by this service.

* *

Subclasses can override if they implement additional caches * 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 the factory lock.

*/ virtual void clearCaches(); /** *

Return true if the listener is accepted.

* *

The default implementation accepts the listener if it is * a ServiceListener. Subclasses can override this to accept * different listeners.

* * @param l the listener to test. * @return true if the service accepts the listener. */ virtual UBool acceptsListener(const EventListener& l) const override; /** *

Notify the listener of a service change.

* *

The default implementation assumes a ServiceListener. * If acceptsListener has been overridden to accept different * listeners, this should be overridden as well.

* * @param l the listener to notify. */ virtual void notifyListener(EventListener& l) const override; /************************************************************************ * Utilities for subclasses. */ /** *

Clear 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 also changes, requiring the cache to be * flushed, but not the visible IDs themselves.

*/ void clearServiceCache(); /** *

Return a map from visible IDs to factories. * This must only be called when the mutex is held.

* * @param status the error code status. * @return a Hashtable containing mappings from visible * IDs to factories. */ const Hashtable* getVisibleIDMap(UErrorCode& status) const; /** *

Allow subclasses to read the time stamp.

* * @return the timestamp. */ int32_t getTimestamp() const; /** *

Return the number of registered factories.

* * @return the number of factories registered at the time of the call. */ int32_t countFactories() const; private: friend class ::ICUServiceTest; // give tests access to countFactories. }; U_NAMESPACE_END /* UCONFIG_NO_SERVICE */ #endif /* ICUSERV_H */ #endif