1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
5 * Copyright (C) 2001-2011, International Business Machines Corporation and *
6 * others. All Rights Reserved. *
7 *******************************************************************************
9 *******************************************************************************
14 #include "unicode/utypes.h"
16 #if UCONFIG_NO_SERVICE
21 * Allow the declaration of APIs with pointers to ICUService
22 * even when service is removed from the build.
24 class ICULocaleService;
30 #include "unicode/unistr.h"
31 #include "unicode/locid.h"
32 #include "unicode/strenum.h"
42 class ICULocaleService;
45 class LocaleKeyFactory;
46 class SimpleLocaleKeyFactory;
47 class ServiceListener;
50 ******************************************************************
54 * A subclass of Key that implements a locale fallback mechanism.
55 * The first locale to search for is the locale provided by the
56 * client, and the fallback locale to search for is the current
57 * default locale. If a prefix is present, the currentDescriptor
58 * includes it before the locale proper, separated by "/". This
59 * is the default key instantiated by ICULocaleService.</p>
61 * <p>Canonicalization adjusts the locale string so that the
62 * section before the first understore is in lower case, and the rest
63 * is in upper case, with no trailing underscores.</p>
66 class U_COMMON_API LocaleKey : public ICUServiceKey {
69 UnicodeString _primaryID;
70 UnicodeString _fallbackID;
71 UnicodeString _currentID;
79 * Create a LocaleKey with canonical primary and fallback IDs.
81 static LocaleKey* createWithCanonicalFallback(const UnicodeString* primaryID,
82 const UnicodeString* canonicalFallbackID,
86 * Create a LocaleKey with canonical primary and fallback IDs.
88 static LocaleKey* createWithCanonicalFallback(const UnicodeString* primaryID,
89 const UnicodeString* canonicalFallbackID,
95 * PrimaryID is the user's requested locale string,
96 * canonicalPrimaryID is this string in canonical form,
97 * fallbackID is the current default locale's string in
100 LocaleKey(const UnicodeString& primaryID,
101 const UnicodeString& canonicalPrimaryID,
102 const UnicodeString* canonicalFallbackID,
107 * Append the prefix associated with the kind, or nothing if the kind is KIND_ANY.
109 virtual UnicodeString& prefix(UnicodeString& result) const;
112 * Return the kind code associated with this key.
114 virtual int32_t kind() const;
117 * Return the canonicalID.
119 virtual UnicodeString& canonicalID(UnicodeString& result) const;
122 * Return the currentID.
124 virtual UnicodeString& currentID(UnicodeString& result) const;
127 * Return the (canonical) current descriptor, or null if no current id.
129 virtual UnicodeString& currentDescriptor(UnicodeString& result) const;
132 * Convenience method to return the locale corresponding to the (canonical) original ID.
134 virtual Locale& canonicalLocale(Locale& result) const;
137 * Convenience method to return the locale corresponding to the (canonical) current ID.
139 virtual Locale& currentLocale(Locale& result) const;
142 * If the key has a fallback, modify the key and return true,
143 * otherwise return false.</p>
145 * <p>First falls back through the primary ID, then through
146 * the fallbackID. The final fallback is the empty string,
147 * unless the primary id was the empty string, in which case
148 * there is no fallback.
150 virtual UBool fallback();
153 * Return true if a key created from id matches, or would eventually
154 * fallback to match, the canonical ID of this key.
156 virtual UBool isFallbackOf(const UnicodeString& id) const;
160 * UObject boilerplate.
162 static UClassID U_EXPORT2 getStaticClassID();
164 virtual UClassID getDynamicClassID() const;
169 virtual ~LocaleKey();
173 virtual UnicodeString& debug(UnicodeString& result) const;
174 virtual UnicodeString& debugClass(UnicodeString& result) const;
180 ******************************************************************
184 * A subclass of ICUServiceFactory that uses LocaleKeys, and is able to
185 * 'cover' more specific locales with more general locales that it
188 * <p>Coverage may be either of the values VISIBLE or INVISIBLE.
190 * <p>'Visible' indicates that the specific locale(s) supported by
191 * the factory are registered in getSupportedIDs, 'Invisible'
192 * indicates that they are not.
194 * <p>Localization of visible ids is handled
195 * by the handling factory, regardless of kind.
197 class U_COMMON_API LocaleKeyFactory : public ICUServiceFactory {
199 const UnicodeString _name;
200 const int32_t _coverage;
205 * Coverage value indicating that the factory makes
206 * its locales visible, and does not cover more specific
212 * Coverage value indicating that the factory does not make
213 * its locales visible, and does not cover more specific
222 virtual ~LocaleKeyFactory();
226 * Constructor used by subclasses.
228 LocaleKeyFactory(int32_t coverage);
231 * Constructor used by subclasses.
233 LocaleKeyFactory(int32_t coverage, const UnicodeString& name);
236 * Implement superclass abstract method. This checks the currentID of
237 * the key against the supported IDs, and passes the canonicalLocale and
238 * kind off to handleCreate (which subclasses must implement).
241 virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
244 virtual UBool handlesKey(const ICUServiceKey& key, UErrorCode& status) const;
248 * Override of superclass method. This adjusts the result based
249 * on the coverage rule for this factory.
251 virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
254 * Return a localized name for the locale represented by id.
256 virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const;
260 * Utility method used by create(ICUServiceKey, ICUService). Subclasses can implement
261 * this instead of create. The default returns NULL.
263 virtual UObject* handleCreate(const Locale& loc, int32_t kind, const ICUService* service, UErrorCode& status) const;
266 * Return true if this id is one the factory supports (visible or
269 // virtual UBool isSupportedID(const UnicodeString& id, UErrorCode& status) const;
272 * Return the set of ids that this factory supports (visible or
273 * otherwise). This can be called often and might need to be
274 * cached if it is expensive to create.
276 virtual const Hashtable* getSupportedIDs(UErrorCode& status) const;
280 * UObject boilerplate.
282 static UClassID U_EXPORT2 getStaticClassID();
284 virtual UClassID getDynamicClassID() const;
288 virtual UnicodeString& debug(UnicodeString& result) const;
289 virtual UnicodeString& debugClass(UnicodeString& result) const;
295 ******************************************************************
299 * A LocaleKeyFactory that just returns a single object for a kind/locale.
302 class U_COMMON_API SimpleLocaleKeyFactory : public LocaleKeyFactory {
309 SimpleLocaleKeyFactory(UObject* objToAdopt,
310 const UnicodeString& locale,
314 SimpleLocaleKeyFactory(UObject* objToAdopt,
315 const Locale& locale,
322 virtual ~SimpleLocaleKeyFactory();
325 * Override of superclass method. Returns the service object if kind/locale match. Service is not used.
327 virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
330 * Override of superclass method. This adjusts the result based
331 * on the coverage rule for this factory.
333 virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
337 * Return true if this id is equal to the locale name.
339 //virtual UBool isSupportedID(const UnicodeString& id, UErrorCode& status) const;
344 * UObject boilerplate.
346 static UClassID U_EXPORT2 getStaticClassID();
348 virtual UClassID getDynamicClassID() const;
352 virtual UnicodeString& debug(UnicodeString& result) const;
353 virtual UnicodeString& debugClass(UnicodeString& result) const;
359 ******************************************************************
363 * A LocaleKeyFactory that creates a service based on the ICU locale data.
364 * This is a base class for most ICU factories. Subclasses instantiate it
365 * with a constructor that takes a bundle name, which determines the supported
366 * IDs. Subclasses then override handleCreate to create the actual service
367 * object. The default implementation returns a resource bundle.
369 class U_COMMON_API ICUResourceBundleFactory : public LocaleKeyFactory
372 UnicodeString _bundleName;
376 * Convenience constructor that uses the main ICU bundle name.
378 ICUResourceBundleFactory();
381 * A service factory based on ICU resource data in resources with
382 * the given name. This should be a 'path' that can be passed to
383 * ures_openAvailableLocales, such as U_ICUDATA or U_ICUDATA_COLL.
384 * The empty string is equivalent to U_ICUDATA.
386 ICUResourceBundleFactory(const UnicodeString& bundleName);
391 virtual ~ICUResourceBundleFactory();
395 * Return the supported IDs. This is the set of all locale names in ICULocaleData.
397 virtual const Hashtable* getSupportedIDs(UErrorCode& status) const;
400 * Create the service. The default implementation returns the resource bundle
401 * for the locale, ignoring kind, and service.
403 virtual UObject* handleCreate(const Locale& loc, int32_t kind, const ICUService* service, UErrorCode& status) const;
407 * UObject boilerplate.
409 static UClassID U_EXPORT2 getStaticClassID();
410 virtual UClassID getDynamicClassID() const;
415 virtual UnicodeString& debug(UnicodeString& result) const;
416 virtual UnicodeString& debugClass(UnicodeString& result) const;
422 ******************************************************************
425 class U_COMMON_API ICULocaleService : public ICUService
428 Locale fallbackLocale;
429 UnicodeString fallbackLocaleName;
433 * Construct an ICULocaleService.
438 * Construct an ICULocaleService with a name (useful for debugging).
440 ICULocaleService(const UnicodeString& name);
445 virtual ~ICULocaleService();
448 // redeclare because of overload resolution rules?
449 // no, causes ambiguities since both UnicodeString and Locale have constructors that take a const char*
450 // need some compiler flag to remove warnings
451 UObject* get(const UnicodeString& descriptor, UErrorCode& status) const {
452 return ICUService::get(descriptor, status);
455 UObject* get(const UnicodeString& descriptor, UnicodeString* actualReturn, UErrorCode& status) const {
456 return ICUService::get(descriptor, actualReturn, status);
461 * Convenience override for callers using locales. This calls
462 * get(Locale, int, Locale[]) with KIND_ANY for kind and null for
465 UObject* get(const Locale& locale, UErrorCode& status) const;
468 * Convenience override for callers using locales. This calls
469 * get(Locale, int, Locale[]) with a null actualReturn.
471 UObject* get(const Locale& locale, int32_t kind, UErrorCode& status) const;
474 * Convenience override for callers using locales. This calls
475 * get(Locale, String, Locale[]) with a null kind.
477 UObject* get(const Locale& locale, Locale* actualReturn, UErrorCode& status) const;
480 * Convenience override for callers using locales. This uses
481 * createKey(Locale.toString(), kind) to create a key, calls getKey, and then
482 * if actualReturn is not null, returns the actualResult from
483 * getKey (stripping any prefix) into a Locale.
485 UObject* get(const Locale& locale, int32_t kind, Locale* actualReturn, UErrorCode& status) const;
488 * Convenience override for callers using locales. This calls
489 * registerObject(Object, Locale, int32_t kind, int coverage)
490 * passing KIND_ANY for the kind, and VISIBLE for the coverage.
492 virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, UErrorCode& status);
495 * Convenience function for callers using locales. This calls
496 * registerObject(Object, Locale, int kind, int coverage)
497 * passing VISIBLE for the coverage.
499 virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, int32_t kind, UErrorCode& status);
502 * Convenience function for callers using locales. This instantiates
503 * a SimpleLocaleKeyFactory, and registers the factory.
505 virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, int32_t kind, int32_t coverage, UErrorCode& status);
509 * (Stop compiler from complaining about hidden overrides.)
510 * Since both UnicodeString and Locale have constructors that take const char*, adding a public
511 * method that takes UnicodeString causes ambiguity at call sites that use const char*.
512 * We really need a flag that is understood by all compilers that will suppress the warning about
515 virtual URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& locale, UBool visible, UErrorCode& status);
518 * Convenience method for callers using locales. This returns the standard
519 * service ID enumeration.
521 virtual StringEnumeration* getAvailableLocales(void) const;
526 * Return the name of the current fallback locale. If it has changed since this was
527 * last accessed, the service cache is cleared.
529 const UnicodeString& validateFallbackLocale() const;
532 * Override superclass createKey method.
534 virtual ICUServiceKey* createKey(const UnicodeString* id, UErrorCode& status) const;
537 * Additional createKey that takes a kind.
539 virtual ICUServiceKey* createKey(const UnicodeString* id, int32_t kind, UErrorCode& status) const;
541 friend class ServiceEnumeration;
546 /* UCONFIG_NO_SERVICE */