michael@0: /**
michael@0:  *******************************************************************************
michael@0:  * Copyright (C) 2001-2011, International Business Machines Corporation and    *
michael@0:  * others. All Rights Reserved.                                                *
michael@0:  *******************************************************************************
michael@0:  *
michael@0:  *******************************************************************************
michael@0:  */
michael@0: #ifndef ICULSERV_H
michael@0: #define ICULSERV_H
michael@0: 
michael@0: #include "unicode/utypes.h"
michael@0: 
michael@0: #if UCONFIG_NO_SERVICE
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: /*
michael@0:  * Allow the declaration of APIs with pointers to ICUService
michael@0:  * even when service is removed from the build.
michael@0:  */
michael@0: class ICULocaleService;
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0: #else
michael@0: 
michael@0: #include "unicode/unistr.h"
michael@0: #include "unicode/locid.h"
michael@0: #include "unicode/strenum.h"
michael@0: 
michael@0: #include "hash.h"
michael@0: #include "uvector.h"
michael@0: 
michael@0: #include "serv.h"
michael@0: #include "locutil.h"
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: class ICULocaleService;
michael@0: 
michael@0: class LocaleKey;
michael@0: class LocaleKeyFactory;
michael@0: class SimpleLocaleKeyFactory;
michael@0: class ServiceListener;
michael@0: 
michael@0: /*
michael@0:  ******************************************************************
michael@0:  */
michael@0: 
michael@0: /**
michael@0:  * A subclass of Key that implements a locale fallback mechanism.
michael@0:  * The first locale to search for is the locale provided by the
michael@0:  * client, and the fallback locale to search for is the current
michael@0:  * default locale.  If a prefix is present, the currentDescriptor
michael@0:  * includes it before the locale proper, separated by "/".  This
michael@0:  * is the default key instantiated by ICULocaleService.</p>
michael@0:  *
michael@0:  * <p>Canonicalization adjusts the locale string so that the
michael@0:  * section before the first understore is in lower case, and the rest
michael@0:  * is in upper case, with no trailing underscores.</p> 
michael@0:  */
michael@0: 
michael@0: class U_COMMON_API LocaleKey : public ICUServiceKey {
michael@0:   private: 
michael@0:     int32_t _kind;
michael@0:     UnicodeString _primaryID;
michael@0:     UnicodeString _fallbackID;
michael@0:     UnicodeString _currentID;
michael@0: 
michael@0:   public:
michael@0:     enum {
michael@0:         KIND_ANY = -1
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      * Create a LocaleKey with canonical primary and fallback IDs.
michael@0:      */
michael@0:     static LocaleKey* createWithCanonicalFallback(const UnicodeString* primaryID, 
michael@0:                                                   const UnicodeString* canonicalFallbackID,
michael@0:                                                   UErrorCode& status);
michael@0: 
michael@0:     /**
michael@0:      * Create a LocaleKey with canonical primary and fallback IDs.
michael@0:      */
michael@0:     static LocaleKey* createWithCanonicalFallback(const UnicodeString* primaryID, 
michael@0:                                                   const UnicodeString* canonicalFallbackID, 
michael@0:                                                   int32_t kind,
michael@0:                                                   UErrorCode& status);
michael@0: 
michael@0:   protected:
michael@0:     /**
michael@0:      * PrimaryID is the user's requested locale string,
michael@0:      * canonicalPrimaryID is this string in canonical form,
michael@0:      * fallbackID is the current default locale's string in
michael@0:      * canonical form.
michael@0:      */
michael@0:     LocaleKey(const UnicodeString& primaryID, 
michael@0:               const UnicodeString& canonicalPrimaryID, 
michael@0:               const UnicodeString* canonicalFallbackID, 
michael@0:               int32_t kind);
michael@0: 
michael@0:  public:
michael@0:     /**
michael@0:      * Append the prefix associated with the kind, or nothing if the kind is KIND_ANY.
michael@0:      */
michael@0:     virtual UnicodeString& prefix(UnicodeString& result) const;
michael@0: 
michael@0:     /**
michael@0:      * Return the kind code associated with this key.
michael@0:      */
michael@0:     virtual int32_t kind() const;
michael@0: 
michael@0:     /**
michael@0:      * Return the canonicalID.
michael@0:      */
michael@0:     virtual UnicodeString& canonicalID(UnicodeString& result) const;
michael@0: 
michael@0:     /**
michael@0:      * Return the currentID.
michael@0:      */
michael@0:     virtual UnicodeString& currentID(UnicodeString& result) const;
michael@0: 
michael@0:     /**
michael@0:      * Return the (canonical) current descriptor, or null if no current id.
michael@0:      */
michael@0:     virtual UnicodeString& currentDescriptor(UnicodeString& result) const;
michael@0: 
michael@0:     /**
michael@0:      * Convenience method to return the locale corresponding to the (canonical) original ID.
michael@0:      */
michael@0:     virtual Locale& canonicalLocale(Locale& result) const;
michael@0: 
michael@0:     /**
michael@0:      * Convenience method to return the locale corresponding to the (canonical) current ID.
michael@0:      */
michael@0:     virtual Locale& currentLocale(Locale& result) const;
michael@0: 
michael@0:     /**
michael@0:      * If the key has a fallback, modify the key and return true,
michael@0:      * otherwise return false.</p>
michael@0:      *
michael@0:      * <p>First falls back through the primary ID, then through
michael@0:      * the fallbackID.  The final fallback is the empty string,
michael@0:      * unless the primary id was the empty string, in which case
michael@0:      * there is no fallback.  
michael@0:      */
michael@0:     virtual UBool fallback();
michael@0: 
michael@0:     /**
michael@0:      * Return true if a key created from id matches, or would eventually
michael@0:      * fallback to match, the canonical ID of this key.  
michael@0:      */
michael@0:     virtual UBool isFallbackOf(const UnicodeString& id) const;
michael@0:     
michael@0:  public:
michael@0:     /**
michael@0:      * UObject boilerplate.
michael@0:      */
michael@0:     static UClassID U_EXPORT2 getStaticClassID();
michael@0: 
michael@0:     virtual UClassID getDynamicClassID() const;
michael@0: 
michael@0:     /**
michael@0:      * Destructor.
michael@0:      */
michael@0:     virtual ~LocaleKey();
michael@0: 
michael@0: #ifdef SERVICE_DEBUG
michael@0:  public:
michael@0:     virtual UnicodeString& debug(UnicodeString& result) const;
michael@0:     virtual UnicodeString& debugClass(UnicodeString& result) const;
michael@0: #endif
michael@0: 
michael@0: };
michael@0: 
michael@0: /*
michael@0:  ******************************************************************
michael@0:  */
michael@0: 
michael@0: /**
michael@0:  * A subclass of ICUServiceFactory that uses LocaleKeys, and is able to
michael@0:  * 'cover' more specific locales with more general locales that it
michael@0:  * supports.  
michael@0:  *
michael@0:  * <p>Coverage may be either of the values VISIBLE or INVISIBLE.
michael@0:  *
michael@0:  * <p>'Visible' indicates that the specific locale(s) supported by
michael@0:  * the factory are registered in getSupportedIDs, 'Invisible'
michael@0:  * indicates that they are not.
michael@0:  *
michael@0:  * <p>Localization of visible ids is handled
michael@0:  * by the handling factory, regardless of kind.
michael@0:  */
michael@0: class U_COMMON_API LocaleKeyFactory : public ICUServiceFactory {
michael@0: protected:
michael@0:     const UnicodeString _name;
michael@0:     const int32_t _coverage;
michael@0: 
michael@0: public:
michael@0:     enum {
michael@0:         /**
michael@0:          * Coverage value indicating that the factory makes
michael@0:          * its locales visible, and does not cover more specific 
michael@0:          * locales.
michael@0:          */
michael@0:         VISIBLE = 0,
michael@0: 
michael@0:         /**
michael@0:          * Coverage value indicating that the factory does not make
michael@0:          * its locales visible, and does not cover more specific
michael@0:          * locales.
michael@0:          */
michael@0:         INVISIBLE = 1
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      * Destructor.
michael@0:      */
michael@0:     virtual ~LocaleKeyFactory();
michael@0: 
michael@0: protected:
michael@0:     /**
michael@0:      * Constructor used by subclasses.
michael@0:      */
michael@0:     LocaleKeyFactory(int32_t coverage);
michael@0: 
michael@0:     /**
michael@0:      * Constructor used by subclasses.
michael@0:      */
michael@0:     LocaleKeyFactory(int32_t coverage, const UnicodeString& name);
michael@0: 
michael@0:     /**
michael@0:      * Implement superclass abstract method.  This checks the currentID of
michael@0:      * the key against the supported IDs, and passes the canonicalLocale and
michael@0:      * kind off to handleCreate (which subclasses must implement).
michael@0:      */
michael@0: public:
michael@0:     virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
michael@0: 
michael@0: protected:
michael@0:     virtual UBool handlesKey(const ICUServiceKey& key, UErrorCode& status) const;
michael@0: 
michael@0: public:
michael@0:     /**
michael@0:      * Override of superclass method.  This adjusts the result based
michael@0:      * on the coverage rule for this factory.
michael@0:      */
michael@0:     virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
michael@0: 
michael@0:     /**
michael@0:      * Return a localized name for the locale represented by id.
michael@0:      */
michael@0:     virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const;
michael@0: 
michael@0: protected:
michael@0:     /**
michael@0:      * Utility method used by create(ICUServiceKey, ICUService).  Subclasses can implement
michael@0:      * this instead of create.  The default returns NULL.
michael@0:      */
michael@0:     virtual UObject* handleCreate(const Locale& loc, int32_t kind, const ICUService* service, UErrorCode& status) const;
michael@0: 
michael@0:    /**
michael@0:      * Return true if this id is one the factory supports (visible or 
michael@0:      * otherwise).
michael@0:      */
michael@0:  //   virtual UBool isSupportedID(const UnicodeString& id, UErrorCode& status) const;
michael@0: 
michael@0:    /**
michael@0:      * Return the set of ids that this factory supports (visible or 
michael@0:      * otherwise).  This can be called often and might need to be
michael@0:      * cached if it is expensive to create.
michael@0:      */
michael@0:     virtual const Hashtable* getSupportedIDs(UErrorCode& status) const;
michael@0: 
michael@0: public:
michael@0:     /**
michael@0:      * UObject boilerplate.
michael@0:      */
michael@0:     static UClassID U_EXPORT2 getStaticClassID();
michael@0: 
michael@0:     virtual UClassID getDynamicClassID() const;
michael@0: 
michael@0: #ifdef SERVICE_DEBUG
michael@0:  public:
michael@0:     virtual UnicodeString& debug(UnicodeString& result) const;
michael@0:     virtual UnicodeString& debugClass(UnicodeString& result) const;
michael@0: #endif
michael@0: 
michael@0: };
michael@0: 
michael@0: /*
michael@0:  ******************************************************************
michael@0:  */
michael@0: 
michael@0: /**
michael@0:  * A LocaleKeyFactory that just returns a single object for a kind/locale.
michael@0:  */
michael@0: 
michael@0: class U_COMMON_API SimpleLocaleKeyFactory : public LocaleKeyFactory {
michael@0:  private:
michael@0:     UObject* _obj;
michael@0:     UnicodeString _id;
michael@0:     const int32_t _kind;
michael@0: 
michael@0:  public:
michael@0:     SimpleLocaleKeyFactory(UObject* objToAdopt, 
michael@0:                            const UnicodeString& locale, 
michael@0:                            int32_t kind, 
michael@0:                            int32_t coverage);
michael@0: 
michael@0:     SimpleLocaleKeyFactory(UObject* objToAdopt, 
michael@0:                            const Locale& locale, 
michael@0:                            int32_t kind, 
michael@0:                            int32_t coverage);
michael@0: 
michael@0:     /**
michael@0:      * Destructor.
michael@0:      */
michael@0:     virtual ~SimpleLocaleKeyFactory();
michael@0: 
michael@0:     /**
michael@0:      * Override of superclass method.  Returns the service object if kind/locale match.  Service is not used.
michael@0:      */
michael@0:     virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
michael@0: 
michael@0:     /**
michael@0:      * Override of superclass method.  This adjusts the result based
michael@0:      * on the coverage rule for this factory.
michael@0:      */
michael@0:     virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
michael@0: 
michael@0:  protected:
michael@0:     /**
michael@0:      * Return true if this id is equal to the locale name.
michael@0:      */
michael@0:     //virtual UBool isSupportedID(const UnicodeString& id, UErrorCode& status) const;
michael@0: 
michael@0: 
michael@0: public:
michael@0:     /**
michael@0:      * UObject boilerplate.
michael@0:      */
michael@0:     static UClassID U_EXPORT2 getStaticClassID();
michael@0: 
michael@0:     virtual UClassID getDynamicClassID() const;
michael@0: 
michael@0: #ifdef SERVICE_DEBUG
michael@0:  public:
michael@0:     virtual UnicodeString& debug(UnicodeString& result) const;
michael@0:     virtual UnicodeString& debugClass(UnicodeString& result) const;
michael@0: #endif
michael@0: 
michael@0: };
michael@0: 
michael@0: /*
michael@0:  ******************************************************************
michael@0:  */
michael@0: 
michael@0: /**
michael@0:  * A LocaleKeyFactory that creates a service based on the ICU locale data.
michael@0:  * This is a base class for most ICU factories.  Subclasses instantiate it
michael@0:  * with a constructor that takes a bundle name, which determines the supported
michael@0:  * IDs.  Subclasses then override handleCreate to create the actual service
michael@0:  * object.  The default implementation returns a resource bundle.
michael@0:  */
michael@0: class U_COMMON_API ICUResourceBundleFactory : public LocaleKeyFactory 
michael@0: {
michael@0:  protected:
michael@0:     UnicodeString _bundleName;
michael@0: 
michael@0:  public:
michael@0:     /**
michael@0:      * Convenience constructor that uses the main ICU bundle name.
michael@0:      */
michael@0:     ICUResourceBundleFactory();
michael@0: 
michael@0:     /**
michael@0:      * A service factory based on ICU resource data in resources with
michael@0:      * the given name.  This should be a 'path' that can be passed to
michael@0:      * ures_openAvailableLocales, such as U_ICUDATA or U_ICUDATA_COLL.
michael@0:      * The empty string is equivalent to U_ICUDATA.
michael@0:      */
michael@0:     ICUResourceBundleFactory(const UnicodeString& bundleName);
michael@0: 
michael@0:     /**
michael@0:      * Destructor
michael@0:      */
michael@0:     virtual ~ICUResourceBundleFactory();
michael@0: 
michael@0: protected:
michael@0:     /**
michael@0:      * Return the supported IDs.  This is the set of all locale names in ICULocaleData.
michael@0:      */
michael@0:     virtual const Hashtable* getSupportedIDs(UErrorCode& status) const;
michael@0: 
michael@0:     /**
michael@0:      * Create the service.  The default implementation returns the resource bundle
michael@0:      * for the locale, ignoring kind, and service.
michael@0:      */
michael@0:     virtual UObject* handleCreate(const Locale& loc, int32_t kind, const ICUService* service, UErrorCode& status) const;
michael@0: 
michael@0: public:
michael@0:     /**
michael@0:      * UObject boilerplate.
michael@0:      */
michael@0:     static UClassID U_EXPORT2 getStaticClassID();
michael@0:     virtual UClassID getDynamicClassID() const;
michael@0: 
michael@0: 
michael@0: #ifdef SERVICE_DEBUG
michael@0:  public:
michael@0:     virtual UnicodeString& debug(UnicodeString& result) const;
michael@0:     virtual UnicodeString& debugClass(UnicodeString& result) const;
michael@0: #endif
michael@0: 
michael@0: };
michael@0: 
michael@0: /*
michael@0:  ******************************************************************
michael@0:  */
michael@0: 
michael@0: class U_COMMON_API ICULocaleService : public ICUService 
michael@0: {
michael@0:  private:
michael@0:   Locale fallbackLocale;
michael@0:   UnicodeString fallbackLocaleName;
michael@0: 
michael@0:  public:
michael@0:   /**
michael@0:    * Construct an ICULocaleService.
michael@0:    */
michael@0:   ICULocaleService();
michael@0: 
michael@0:   /**
michael@0:    * Construct an ICULocaleService with a name (useful for debugging).
michael@0:    */
michael@0:   ICULocaleService(const UnicodeString& name);
michael@0: 
michael@0:   /**
michael@0:    * Destructor.
michael@0:    */
michael@0:   virtual ~ICULocaleService();
michael@0: 
michael@0: #if 0
michael@0:   // redeclare because of overload resolution rules?
michael@0:   // no, causes ambiguities since both UnicodeString and Locale have constructors that take a const char*
michael@0:   // need some compiler flag to remove warnings 
michael@0:   UObject* get(const UnicodeString& descriptor, UErrorCode& status) const {
michael@0:     return ICUService::get(descriptor, status);
michael@0:   }
michael@0: 
michael@0:   UObject* get(const UnicodeString& descriptor, UnicodeString* actualReturn, UErrorCode& status) const {
michael@0:     return ICUService::get(descriptor, actualReturn, status);
michael@0:   }
michael@0: #endif
michael@0: 
michael@0:   /**
michael@0:    * Convenience override for callers using locales.  This calls
michael@0:    * get(Locale, int, Locale[]) with KIND_ANY for kind and null for
michael@0:    * actualReturn.
michael@0:    */
michael@0:   UObject* get(const Locale& locale, UErrorCode& status) const;
michael@0: 
michael@0:   /**
michael@0:    * Convenience override for callers using locales.  This calls
michael@0:    * get(Locale, int, Locale[]) with a null actualReturn.
michael@0:    */
michael@0:   UObject* get(const Locale& locale, int32_t kind, UErrorCode& status) const;
michael@0: 
michael@0:   /**
michael@0:    * Convenience override for callers using locales. This calls
michael@0:    * get(Locale, String, Locale[]) with a null kind.
michael@0:    */
michael@0:   UObject* get(const Locale& locale, Locale* actualReturn, UErrorCode& status) const;
michael@0:                    
michael@0:   /**
michael@0:    * Convenience override for callers using locales.  This uses
michael@0:    * createKey(Locale.toString(), kind) to create a key, calls getKey, and then
michael@0:    * if actualReturn is not null, returns the actualResult from
michael@0:    * getKey (stripping any prefix) into a Locale.  
michael@0:    */
michael@0:   UObject* get(const Locale& locale, int32_t kind, Locale* actualReturn, UErrorCode& status) const;
michael@0: 
michael@0:   /**
michael@0:    * Convenience override for callers using locales.  This calls
michael@0:    * registerObject(Object, Locale, int32_t kind, int coverage)
michael@0:    * passing KIND_ANY for the kind, and VISIBLE for the coverage.
michael@0:    */
michael@0:   virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, UErrorCode& status);
michael@0: 
michael@0:   /**
michael@0:    * Convenience function for callers using locales.  This calls
michael@0:    * registerObject(Object, Locale, int kind, int coverage)
michael@0:    * passing VISIBLE for the coverage.
michael@0:    */
michael@0:   virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, int32_t kind, UErrorCode& status);
michael@0: 
michael@0:   /**
michael@0:    * Convenience function for callers using locales.  This  instantiates
michael@0:    * a SimpleLocaleKeyFactory, and registers the factory.
michael@0:    */
michael@0:   virtual URegistryKey registerInstance(UObject* objToAdopt, const Locale& locale, int32_t kind, int32_t coverage, UErrorCode& status);
michael@0: 
michael@0: 
michael@0:   /**
michael@0:    * (Stop compiler from complaining about hidden overrides.)
michael@0:    * Since both UnicodeString and Locale have constructors that take const char*, adding a public
michael@0:    * method that takes UnicodeString causes ambiguity at call sites that use const char*.
michael@0:    * We really need a flag that is understood by all compilers that will suppress the warning about
michael@0:    * hidden overrides.
michael@0:    */
michael@0:   virtual URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& locale, UBool visible, UErrorCode& status);
michael@0: 
michael@0:   /**
michael@0:    * Convenience method for callers using locales.  This returns the standard
michael@0:    * service ID enumeration.
michael@0:    */
michael@0:   virtual StringEnumeration* getAvailableLocales(void) const;
michael@0: 
michael@0:  protected:
michael@0: 
michael@0:   /**
michael@0:    * Return the name of the current fallback locale.  If it has changed since this was
michael@0:    * last accessed, the service cache is cleared.
michael@0:    */
michael@0:   const UnicodeString& validateFallbackLocale() const;
michael@0: 
michael@0:   /**
michael@0:    * Override superclass createKey method.
michael@0:    */
michael@0:   virtual ICUServiceKey* createKey(const UnicodeString* id, UErrorCode& status) const;
michael@0: 
michael@0:   /**
michael@0:    * Additional createKey that takes a kind.
michael@0:    */
michael@0:   virtual ICUServiceKey* createKey(const UnicodeString* id, int32_t kind, UErrorCode& status) const;
michael@0: 
michael@0:   friend class ServiceEnumeration;
michael@0: };
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0:     /* UCONFIG_NO_SERVICE */
michael@0: #endif
michael@0: 
michael@0:     /* ICULSERV_H */
michael@0: #endif
michael@0: