icuSources/common/servloc.h

   1 /**
   2  *******************************************************************************
   3  * Copyright (C) 2001-2005, International Business Machines Corporation and    *
   4  * others. All Rights Reserved.                                                *
   5  *******************************************************************************
   6  *
   7  *******************************************************************************
   8  */
   9 #ifndef ICULSERV_H
  10 #define ICULSERV_H
  11
  12 #include "unicode/utypes.h"
  13
  14 #if UCONFIG_NO_SERVICE
  15
  16 U_NAMESPACE_BEGIN
  17
  18 /*
  19  * Allow the declaration of APIs with pointers to ICUService
  20  * even when service is removed from the build.
  21  */
  22 class ICULocaleService;
  23
  24 U_NAMESPACE_END
  25
  26 #else
  27
  28 #include "unicode/unistr.h"
  29 #include "unicode/locid.h"
  30 #include "unicode/strenum.h"
  31
  32 #include "hash.h"
  33 #include "uvector.h"
  34
  35 #include "serv.h"
  36 #include "locutil.h"
  37
  38 U_NAMESPACE_BEGIN
  39
  40 class ICULocaleService;
  41
  42 class LocaleKey;
  43 class LocaleKeyFactory;
  44 class SimpleLocaleKeyFactory;
  45 class ServiceListener;
  46
  47 /*
  48  ******************************************************************
  49  */
  50
  51 /**
  52  * A subclass of Key that implements a locale fallback mechanism.
  53  * The first locale to search for is the locale provided by the
  54  * client, and the fallback locale to search for is the current
  55  * default locale.  If a prefix is present, the currentDescriptor
  56  * includes it before the locale proper, separated by "/".  This
  57  * is the default key instantiated by ICULocaleService.</p>
  58  *
  59  * <p>Canonicalization adjusts the locale string so that the
  60  * section before the first understore is in lower case, and the rest
  61  * is in upper case, with no trailing underscores.</p>
  62  */
  63
  64 class U_COMMON_API LocaleKey : public ICUServiceKey {
  65   private:
  66     int32_t _kind;
  67     UnicodeString _primaryID;
  68     UnicodeString _fallbackID;
  69     UnicodeString _currentID;
  70
  71   public:
  72     enum {
  73         KIND_ANY = -1
  74     };
  75
  76     /**
  77      * Create a LocaleKey with canonical primary and fallback IDs.
  78      */
  79     static LocaleKey* createWithCanonicalFallback(const UnicodeString* primaryID,
  80                                                   const UnicodeString* canonicalFallbackID,
  81                                                   UErrorCode& status);
  82
  83     /**
  84      * Create a LocaleKey with canonical primary and fallback IDs.
  85      */
  86     static LocaleKey* createWithCanonicalFallback(const UnicodeString* primaryID,
  87                                                   const UnicodeString* canonicalFallbackID,
  88                                                   int32_t kind,
  89                                                   UErrorCode& status);
  90
  91   protected:
  92     /**
  93      * PrimaryID is the user's requested locale string,
  94      * canonicalPrimaryID is this string in canonical form,
  95      * fallbackID is the current default locale's string in
  96      * canonical form.
  97      */
  98     LocaleKey(const UnicodeString& primaryID,
  99               const UnicodeString& canonicalPrimaryID,
 100               const UnicodeString* canonicalFallbackID,
 101               int32_t kind);
 102
 103  public:
 104     /**
 105      * Append the prefix associated with the kind, or nothing if the kind is KIND_ANY.
 106      */
 107     virtual UnicodeString& prefix(UnicodeString& result) const;
 108
 109     /**
 110      * Return the kind code associated with this key.
 111      */
 112     virtual int32_t kind() const;
 113
 114     /**
 115      * Return the canonicalID.
 116      */
 117     virtual UnicodeString& canonicalID(UnicodeString& result) const;
 118
 119     /**
 120      * Return the currentID.
 121      */
 122     virtual UnicodeString& currentID(UnicodeString& result) const;
 123
 124     /**
 125      * Return the (canonical) current descriptor, or null if no current id.
 126      */
 127     virtual UnicodeString& currentDescriptor(UnicodeString& result) const;
 128
 129     /**
 130      * Convenience method to return the locale corresponding to the (canonical) original ID.
 131      */
 132     virtual Locale& canonicalLocale(Locale& result) const;
 133
 134     /**
 135      * Convenience method to return the locale corresponding to the (canonical) current ID.
 136      */
 137     virtual Locale& currentLocale(Locale& result) const;
 138
 139     /**
 140      * If the key has a fallback, modify the key and return true,
 141      * otherwise return false.</p>
 142      *
 143      * <p>First falls back through the primary ID, then through
 144      * the fallbackID.  The final fallback is the empty string,
 145      * unless the primary id was the empty string, in which case
 146      * there is no fallback.
 147      */
 148     virtual UBool fallback();
 149
 150     /**
 151      * Return true if a key created from id matches, or would eventually
 152      * fallback to match, the canonical ID of this key.
 153      */
 154     virtual UBool isFallbackOf(const UnicodeString& id) const;
 155
 156  public:
 157     /**
 158      * UObject boilerplate.
 159      */
 160     static UClassID U_EXPORT2 getStaticClassID();
 161
 162     virtual UClassID getDynamicClassID() const;
 163
 164     /**
 165      * Destructor.
 166      */
 167     virtual ~LocaleKey();
 168
 169 #ifdef SERVICE_DEBUG
 170  public:
 171     virtual UnicodeString& debug(UnicodeString& result) const;
 172     virtual UnicodeString& debugClass(UnicodeString& result) const;
 173 #endif
 174
 175 };
 176
 177 /*
 178  ******************************************************************
 179  */
 180
 181 /**
 182  * A subclass of ICUServiceFactory that uses LocaleKeys, and is able to
 183  * 'cover' more specific locales with more general locales that it
 184  * supports.
 185  *
 186  * <p>Coverage may be either of the values VISIBLE or INVISIBLE.
 187  *
 188  * <p>'Visible' indicates that the specific locale(s) supported by
 189  * the factory are registered in getSupportedIDs, 'Invisible'
 190  * indicates that they are not.
 191  *
 192  * <p>Localization of visible ids is handled
 193  * by the handling factory, regardless of kind.
 194  */
 195 class U_COMMON_API LocaleKeyFactory : public ICUServiceFactory {
 196 protected:
 197     const UnicodeString _name;
 198     const int32_t _coverage;
 199
 200 public:
 201     enum {
 202         /**
 203          * Coverage value indicating that the factory makes
 204          * its locales visible, and does not cover more specific
 205          * locales.
 206          */
 207         VISIBLE = 0,
 208
 209         /**
 210          * Coverage value indicating that the factory does not make
 211          * its locales visible, and does not cover more specific
 212          * locales.
 213          */
 214         INVISIBLE = 1
 215     };
 216
 217     /**
 218      * Destructor.
 219      */
 220     virtual ~LocaleKeyFactory();
 221
 222 protected:
 223     /**
 224      * Constructor used by subclasses.
 225      */
 226     LocaleKeyFactory(int32_t coverage);
 227
 228     /**
 229      * Constructor used by subclasses.
 230      */
 231     LocaleKeyFactory(int32_t coverage, const UnicodeString& name);
 232
 233     /**
 234      * Implement superclass abstract method.  This checks the currentID of
 235      * the key against the supported IDs, and passes the canonicalLocale and
 236      * kind off to handleCreate (which subclasses must implement).
 237      */
 238 public:
 239     virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
 240
 241 protected:
 242     virtual UBool handlesKey(const ICUServiceKey& key, UErrorCode& status) const;
 243
 244 public:
 245     /**
 246      * Override of superclass method.  This adjusts the result based
 247      * on the coverage rule for this factory.
 248      */
 249     virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
 250
 251     /**
 252      * Return a localized name for the locale represented by id.
 253      */
 254     virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const;
 255
 256 protected:
 257     /**
 258      * Utility method used by create(ICUServiceKey, ICUService).  Subclasses can implement
 259      * this instead of create.  The default returns NULL.
 260      */
 261     virtual UObject* handleCreate(const Locale& loc, int32_t kind, const ICUService* service, UErrorCode& status) const;
 262
 263    /**
 264      * Return true if this id is one the factory supports (visible or
 265      * otherwise).
 266      */
 267  //   virtual UBool isSupportedID(const UnicodeString& id, UErrorCode& status) const;
 268
 269    /**
 270      * Return the set of ids that this factory supports (visible or
 271      * otherwise).  This can be called often and might need to be
 272      * cached if it is expensive to create.
 273      */
 274     virtual const Hashtable* getSupportedIDs(UErrorCode& status) const;
 275
 276 public:
 277     /**
 278      * UObject boilerplate.
 279      */
 280     static UClassID U_EXPORT2 getStaticClassID();
 281
 282     virtual UClassID getDynamicClassID() const;
 283
 284 #ifdef SERVICE_DEBUG
 285  public:
 286     virtual UnicodeString& debug(UnicodeString& result) const;
 287     virtual UnicodeString& debugClass(UnicodeString& result) const;
 288 #endif
 289
 290 };
 291
 292 /*
 293  ******************************************************************
 294  */
 295
 296 /**
 297  * A LocaleKeyFactory that just returns a single object for a kind/locale.
 298  */
 299
 300 class U_COMMON_API SimpleLocaleKeyFactory : public LocaleKeyFactory {
 301  private:
 302     UObject* _obj;
 303     UnicodeString _id;
 304     const int32_t _kind;
 305
 306  public:
 307     SimpleLocaleKeyFactory(UObject* objToAdopt,
 308                            const UnicodeString& locale,
 309                            int32_t kind,
 310                            int32_t coverage);
 311
 312     SimpleLocaleKeyFactory(UObject* objToAdopt,
 313                            const Locale& locale,
 314                            int32_t kind,
 315                            int32_t coverage);
 316
 317     /**
 318      * Destructor.
 319      */
 320     virtual ~SimpleLocaleKeyFactory();
 321
 322     /**
 323      * Override of superclass method.  Returns the service object if kind/locale match.  Service is not used.
 324      */
 325     virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
 326
 327     /**
 328      * Override of superclass method.  This adjusts the result based
 329      * on the coverage rule for this factory.
 330      */
 331     virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
 332
 333  protected:
 334     /**
 335      * Return true if this id is equal to the locale name.
 336      */
 337     //virtual UBool isSupportedID(const UnicodeString& id, UErrorCode& status) const;
 338
 339
 340 public:
 341     /**
 342      * UObject boilerplate.
 343      */
 344     static UClassID U_EXPORT2 getStaticClassID();
 345
 346     virtual UClassID getDynamicClassID() const;
 347
 348 #ifdef SERVICE_DEBUG
 349  public:
 350     virtual UnicodeString& debug(UnicodeString& result) const;
 351     virtual UnicodeString& debugClass(UnicodeString& result) const;
 352 #endif
 353
 354 };
 355
 356 /*
 357  ******************************************************************
 358  */
 359
 360 /**
 361  * A LocaleKeyFactory that creates a service based on the ICU locale data.
 362  * This is a base class for most ICU factories.  Subclasses instantiate it
 363  * with a constructor that takes a bundle name, which determines the supported
 364  * IDs.  Subclasses then override handleCreate to create the actual service
 365  * object.  The default implementation returns a resource bundle.
 366  */
 367 class U_COMMON_API ICUResourceBundleFactory : public LocaleKeyFactory
 368 {
 369  protected:
 370     UnicodeString _bundleName;
 371
 372  public:
 373     /**
 374      * Convenience constructor that uses the main ICU bundle name.
 375      */
 376     ICUResourceBundleFactory();
 377
 378     /**
 379      * A service factory based on ICU resource data in resources with
 380      * the given name.  This should be a 'path' that can be passed to
 381      * ures_openAvailableLocales, such as U_ICUDATA or U_ICUDATA_COLL.
 382      * The empty string is equivalent to U_ICUDATA.
 383      */
 384     ICUResourceBundleFactory(const UnicodeString& bundleName);
 385
 386     /**
 387      * Destructor
 388      */
 389     virtual ~ICUResourceBundleFactory();
 390
 391 protected:
 392     /**
 393      * Return the supported IDs.  This is the set of all locale names in ICULocaleData.
 394      */
 395     virtual const Hashtable* getSupportedIDs(UErrorCode& status) const;
 396
 397     /**
 398      * Create the service.  The default implementation returns the resource bundle
 399      * for the locale, ignoring kind, and service.
 400      */
 401     virtual UObject* handleCreate(const Locale& loc, int32_t kind, const ICUService* service, UErrorCode& status) const;
 402
 403 public:
 404     /**
 405      * UObject boilerplate.
 406      */
 407     static UClassID U_EXPORT2 getStaticClassID();
 408     virtual UClassID getDynamicClassID() const;
 409
 410
 411 #ifdef SERVICE_DEBUG
 412  public:
 413     virtual UnicodeString& debug(UnicodeString& result) const;
 414     virtual UnicodeString& debugClass(UnicodeString& result) const;
 415 #endif
 416
 417 };
 418
 419 /*
 420  ******************************************************************
 421  */
 422
 423 class U_COMMON_API ICULocaleService : public ICUService
 424 {
 425  private:
 426   Locale fallbackLocale;
 427   UnicodeString fallbackLocaleName;
 428   UMTX llock;
 429
 430  public:
 431   /**
 432    * Construct an ICULocaleService.
 433    */
 434   ICULocaleService();
 435
 436   /**
 437    * Construct an ICULocaleService with a name (useful for debugging).
 438    */
 439   ICULocaleService(const UnicodeString& name);
 440
 441   /**
 442    * Destructor.
 443    */
 444   virtual ~ICULocaleService();
 445
 446 #if 0
 447   // redeclare because of overload resolution rules?
 448   // no, causes ambiguities since both UnicodeString and Locale have constructors that take a const char*
 449   // need some compiler flag to remove warnings
 450   UObject* get(const UnicodeString& descriptor, UErrorCode& status) const {
 451     return ICUService::get(descriptor, status);
 452   }
 453
 454   UObject* get(const UnicodeString& descriptor, UnicodeString* actualReturn, UErrorCode& status) const {
 455     return ICUService::get(descriptor, actualReturn, status);
 456   }
 457 #endif
 458
 459   /**
 460    * Convenience override for callers using locales.  This calls
 461    * get(Locale, int, Locale[]) with KIND_ANY for kind and null for
 462    * actualReturn.
 463    */
 464   UObject* get(const Locale& locale, UErrorCode& status) const;
 465
 466   /**
 467    * Convenience override for callers using locales.  This calls
 468    * get(Locale, int, Locale[]) with a null actualReturn.
 469    */
 470   UObject* get(const Locale& locale, int32_t kind, UErrorCode& status) const;
 471
 472   /**
 473    * Convenience override for callers using locales. This calls
 474    * get(Locale, String, Locale[]) with a null kind.
 475    */
 476   UObject* get(const Locale& locale, Locale* actualReturn, UErrorCode& status) const;
 477
 478   /**
 479    * Convenience override for callers using locales.  This uses
 480    * createKey(Locale.toString(), kind) to create a key, calls getKey, and then
 481    * if actualReturn is not null, returns the actualResult from
 482    * getKey (stripping any prefix) into a Locale.
 483    */
 484   UObject* get(const Locale& locale, int32_t kind, Locale* actualReturn, UErrorCode& status) const;
 485
 486   /**
 487    * Convenience override for callers using locales.  This calls
 488    * registerObject(Object, Locale, int32_t kind, int coverage)
 489    * passing KIND_ANY for the kind, and VISIBLE for the coverage.
 490    */
 491   virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, UErrorCode& status);
 492
 493   /**
 494    * Convenience function for callers using locales.  This calls
 495    * registerObject(Object, Locale, int kind, int coverage)
 496    * passing VISIBLE for the coverage.
 497    */
 498   virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, int32_t kind, UErrorCode& status);
 499
 500   /**
 501    * Convenience function for callers using locales.  This  instantiates
 502    * a SimpleLocaleKeyFactory, and registers the factory.
 503    */
 504   virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, int32_t kind, int32_t coverage, UErrorCode& status);
 505
 506
 507   /**
 508    * (Stop compiler from complaining about hidden overrides.)
 509    * Since both UnicodeString and Locale have constructors that take const char*, adding a public
 510    * method that takes UnicodeString causes ambiguity at call sites that use const char*.
 511    * We really need a flag that is understood by all compilers that will suppress the warning about
 512    * hidden overrides.
 513    */
 514   virtual URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& locale, UBool visible, UErrorCode& status);
 515
 516   /**
 517    * Convenience method for callers using locales.  This returns the standard
 518    * service ID enumeration.
 519    */
 520   virtual StringEnumeration* getAvailableLocales(void) const;
 521
 522  protected:
 523
 524   /**
 525    * Return the name of the current fallback locale.  If it has changed since this was
 526    * last accessed, the service cache is cleared.
 527    */
 528   const UnicodeString& validateFallbackLocale() const;
 529
 530   /**
 531    * Override superclass createKey method.
 532    */
 533   virtual ICUServiceKey* createKey(const UnicodeString* id, UErrorCode& status) const;
 534
 535   /**
 536    * Additional createKey that takes a kind.
 537    */
 538   virtual ICUServiceKey* createKey(const UnicodeString* id, int32_t kind, UErrorCode& status) const;
 539
 540   friend class ServiceEnumeration;
 541 };
 542
 543 U_NAMESPACE_END
 544
 545     /* UCONFIG_NO_SERVICE */
 546 #endif
 547
 548     /* ICULSERV_H */
 549 #endif
 550