• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /**
2  *******************************************************************************
3  * Copyright (C) 2001-2007, International Business Machines Corporation.       *
4  * All Rights Reserved.                                                        *
5  *******************************************************************************
6  */
7 
8 #ifndef ICUSERV_H
9 #define ICUSERV_H
10 
11 #include "unicode/utypes.h"
12 
13 #if UCONFIG_NO_SERVICE
14 
15 U_NAMESPACE_BEGIN
16 
17 /*
18  * Allow the declaration of APIs with pointers to ICUService
19  * even when service is removed from the build.
20  */
21 class ICUService;
22 
23 U_NAMESPACE_END
24 
25 #else
26 
27 #include "unicode/unistr.h"
28 #include "unicode/locid.h"
29 #include "unicode/umisc.h"
30 
31 #include "hash.h"
32 #include "uvector.h"
33 #include "servnotf.h"
34 
35 class ICUServiceTest;
36 
37 U_NAMESPACE_BEGIN
38 
39 class ICUServiceKey;
40 class ICUServiceFactory;
41 class SimpleFactory;
42 class ServiceListener;
43 class ICUService;
44 
45 class DNCache;
46 
47 /*******************************************************************
48  * ICUServiceKey
49  */
50 
51 /**
52  * <p>ICUServiceKeys are used to communicate with factories to
53  * generate an instance of the service.  ICUServiceKeys define how
54  * ids are canonicalized, provide both a current id and a current
55  * descriptor to use in querying the cache and factories, and
56  * determine the fallback strategy.</p>
57  *
58  * <p>ICUServiceKeys provide both a currentDescriptor and a currentID.
59  * The descriptor contains an optional prefix, followed by '/'
60  * and the currentID.  Factories that handle complex keys,
61  * for example number format factories that generate multiple
62  * kinds of formatters for the same locale, use the descriptor
63  * to provide a fully unique identifier for the service object,
64  * while using the currentID (in this case, the locale string),
65  * as the visible IDs that can be localized.</p>
66  *
67  * <p>The default implementation of ICUServiceKey has no fallbacks and
68  * has no custom descriptors.</p>
69  */
70 class U_COMMON_API ICUServiceKey : public UObject {
71  private:
72   const UnicodeString _id;
73 
74  protected:
75   static const UChar PREFIX_DELIMITER;
76 
77  public:
78 
79   /**
80    * <p>Construct a key from an id.</p>
81    *
82    * @param id the ID from which to construct the key.
83    */
84   ICUServiceKey(const UnicodeString& id);
85 
86   /**
87    * <p>Virtual destructor.</p>
88    */
89   virtual ~ICUServiceKey();
90 
91  /**
92   * <p>Return the original ID used to construct this key.</p>
93   *
94   * @return the ID used to construct this key.
95   */
96   virtual const UnicodeString& getID() const;
97 
98  /**
99   * <p>Return the canonical version of the original ID.  This implementation
100   * appends the original ID to result.  Result is returned as a convenience.</p>
101   *
102   * @param result the output parameter to which the id will be appended.
103   * @return the modified result.
104   */
105   virtual UnicodeString& canonicalID(UnicodeString& result) const;
106 
107  /**
108   * <p>Return the (canonical) current ID.  This implementation appends
109   * the canonical ID to result.  Result is returned as a convenience.</p>
110   *
111   * @param result the output parameter to which the current id will be appended.
112   * @return the modified result.
113   */
114   virtual UnicodeString& currentID(UnicodeString& result) const;
115 
116  /**
117   * <p>Return the current descriptor.  This implementation appends
118   * the current descriptor to result.  Result is returned as a convenience.</p>
119   *
120   * <p>The current descriptor is used to fully
121   * identify an instance of the service in the cache.  A
122   * factory may handle all descriptors for an ID, or just a
123   * particular descriptor.  The factory can either parse the
124   * descriptor or use custom API on the key in order to
125   * instantiate the service.</p>
126   *
127   * @param result the output parameter to which the current id will be appended.
128   * @return the modified result.
129   */
130   virtual UnicodeString& currentDescriptor(UnicodeString& result) const;
131 
132  /**
133   * <p>If the key has a fallback, modify the key and return true,
134   * otherwise return false.  The current ID will change if there
135   * is a fallback.  No currentIDs should be repeated, and fallback
136   * must eventually return false.  This implementation has no fallbacks
137   * and always returns false.</p>
138   *
139   * @return TRUE if the ICUServiceKey changed to a valid fallback value.
140   */
141   virtual UBool fallback();
142 
143  /**
144   * <p>Return TRUE if a key created from id matches, or would eventually
145   * fallback to match, the canonical ID of this ICUServiceKey.</p>
146   *
147   * @param id the id to test.
148   * @return TRUE if this ICUServiceKey's canonical ID is a fallback of id.
149   */
150   virtual UBool isFallbackOf(const UnicodeString& id) const;
151 
152  /**
153   * <p>Return the prefix.  This implementation leaves result unchanged.
154   * Result is returned as a convenience.</p>
155   *
156   * @param result the output parameter to which the prefix will be appended.
157   * @return the modified result.
158   */
159   virtual UnicodeString& prefix(UnicodeString& result) const;
160 
161  /**
162   * <p>A utility to parse the prefix out of a descriptor string.  Only
163   * the (undelimited) prefix, if any, remains in result.  Result is returned as a
164   * convenience.</p>
165   *
166   * @param result an input/output parameter that on entry is a descriptor, and
167   * on exit is the prefix of that descriptor.
168   * @return the modified result.
169   */
170   static UnicodeString& parsePrefix(UnicodeString& result);
171 
172   /**
173   * <p>A utility to parse the suffix out of a descriptor string.  Only
174   * the (undelimited) suffix, if any, remains in result.  Result is returned as a
175   * convenience.</p>
176   *
177   * @param result an input/output parameter that on entry is a descriptor, and
178   * on exit is the suffix of that descriptor.
179   * @return the modified result.
180   */
181   static UnicodeString& parseSuffix(UnicodeString& result);
182 
183 public:
184   /**
185    * UObject RTTI boilerplate.
186    */
187   static UClassID U_EXPORT2 getStaticClassID();
188 
189   /**
190    * UObject RTTI boilerplate.
191    */
192   virtual UClassID getDynamicClassID() const;
193 
194 #ifdef SERVICE_DEBUG
195  public:
196   virtual UnicodeString& debug(UnicodeString& result) const;
197   virtual UnicodeString& debugClass(UnicodeString& result) const;
198 #endif
199 
200 };
201 
202  /*******************************************************************
203   * ICUServiceFactory
204   */
205 
206  /**
207   * <p>An implementing ICUServiceFactory generates the service objects maintained by the
208   * service.  A factory generates a service object from a key,
209   * updates id->factory mappings, and returns the display name for
210   * a supported id.</p>
211   */
212 class U_COMMON_API ICUServiceFactory : public UObject {
213  public:
214 
215     /**
216      * <p>Create a service object from the key, if this factory
217      * supports the key.  Otherwise, return NULL.</p>
218      *
219      * <p>If the factory supports the key, then it can call
220      * the service's getKey(ICUServiceKey, String[], ICUServiceFactory) method
221      * passing itself as the factory to get the object that
222      * the service would have created prior to the factory's
223      * registration with the service.  This can change the
224      * key, so any information required from the key should
225      * be extracted before making such a callback.</p>
226      *
227      * @param key the service key.
228      * @param service the service with which this factory is registered.
229      * @param status the error code status.
230      * @return the service object, or NULL if the factory does not support the key.
231      */
232     virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const = 0;
233 
234     /**
235      * <p>Update result to reflect the IDs (not descriptors) that this
236      * factory publicly handles.  Result contains mappings from ID to
237      * factory.  On entry it will contain all (visible) mappings from
238      * previously-registered factories.</p>
239      *
240      * <p>This function, together with getDisplayName, are used to
241      * support ICUService::getDisplayNames.  The factory determines
242      * which IDs (of those it supports) it will make visible, and of
243      * those, which it will provide localized display names for.  In
244      * most cases it will register mappings from all IDs it supports
245      * to itself.</p>
246      *
247      * @param result the mapping table to update.
248      * @param status the error code status.
249      */
250     virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const = 0;
251 
252     /**
253      * <p>Return, in result, the display name of the id in the provided locale.
254      * This is an id, not a descriptor.  If the id is
255      * not visible, sets result to bogus.  If the
256      * incoming result is bogus, it remains bogus.  Result is returned as a
257      * convenience.  Results are not defined if id is not one supported by this
258          * factory.</p>
259      *
260      * @param id a visible id supported by this factory.
261      * @param locale the locale for which to generate the corresponding localized display name.
262      * @param result output parameter to hold the display name.
263      * @return result.
264      */
265     virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const = 0;
266 };
267 
268 /*
269  ******************************************************************
270  */
271 
272  /**
273   * <p>A default implementation of factory.  This provides default
274   * implementations for subclasses, and implements a singleton
275   * factory that matches a single ID and returns a single
276   * (possibly deferred-initialized) instance.  This implements
277   * updateVisibleIDs to add a mapping from its ID to itself
278   * if visible is true, or to remove any existing mapping
279   * for its ID if visible is false.  No localization of display
280   * names is performed.</p>
281   */
282 class U_COMMON_API SimpleFactory : public ICUServiceFactory {
283  protected:
284   UObject* _instance;
285   const UnicodeString _id;
286   const UBool _visible;
287 
288  public:
289   /**
290    * <p>Construct a SimpleFactory that maps a single ID to a single
291    * service instance.  If visible is TRUE, the ID will be visible.
292    * The instance must not be NULL.  The SimpleFactory will adopt
293    * the instance, which must not be changed subsequent to this call.</p>
294    *
295    * @param instanceToAdopt the service instance to adopt.
296    * @param id the ID to assign to this service instance.
297    * @param visible if TRUE, the ID will be visible.
298    */
299   SimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible = TRUE);
300 
301   /**
302    * <p>Destructor.</p>
303    */
304   virtual ~SimpleFactory();
305 
306   /**
307    * <p>This implementation returns a clone of the service instance if the factory's ID is equal to
308    * the key's currentID.  Service and prefix are ignored.</p>
309    *
310    * @param key the service key.
311    * @param service the service with which this factory is registered.
312    * @param status the error code status.
313    * @return the service object, or NULL if the factory does not support the key.
314    */
315   virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
316 
317   /**
318    * <p>This implementation adds a mapping from ID -> this to result if visible is TRUE,
319    * otherwise it removes ID from result.</p>
320    *
321    * @param result the mapping table to update.
322    * @param status the error code status.
323    */
324   virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
325 
326   /**
327    * <p>This implementation returns the factory ID if it equals id and visible is TRUE,
328    * otherwise it returns the empty string.  (This implementation provides
329    * no localized id information.)</p>
330    *
331    * @param id a visible id supported by this factory.
332    * @param locale the locale for which to generate the corresponding localized display name.
333    * @param result output parameter to hold the display name.
334    * @return result.
335    */
336   virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const;
337 
338 public:
339  /**
340   * UObject RTTI boilerplate.
341   */
342   static UClassID U_EXPORT2 getStaticClassID();
343 
344  /**
345   * UObject RTTI boilerplate.
346   */
347   virtual UClassID getDynamicClassID() const;
348 
349 #ifdef SERVICE_DEBUG
350  public:
351   virtual UnicodeString& debug(UnicodeString& toAppendTo) const;
352   virtual UnicodeString& debugClass(UnicodeString& toAppendTo) const;
353 #endif
354 
355 };
356 
357 /*
358  ******************************************************************
359  */
360 
361 /**
362  * <p>ServiceListener is the listener that ICUService provides by default.
363  * ICUService will notifiy this listener when factories are added to
364  * or removed from the service.  Subclasses can provide
365  * different listener interfaces that extend EventListener, and modify
366  * acceptsListener and notifyListener as appropriate.</p>
367  */
368 class U_COMMON_API ServiceListener : public EventListener {
369 public:
370     /**
371      * <p>This method is called when the service changes. At the time of the
372      * call this listener is registered with the service.  It must
373      * not modify the notifier in the context of this call.</p>
374      *
375      * @param service the service that changed.
376      */
377     virtual void serviceChanged(const ICUService& service) const = 0;
378 
379 public:
380     /**
381      * UObject RTTI boilerplate.
382      */
383     static UClassID U_EXPORT2 getStaticClassID();
384 
385     /**
386      * UObject RTTI boilerplate.
387      */
388     virtual UClassID getDynamicClassID() const;
389 
390 };
391 
392 /*
393  ******************************************************************
394  */
395 
396 /**
397  * <p>A StringPair holds a displayName/ID pair.  ICUService uses it
398  * as the array elements returned by getDisplayNames.
399  */
400 class U_COMMON_API StringPair : public UMemory {
401 public:
402   /**
403    * <p>The display name of the pair.</p>
404    */
405   const UnicodeString displayName;
406 
407   /**
408    * <p>The ID of the pair.</p>
409    */
410   const UnicodeString id;
411 
412   /**
413    * <p>Creates a string pair from a displayName and an ID.</p>
414    *
415    * @param displayName the displayName.
416    * @param id the ID.
417    * @param status the error code status.
418    * @return a StringPair if the creation was successful, otherwise NULL.
419    */
420   static StringPair* create(const UnicodeString& displayName,
421                             const UnicodeString& id,
422                             UErrorCode& status);
423 
424   /**
425    * <p>Return TRUE if either string of the pair is bogus.</p>
426    * @return TRUE if either string of the pair is bogus.
427    */
428   UBool isBogus() const;
429 
430 private:
431   StringPair(const UnicodeString& displayName, const UnicodeString& id);
432 };
433 
434 /*******************************************************************
435  * ICUService
436  */
437 
438  /**
439  * <p>A Service provides access to service objects that implement a
440  * particular service, e.g. transliterators.  Users provide a String
441  * id (for example, a locale string) to the service, and get back an
442  * object for that id.  Service objects can be any kind of object.  A
443  * new service object is returned for each query. The caller is
444  * responsible for deleting it.</p>
445  *
446  * <p>Services 'canonicalize' the query ID and use the canonical ID to
447  * query for the service.  The service also defines a mechanism to
448  * 'fallback' the ID multiple times.  Clients can optionally request
449  * the actual ID that was matched by a query when they use an ID to
450  * retrieve a service object.</p>
451  *
452  * <p>Service objects are instantiated by ICUServiceFactory objects
453  * registered with the service.  The service queries each
454  * ICUServiceFactory in turn, from most recently registered to
455  * earliest registered, until one returns a service object.  If none
456  * responds with a service object, a fallback ID is generated, and the
457  * process repeats until a service object is returned or until the ID
458  * has no further fallbacks.</p>
459  *
460  * <p>In ICU 2.4, UObject (the base class of service instances) does
461  * not define a polymorphic clone function.  ICUService uses clones to
462  * manage ownership.  Thus, for now, ICUService defines an abstract
463  * method, cloneInstance, that clients must implement to create clones
464  * of the service instances.  This may change in future releases of
465  * ICU.</p>
466  *
467  * <p>ICUServiceFactories can be dynamically registered and
468  * unregistered with the service.  When registered, an
469  * ICUServiceFactory is installed at the head of the factory list, and
470  * so gets 'first crack' at any keys or fallback keys.  When
471  * unregistered, it is removed from the service and can no longer be
472  * located through it.  Service objects generated by this factory and
473  * held by the client are unaffected.</p>
474  *
475  * <p>If a service has variants (e.g., the different variants of
476  * BreakIterator) an ICUServiceFactory can use the prefix of the
477  * ICUServiceKey to determine the variant of a service to generate.
478  * If it does not support all variants, it can request
479  * previously-registered factories to handle the ones it does not
480  * support.</p>
481  *
482  * <p>ICUService uses ICUServiceKeys to query factories and perform
483  * fallback.  The ICUServiceKey defines the canonical form of the ID,
484  * and implements the fallback strategy.  Custom ICUServiceKeys can be
485  * defined that parse complex IDs into components that
486  * ICUServiceFactories can more easily use.  The ICUServiceKey can
487  * cache the results of this parsing to save repeated effort.
488  * ICUService provides convenience APIs that take UnicodeStrings and
489  * generate default ICUServiceKeys for use in querying.</p>
490  *
491  * <p>ICUService provides API to get the list of IDs publicly
492  * supported by the service (although queries aren't restricted to
493  * this list).  This list contains only 'simple' IDs, and not fully
494  * unique IDs.  ICUServiceFactories are associated with each simple ID
495  * and the responsible factory can also return a human-readable
496  * localized version of the simple ID, for use in user interfaces.
497  * ICUService can also provide an array of the all the localized
498  * visible IDs and their corresponding internal IDs.</p>
499  *
500  * <p>ICUService implements ICUNotifier, so that clients can register
501  * to receive notification when factories are added or removed from
502  * the service.  ICUService provides a default EventListener
503  * subinterface, ServiceListener, which can be registered with the
504  * service.  When the service changes, the ServiceListener's
505  * serviceChanged method is called with the service as the
506  * argument.</p>
507  *
508  * <p>The ICUService API is both rich and generic, and it is expected
509  * that most implementations will statically 'wrap' ICUService to
510  * present a more appropriate API-- for example, to declare the type
511  * of the objects returned from get, to limit the factories that can
512  * be registered with the service, or to define their own listener
513  * interface with a custom callback method.  They might also customize
514  * ICUService by overriding it, for example, to customize the
515  * ICUServiceKey and fallback strategy.  ICULocaleService is a
516  * subclass of ICUService that uses Locale names as IDs and uses
517  * ICUServiceKeys that implement the standard resource bundle fallback
518  * strategy.  Most clients will wish to subclass it instead of
519  * ICUService.</p>
520  */
521 class U_COMMON_API ICUService : public ICUNotifier {
522  protected:
523     /**
524      * Name useful for debugging.
525      */
526     const UnicodeString name;
527 
528  private:
529 
530     /**
531      * single lock used by this service.
532      */
533     UMTX lock;
534 
535     /**
536      * Timestamp so iterators can be fail-fast.
537      */
538     uint32_t timestamp;
539 
540     /**
541      * All the factories registered with this service.
542      */
543     UVector* factories;
544 
545     /**
546      * The service cache.
547      */
548     Hashtable* serviceCache;
549 
550     /**
551      * The ID cache.
552      */
553     Hashtable* idCache;
554 
555     /**
556      * The name cache.
557      */
558     DNCache* dnCache;
559 
560     /**
561      * Constructor.
562      */
563  public:
564     /**
565      * <p>Construct a new ICUService.</p>
566      */
567     ICUService();
568 
569     /**
570      * <p>Construct with a name (useful for debugging).</p>
571      *
572      * @param name a name to use in debugging.
573      */
574     ICUService(const UnicodeString& name);
575 
576     /**
577      * <p>Destructor.</p>
578      */
579     virtual ~ICUService();
580 
581     /**
582      * <p>Return the name of this service. This will be the empty string if none was assigned.
583      * Returns result as a convenience.</p>
584      *
585      * @param result an output parameter to contain the name of this service.
586      * @return the name of this service.
587      */
588     UnicodeString& getName(UnicodeString& result) const;
589 
590     /**
591      * <p>Convenience override for get(ICUServiceKey&, UnicodeString*). This uses
592      * createKey to create a key for the provided descriptor.</p>
593      *
594      * @param descriptor the descriptor.
595      * @param status the error code status.
596      * @return the service instance, or NULL.
597      */
598     UObject* get(const UnicodeString& descriptor, UErrorCode& status) const;
599 
600     /**
601      * <p>Convenience override for get(ICUServiceKey&, UnicodeString*).  This uses
602      * createKey to create a key from the provided descriptor.</p>
603      *
604      * @param descriptor the descriptor.
605      * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
606      * @param status the error code status.
607      * @return the service instance, or NULL.
608      */
609     UObject* get(const UnicodeString& descriptor, UnicodeString* actualReturn, UErrorCode& status) const;
610 
611     /**
612      * <p>Convenience override for get(ICUServiceKey&, UnicodeString*).</p>
613      *
614      * @param key the key.
615      * @param status the error code status.
616      * @return the service instance, or NULL.
617      */
618     UObject* getKey(ICUServiceKey& key, UErrorCode& status) const;
619 
620     /**
621      * <p>Given a key, return a service object, and, if actualReturn
622      * is not NULL, the descriptor with which it was found in the
623      * first element of actualReturn.  If no service object matches
624      * this key, returns NULL and leaves actualReturn unchanged.</p>
625      *
626      * <p>This queries the cache using the key's descriptor, and if no
627      * object in the cache matches, tries the key on each
628      * registered factory, in order.  If none generates a service
629      * object for the key, repeats the process with each fallback of
630      * the key, until either a factory returns a service object, or the key
631      * has no fallback.  If no object is found, the result of handleDefault
632      * is returned.</p>
633      *
634      * <p>Subclasses can override this method to further customize the
635      * result before returning it.
636      *
637      * @param key the key.
638      * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
639      * @param status the error code status.
640      * @return the service instance, or NULL.
641      */
642     virtual UObject* getKey(ICUServiceKey& key, UnicodeString* actualReturn, UErrorCode& status) const;
643 
644     /**
645      * <p>This version of getKey is only called by ICUServiceFactories within the scope
646      * of a previous getKey call, to determine what previously-registered factories would
647      * have returned.  For details, see getKey(ICUServiceKey&, UErrorCode&).  Subclasses
648      * should not call it directly, but call through one of the other get functions.</p>
649      *
650      * @param key the key.
651      * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
652      * @param factory the factory making the recursive call.
653      * @param status the error code status.
654      * @return the service instance, or NULL.
655      */
656     UObject* getKey(ICUServiceKey& key, UnicodeString* actualReturn, const ICUServiceFactory* factory, UErrorCode& status) const;
657 
658     /**
659      * <p>Convenience override for getVisibleIDs(String) that passes null
660      * as the fallback, thus returning all visible IDs.</p>
661      *
662      * @param result a vector to hold the returned IDs.
663      * @param status the error code status.
664      * @return the result vector.
665      */
666     UVector& getVisibleIDs(UVector& result, UErrorCode& status) const;
667 
668     /**
669      * <p>Return a snapshot of the visible IDs for this service.  This
670      * list will not change as ICUServiceFactories are added or removed, but the
671      * supported IDs will, so there is no guarantee that all and only
672      * the IDs in the returned list will be visible and supported by the
673      * service in subsequent calls.</p>
674      *
675      * <p>The IDs are returned as pointers to UnicodeStrings.  The
676      * caller owns the IDs.  Previous contents of result are discarded before
677      * new elements, if any, are added.</p>
678      *
679      * <p>matchID is passed to createKey to create a key.  If the key
680      * is not NULL, its isFallbackOf method is used to filter out IDs
681      * that don't match the key or have it as a fallback.</p>
682      *
683      * @param result a vector to hold the returned IDs.
684      * @param matchID an ID used to filter the result, or NULL if all IDs are desired.
685      * @param status the error code status.
686      * @return the result vector.
687      */
688     UVector& getVisibleIDs(UVector& result, const UnicodeString* matchID, UErrorCode& status) const;
689 
690     /**
691      * <p>Convenience override for getDisplayName(const UnicodeString&, const Locale&, UnicodeString&) that
692      * uses the current default locale.</p>
693      *
694      * @param id the ID for which to retrieve the localized displayName.
695      * @param result an output parameter to hold the display name.
696      * @return the modified result.
697      */
698     UnicodeString& getDisplayName(const UnicodeString& id, UnicodeString& result) const;
699 
700     /**
701      * <p>Given a visible ID, return the display name in the requested locale.
702      * If there is no directly supported ID corresponding to this ID, result is
703      * set to bogus.</p>
704      *
705      * @param id the ID for which to retrieve the localized displayName.
706      * @param result an output parameter to hold the display name.
707      * @param locale the locale in which to localize the ID.
708      * @return the modified result.
709      */
710     UnicodeString& getDisplayName(const UnicodeString& id, UnicodeString& result, const Locale& locale) const;
711 
712     /**
713      * <p>Convenience override of getDisplayNames(const Locale&, const UnicodeString*) that
714      * uses the current default Locale as the locale and NULL for
715      * the matchID.</p>
716      *
717      * @param result a vector to hold the returned displayName/id StringPairs.
718      * @param status the error code status.
719      * @return the modified result vector.
720      */
721     UVector& getDisplayNames(UVector& result, UErrorCode& status) const;
722 
723     /**
724      * <p>Convenience override of getDisplayNames(const Locale&, const UnicodeString*) that
725      * uses NULL for the matchID.</p>
726      *
727      * @param result a vector to hold the returned displayName/id StringPairs.
728      * @param locale the locale in which to localize the ID.
729      * @param status the error code status.
730      * @return the modified result vector.
731      */
732     UVector& getDisplayNames(UVector& result, const Locale& locale, UErrorCode& status) const;
733 
734     /**
735      * <p>Return a snapshot of the mapping from display names to visible
736      * IDs for this service.  This set will not change as factories
737      * are added or removed, but the supported IDs will, so there is
738      * no guarantee that all and only the IDs in the returned map will
739      * be visible and supported by the service in subsequent calls,
740      * nor is there any guarantee that the current display names match
741      * those in the result.</p>
742      *
743      * <p>The names are returned as pointers to StringPairs, which
744      * contain both the displayName and the corresponding ID.  The
745      * caller owns the StringPairs.  Previous contents of result are
746      * discarded before new elements, if any, are added.</p>
747      *
748      * <p>matchID is passed to createKey to create a key.  If the key
749      * is not NULL, its isFallbackOf method is used to filter out IDs
750      * that don't match the key or have it as a fallback.</p>
751      *
752      * @param result a vector to hold the returned displayName/id StringPairs.
753      * @param locale the locale in which to localize the ID.
754      * @param matchID an ID used to filter the result, or NULL if all IDs are desired.
755      * @param status the error code status.
756      * @return the result vector.  */
757     UVector& getDisplayNames(UVector& result,
758                              const Locale& locale,
759                              const UnicodeString* matchID,
760                              UErrorCode& status) const;
761 
762     /**
763      * <p>A convenience override of registerInstance(UObject*, const UnicodeString&, UBool)
764      * that defaults visible to TRUE.</p>
765      *
766      * @param objToAdopt the object to register and adopt.
767      * @param id the ID to assign to this object.
768      * @param status the error code status.
769      * @return a registry key that can be passed to unregister to unregister
770      * (and discard) this instance.
771      */
772     URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& id, UErrorCode& status);
773 
774     /**
775      * <p>Register a service instance with the provided ID.  The ID will be
776      * canonicalized.  The canonicalized ID will be returned by
777      * getVisibleIDs if visible is TRUE.  The service instance will be adopted and
778      * must not be modified subsequent to this call.</p>
779      *
780      * <p>This issues a serviceChanged notification to registered listeners.</p>
781      *
782      * <p>This implementation wraps the object using
783      * createSimpleFactory, and calls registerFactory.</p>
784      *
785      * @param objToAdopt the object to register and adopt.
786      * @param id the ID to assign to this object.
787      * @param visible TRUE if getVisibleIDs is to return this ID.
788      * @param status the error code status.
789      * @return a registry key that can be passed to unregister() to unregister
790      * (and discard) this instance.
791      */
792     virtual URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& id, UBool visible, UErrorCode& status);
793 
794     /**
795      * <p>Register an ICUServiceFactory.  Returns a registry key that
796      * can be used to unregister the factory.  The factory
797      * must not be modified subsequent to this call.  The service owns
798      * all registered factories. In case of an error, the factory is
799      * deleted.</p>
800      *
801      * <p>This issues a serviceChanged notification to registered listeners.</p>
802      *
803      * <p>The default implementation accepts all factories.</p>
804      *
805      * @param factoryToAdopt the factory to register and adopt.
806      * @param status the error code status.
807      * @return a registry key that can be passed to unregister to unregister
808      * (and discard) this factory.
809      */
810     virtual URegistryKey registerFactory(ICUServiceFactory* factoryToAdopt, UErrorCode& status);
811 
812     /**
813      * <p>Unregister a factory using a registry key returned by
814      * registerInstance or registerFactory.  After a successful call,
815      * the factory will be removed from the service factory list and
816      * deleted, and the key becomes invalid.</p>
817      *
818      * <p>This issues a serviceChanged notification to registered
819      * listeners.</p>
820      *
821      * @param rkey the registry key.
822      * @param status the error code status.
823      * @return TRUE if the call successfully unregistered the factory.
824      */
825     virtual UBool unregister(URegistryKey rkey, UErrorCode& status);
826 
827     /**
828      * </p>Reset the service to the default factories.  The factory
829      * lock is acquired and then reInitializeFactories is called.</p>
830      *
831      * <p>This issues a serviceChanged notification to registered listeners.</p>
832      */
833     virtual void reset(void);
834 
835     /**
836      * <p>Return TRUE if the service is in its default state.</p>
837      *
838      * <p>The default implementation returns TRUE if there are no
839      * factories registered.</p>
840      */
841     virtual UBool isDefault(void) const;
842 
843     /**
844      * <p>Create a key from an ID.  If ID is NULL, returns NULL.</p>
845      *
846      * <p>The default implementation creates an ICUServiceKey instance.
847      * Subclasses can override to define more useful keys appropriate
848      * to the factories they accept.</p>
849      *
850      * @param a pointer to the ID for which to create a default ICUServiceKey.
851      * @param status the error code status.
852      * @return the ICUServiceKey corresponding to ID, or NULL.
853      */
854     virtual ICUServiceKey* createKey(const UnicodeString* id, UErrorCode& status) const;
855 
856     /**
857      * <p>Clone object so that caller can own the copy.  In ICU2.4, UObject doesn't define
858      * clone, so we need an instance-aware method that knows how to do this.
859      * This is public so factories can call it, but should really be protected.</p>
860      *
861      * @param instance the service instance to clone.
862      * @return a clone of the passed-in instance, or NULL if cloning was unsuccessful.
863      */
864     virtual UObject* cloneInstance(UObject* instance) const = 0;
865 
866 
867     /************************************************************************
868      * Subclassing API
869      */
870 
871  protected:
872 
873     /**
874      * <p>Create a factory that wraps a single service object.  Called by registerInstance.</p>
875      *
876      * <p>The default implementation returns an instance of SimpleFactory.</p>
877      *
878      * @param instanceToAdopt the service instance to adopt.
879      * @param id the ID to assign to this service instance.
880      * @param visible if TRUE, the ID will be visible.
881      * @param status the error code status.
882      * @return an instance of ICUServiceFactory that maps this instance to the provided ID.
883      */
884     virtual ICUServiceFactory* createSimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible, UErrorCode& status);
885 
886     /**
887      * <p>Reinitialize the factory list to its default state.  After this call, isDefault()
888      * must return TRUE.</p>
889      *
890      * <p>This issues a serviceChanged notification to registered listeners.</p>
891      *
892      * <p>The default implementation clears the factory list.
893      * Subclasses can override to provide other default initialization
894      * of the factory list.  Subclasses must not call this method
895      * directly, since it must only be called while holding write
896      * access to the factory list.</p>
897      */
898     virtual void reInitializeFactories(void);
899 
900     /**
901      * <p>Default handler for this service if no factory in the factory list
902      * handled the key passed to getKey.</p>
903      *
904      * <p>The default implementation returns NULL.</p>
905      *
906      * @param key the key.
907      * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
908      * @param status the error code status.
909      * @return the service instance, or NULL.
910      */
911     virtual UObject* handleDefault(const ICUServiceKey& key, UnicodeString* actualReturn, UErrorCode& status) const;
912 
913     /**
914      * <p>Clear caches maintained by this service.</p>
915      *
916      * <p>Subclasses can override if they implement additional caches
917      * that need to be cleared when the service changes.  Subclasses
918      * should generally not call this method directly, as it must only
919      * be called while synchronized on the factory lock.</p>
920      */
921     virtual void clearCaches(void);
922 
923     /**
924      * <p>Return true if the listener is accepted.</p>
925      *
926      * <p>The default implementation accepts the listener if it is
927      * a ServiceListener.  Subclasses can override this to accept
928      * different listeners.</p>
929      *
930      * @param l the listener to test.
931      * @return TRUE if the service accepts the listener.
932      */
933     virtual UBool acceptsListener(const EventListener& l) const;
934 
935     /**
936      * <p>Notify the listener of a service change.</p>
937      *
938      * <p>The default implementation assumes a ServiceListener.
939      * If acceptsListener has been overridden to accept different
940      * listeners, this should be overridden as well.</p>
941      *
942      * @param l the listener to notify.
943      */
944     virtual void notifyListener(EventListener& l) const;
945 
946     /************************************************************************
947      * Utilities for subclasses.
948      */
949 
950     /**
951      * <p>Clear only the service cache.</p>
952      *
953      * <p>This can be called by subclasses when a change affects the service
954      * cache but not the ID caches, e.g., when the default locale changes
955      * the resolution of IDs also changes, requiring the cache to be
956      * flushed, but not the visible IDs themselves.</p>
957      */
958     void clearServiceCache(void);
959 
960     /**
961      * <p>Return a map from visible IDs to factories.
962      * This must only be called when the mutex is held.</p>
963      *
964      * @param status the error code status.
965      * @return a Hashtable containing mappings from visible
966      * IDs to factories.
967      */
968     const Hashtable* getVisibleIDMap(UErrorCode& status) const;
969 
970     /**
971      * <p>Allow subclasses to read the time stamp.</p>
972      *
973      * @return the timestamp.
974      */
975     int32_t getTimestamp(void) const;
976 
977     /**
978      * <p>Return the number of registered factories.</p>
979      *
980      * @return the number of factories registered at the time of the call.
981      */
982     int32_t countFactories(void) const;
983 
984 private:
985 
986     friend class ::ICUServiceTest; // give tests access to countFactories.
987 };
988 
989 U_NAMESPACE_END
990 
991     /* UCONFIG_NO_SERVICE */
992 #endif
993 
994     /* ICUSERV_H */
995 #endif
996 
997