/**

 *******************************************************************************

 * Copyright (C) 2001-2005, 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 "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

 */

/**

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>The default implementation of ICUServiceKey has no fallbacks and

 * has no custom descriptors.</p> 

 */

class U_COMMON_API ICUServiceKey : public UObject {

 private: 

  const UnicodeString _id;

 protected:

  static const UChar PREFIX_DELIMITER;

 public:

  /**

   * <p>Construct a key from an id.</p>

   *

   * @param id the ID from which to construct the key.

   */

  ICUServiceKey(const UnicodeString& id);

  /**

   * <p>Virtual destructor.</p>

   */

  virtual ~ICUServiceKey();

 /**

  * <p>Return the original ID used to construct this key.</p>

  *

  * @return the ID used to construct this key.

  */

  virtual const UnicodeString& getID() const;

 /**

  * <p>Return the canonical version of the original ID.  This implementation

  * appends the original ID to result.  Result is returned as a convenience.</p>

  *

  * @param result the output parameter to which the id will be appended.

  * @return the modified result.

  */

  virtual UnicodeString& canonicalID(UnicodeString& result) const;

 /**

  * <p>Return the (canonical) current ID.  This implementation appends

  * the canonical ID to result.  Result is returned as a convenience.</p>

  *

  * @param result the output parameter to which the current id will be appended.

  * @return the modified result.  

  */

  virtual UnicodeString& currentID(UnicodeString& result) const;

 /**

  * <p>Return the current descriptor.  This implementation appends

  * the current descriptor to result.  Result is returned as a convenience.</p>

  *

  * <p>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.</p>

  *

  * @param result the output parameter to which the current id will be appended.

  * @return the modified result.  

  */

  virtual UnicodeString& currentDescriptor(UnicodeString& result) const;

 /**

  * <p>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.</p>

  *

  * @return TRUE if the ICUServiceKey changed to a valid fallback value.

  */

  virtual UBool fallback();

 /**

  * <p>Return TRUE if a key created from id matches, or would eventually

  * fallback to match, the canonical ID of this ICUServiceKey.</p>

  *

  * @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;

 /**

  * <p>Return the prefix.  This implementation leaves result unchanged.

  * Result is returned as a convenience.</p>

  *

  * @param result the output parameter to which the prefix will be appended.

  * @return the modified result.

  */

  virtual UnicodeString& prefix(UnicodeString& result) const;

 /**

  * <p>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.</p>

  *

  * @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);

  /**

  * <p>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.</p>

  *

  * @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;

#ifdef SERVICE_DEBUG

 public:

  virtual UnicodeString& debug(UnicodeString& result) const;

  virtual UnicodeString& debugClass(UnicodeString& result) const;

#endif

};

 /*******************************************************************

  * ICUServiceFactory

  */

 /**

  * <p>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.</p>

  */

class U_COMMON_API ICUServiceFactory : public UObject {

 public:

    /**

     * <p>Create a service object from the key, if this factory

     * supports the key.  Otherwise, return NULL.</p>

     *

     * <p>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.</p>

     *

     * @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 NULL if the factory does not support the key.

     */

    virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const = 0;

    /**

     * <p>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.</p>

     *

     * <p>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.</p>

     *

     * @param result the mapping table to update.

     * @param status the error code status.

     */

    virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const = 0;

    /**

     * <p>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.</p>

     *

     * @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;

};

/*

 ******************************************************************

 */

 /**

  * <p>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.</p>

  */

class U_COMMON_API SimpleFactory : public ICUServiceFactory {

 protected:

  UObject* _instance;

  const UnicodeString _id;

  const UBool _visible;

 public:

  /**

   * <p>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 NULL.  The SimpleFactory will adopt

   * the instance, which must not be changed subsequent to this call.</p>

   *

   * @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);

  /**

   * <p>Destructor.</p>

   */

  virtual ~SimpleFactory();

  /**

   * <p>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.</p>

   *

   * @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 NULL if the factory does not support the key.

   */

  virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;

  /**

   * <p>This implementation adds a mapping from ID -> this to result if visible is TRUE, 

   * otherwise it removes ID from result.</p>

   *

   * @param result the mapping table to update.

   * @param status the error code status.

   */

  virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;

  /**

   * <p>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.)</p>

   *

   * @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;

public:

 /**

  * UObject RTTI boilerplate.

  */

  static UClassID U_EXPORT2 getStaticClassID();

 /**

  * UObject RTTI boilerplate.

  */

  virtual UClassID getDynamicClassID() const;

#ifdef SERVICE_DEBUG

 public:

  virtual UnicodeString& debug(UnicodeString& toAppendTo) const;

  virtual UnicodeString& debugClass(UnicodeString& toAppendTo) const;

#endif

};

/*

 ******************************************************************

 */

/**

 * <p>ServiceListener is the listener that ICUService provides by default.

 * ICUService will notifiy 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.</p>

 */

class U_COMMON_API ServiceListener : public EventListener {

public:

    /**

     * <p>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.</p>

     * 

     * @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;

};

/*

 ******************************************************************

 */

/**

 * <p>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:

  /**

   * <p>The display name of the pair.</p>

   */

  const UnicodeString displayName;

  /**

   * <p>The ID of the pair.</p>

   */

  const UnicodeString id;

  /**

   * <p>Creates a string pair from a displayName and an ID.</p>

   *

   * @param displayName the displayName.

   * @param id the ID.

   * @param status the error code status.

   * @return a StringPair if the creation was successful, otherwise NULL.

   */

  static StringPair* create(const UnicodeString& displayName, 

                            const UnicodeString& id,

                            UErrorCode& status);

  /**

   * <p>Return TRUE if either string of the pair is bogus.</p>

   * @return TRUE if either string of the pair is bogus.

   */

  UBool isBogus() const;

private:

  StringPair(const UnicodeString& displayName, const UnicodeString& id);

};

/**

 * Deleter for StringPairs

 */

U_CAPI void U_EXPORT2

userv_deleteStringPair(void *obj);

/**

 * Opaque type returned by registerInstance and registerFactory.

 */

typedef const void* URegistryKey;

/*******************************************************************

 * ICUService

 */

 /**

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>