1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /** 4 ******************************************************************************* 5 * Copyright (C) 2001-2011, International Business Machines Corporation. * 6 * All Rights Reserved. * 7 ******************************************************************************* 8 */ 9 10 #ifndef ICUSERV_H 11 #define ICUSERV_H 12 13 #include "unicode/utypes.h" 14 15 #if UCONFIG_NO_SERVICE 16 17 U_NAMESPACE_BEGIN 18 19 /* 20 * Allow the declaration of APIs with pointers to ICUService 21 * even when service is removed from the build. 22 */ 23 class ICUService; 24 25 U_NAMESPACE_END 26 27 #else 28 29 #include "unicode/unistr.h" 30 #include "unicode/locid.h" 31 #include "unicode/umisc.h" 32 33 #include "hash.h" 34 #include "uvector.h" 35 #include "servnotf.h" 36 37 class ICUServiceTest; 38 39 U_NAMESPACE_BEGIN 40 41 class ICUServiceKey; 42 class ICUServiceFactory; 43 class SimpleFactory; 44 class ServiceListener; 45 class ICUService; 46 47 class DNCache; 48 49 /******************************************************************* 50 * ICUServiceKey 51 */ 52 53 /** 54 * <p>ICUServiceKeys are used to communicate with factories to 55 * generate an instance of the service. ICUServiceKeys define how 56 * ids are canonicalized, provide both a current id and a current 57 * descriptor to use in querying the cache and factories, and 58 * determine the fallback strategy.</p> 59 * 60 * <p>ICUServiceKeys provide both a currentDescriptor and a currentID. 61 * The descriptor contains an optional prefix, followed by '/' 62 * and the currentID. Factories that handle complex keys, 63 * for example number format factories that generate multiple 64 * kinds of formatters for the same locale, use the descriptor 65 * to provide a fully unique identifier for the service object, 66 * while using the currentID (in this case, the locale string), 67 * as the visible IDs that can be localized.</p> 68 * 69 * <p>The default implementation of ICUServiceKey has no fallbacks and 70 * has no custom descriptors.</p> 71 */ 72 class U_COMMON_API ICUServiceKey : public UObject { 73 private: 74 const UnicodeString _id; 75 76 protected: 77 static const UChar PREFIX_DELIMITER; 78 79 public: 80 81 /** 82 * <p>Construct a key from an id.</p> 83 * 84 * @param id the ID from which to construct the key. 85 */ 86 ICUServiceKey(const UnicodeString& id); 87 88 /** 89 * <p>Virtual destructor.</p> 90 */ 91 virtual ~ICUServiceKey(); 92 93 /** 94 * <p>Return the original ID used to construct this key.</p> 95 * 96 * @return the ID used to construct this key. 97 */ 98 virtual const UnicodeString& getID() const; 99 100 /** 101 * <p>Return the canonical version of the original ID. This implementation 102 * appends the original ID to result. Result is returned as a convenience.</p> 103 * 104 * @param result the output parameter to which the id will be appended. 105 * @return the modified result. 106 */ 107 virtual UnicodeString& canonicalID(UnicodeString& result) const; 108 109 /** 110 * <p>Return the (canonical) current ID. This implementation appends 111 * the canonical ID to result. Result is returned as a convenience.</p> 112 * 113 * @param result the output parameter to which the current id will be appended. 114 * @return the modified result. 115 */ 116 virtual UnicodeString& currentID(UnicodeString& result) const; 117 118 /** 119 * <p>Return the current descriptor. This implementation appends 120 * the current descriptor to result. Result is returned as a convenience.</p> 121 * 122 * <p>The current descriptor is used to fully 123 * identify an instance of the service in the cache. A 124 * factory may handle all descriptors for an ID, or just a 125 * particular descriptor. The factory can either parse the 126 * descriptor or use custom API on the key in order to 127 * instantiate the service.</p> 128 * 129 * @param result the output parameter to which the current id will be appended. 130 * @return the modified result. 131 */ 132 virtual UnicodeString& currentDescriptor(UnicodeString& result) const; 133 134 /** 135 * <p>If the key has a fallback, modify the key and return true, 136 * otherwise return false. The current ID will change if there 137 * is a fallback. No currentIDs should be repeated, and fallback 138 * must eventually return false. This implementation has no fallbacks 139 * and always returns false.</p> 140 * 141 * @return TRUE if the ICUServiceKey changed to a valid fallback value. 142 */ 143 virtual UBool fallback(); 144 145 /** 146 * <p>Return TRUE if a key created from id matches, or would eventually 147 * fallback to match, the canonical ID of this ICUServiceKey.</p> 148 * 149 * @param id the id to test. 150 * @return TRUE if this ICUServiceKey's canonical ID is a fallback of id. 151 */ 152 virtual UBool isFallbackOf(const UnicodeString& id) const; 153 154 /** 155 * <p>Return the prefix. This implementation leaves result unchanged. 156 * Result is returned as a convenience.</p> 157 * 158 * @param result the output parameter to which the prefix will be appended. 159 * @return the modified result. 160 */ 161 virtual UnicodeString& prefix(UnicodeString& result) const; 162 163 /** 164 * <p>A utility to parse the prefix out of a descriptor string. Only 165 * the (undelimited) prefix, if any, remains in result. Result is returned as a 166 * convenience.</p> 167 * 168 * @param result an input/output parameter that on entry is a descriptor, and 169 * on exit is the prefix of that descriptor. 170 * @return the modified result. 171 */ 172 static UnicodeString& parsePrefix(UnicodeString& result); 173 174 /** 175 * <p>A utility to parse the suffix out of a descriptor string. Only 176 * the (undelimited) suffix, if any, remains in result. Result is returned as a 177 * convenience.</p> 178 * 179 * @param result an input/output parameter that on entry is a descriptor, and 180 * on exit is the suffix of that descriptor. 181 * @return the modified result. 182 */ 183 static UnicodeString& parseSuffix(UnicodeString& result); 184 185 public: 186 /** 187 * UObject RTTI boilerplate. 188 */ 189 static UClassID U_EXPORT2 getStaticClassID(); 190 191 /** 192 * UObject RTTI boilerplate. 193 */ 194 virtual UClassID getDynamicClassID() const; 195 196 #ifdef SERVICE_DEBUG 197 public: 198 virtual UnicodeString& debug(UnicodeString& result) const; 199 virtual UnicodeString& debugClass(UnicodeString& result) const; 200 #endif 201 202 }; 203 204 /******************************************************************* 205 * ICUServiceFactory 206 */ 207 208 /** 209 * <p>An implementing ICUServiceFactory generates the service objects maintained by the 210 * service. A factory generates a service object from a key, 211 * updates id->factory mappings, and returns the display name for 212 * a supported id.</p> 213 */ 214 class U_COMMON_API ICUServiceFactory : public UObject { 215 public: 216 virtual ~ICUServiceFactory(); 217 218 /** 219 * <p>Create a service object from the key, if this factory 220 * supports the key. Otherwise, return NULL.</p> 221 * 222 * <p>If the factory supports the key, then it can call 223 * the service's getKey(ICUServiceKey, String[], ICUServiceFactory) method 224 * passing itself as the factory to get the object that 225 * the service would have created prior to the factory's 226 * registration with the service. This can change the 227 * key, so any information required from the key should 228 * be extracted before making such a callback.</p> 229 * 230 * @param key the service key. 231 * @param service the service with which this factory is registered. 232 * @param status the error code status. 233 * @return the service object, or NULL if the factory does not support the key. 234 */ 235 virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const = 0; 236 237 /** 238 * <p>Update result to reflect the IDs (not descriptors) that this 239 * factory publicly handles. Result contains mappings from ID to 240 * factory. On entry it will contain all (visible) mappings from 241 * previously-registered factories.</p> 242 * 243 * <p>This function, together with getDisplayName, are used to 244 * support ICUService::getDisplayNames. The factory determines 245 * which IDs (of those it supports) it will make visible, and of 246 * those, which it will provide localized display names for. In 247 * most cases it will register mappings from all IDs it supports 248 * to itself.</p> 249 * 250 * @param result the mapping table to update. 251 * @param status the error code status. 252 */ 253 virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const = 0; 254 255 /** 256 * <p>Return, in result, the display name of the id in the provided locale. 257 * This is an id, not a descriptor. If the id is 258 * not visible, sets result to bogus. If the 259 * incoming result is bogus, it remains bogus. Result is returned as a 260 * convenience. Results are not defined if id is not one supported by this 261 * factory.</p> 262 * 263 * @param id a visible id supported by this factory. 264 * @param locale the locale for which to generate the corresponding localized display name. 265 * @param result output parameter to hold the display name. 266 * @return result. 267 */ 268 virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const = 0; 269 }; 270 271 /* 272 ****************************************************************** 273 */ 274 275 /** 276 * <p>A default implementation of factory. This provides default 277 * implementations for subclasses, and implements a singleton 278 * factory that matches a single ID and returns a single 279 * (possibly deferred-initialized) instance. This implements 280 * updateVisibleIDs to add a mapping from its ID to itself 281 * if visible is true, or to remove any existing mapping 282 * for its ID if visible is false. No localization of display 283 * names is performed.</p> 284 */ 285 class U_COMMON_API SimpleFactory : public ICUServiceFactory { 286 protected: 287 UObject* _instance; 288 const UnicodeString _id; 289 const UBool _visible; 290 291 public: 292 /** 293 * <p>Construct a SimpleFactory that maps a single ID to a single 294 * service instance. If visible is TRUE, the ID will be visible. 295 * The instance must not be NULL. The SimpleFactory will adopt 296 * the instance, which must not be changed subsequent to this call.</p> 297 * 298 * @param instanceToAdopt the service instance to adopt. 299 * @param id the ID to assign to this service instance. 300 * @param visible if TRUE, the ID will be visible. 301 */ 302 SimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible = TRUE); 303 304 /** 305 * <p>Destructor.</p> 306 */ 307 virtual ~SimpleFactory(); 308 309 /** 310 * <p>This implementation returns a clone of the service instance if the factory's ID is equal to 311 * the key's currentID. Service and prefix are ignored.</p> 312 * 313 * @param key the service key. 314 * @param service the service with which this factory is registered. 315 * @param status the error code status. 316 * @return the service object, or NULL if the factory does not support the key. 317 */ 318 virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const; 319 320 /** 321 * <p>This implementation adds a mapping from ID -> this to result if visible is TRUE, 322 * otherwise it removes ID from result.</p> 323 * 324 * @param result the mapping table to update. 325 * @param status the error code status. 326 */ 327 virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const; 328 329 /** 330 * <p>This implementation returns the factory ID if it equals id and visible is TRUE, 331 * otherwise it returns the empty string. (This implementation provides 332 * no localized id information.)</p> 333 * 334 * @param id a visible id supported by this factory. 335 * @param locale the locale for which to generate the corresponding localized display name. 336 * @param result output parameter to hold the display name. 337 * @return result. 338 */ 339 virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const; 340 341 public: 342 /** 343 * UObject RTTI boilerplate. 344 */ 345 static UClassID U_EXPORT2 getStaticClassID(); 346 347 /** 348 * UObject RTTI boilerplate. 349 */ 350 virtual UClassID getDynamicClassID() const; 351 352 #ifdef SERVICE_DEBUG 353 public: 354 virtual UnicodeString& debug(UnicodeString& toAppendTo) const; 355 virtual UnicodeString& debugClass(UnicodeString& toAppendTo) const; 356 #endif 357 358 }; 359 360 /* 361 ****************************************************************** 362 */ 363 364 /** 365 * <p>ServiceListener is the listener that ICUService provides by default. 366 * ICUService will notifiy this listener when factories are added to 367 * or removed from the service. Subclasses can provide 368 * different listener interfaces that extend EventListener, and modify 369 * acceptsListener and notifyListener as appropriate.</p> 370 */ 371 class U_COMMON_API ServiceListener : public EventListener { 372 public: 373 virtual ~ServiceListener(); 374 375 /** 376 * <p>This method is called when the service changes. At the time of the 377 * call this listener is registered with the service. It must 378 * not modify the notifier in the context of this call.</p> 379 * 380 * @param service the service that changed. 381 */ 382 virtual void serviceChanged(const ICUService& service) const = 0; 383 384 public: 385 /** 386 * UObject RTTI boilerplate. 387 */ 388 static UClassID U_EXPORT2 getStaticClassID(); 389 390 /** 391 * UObject RTTI boilerplate. 392 */ 393 virtual UClassID getDynamicClassID() const; 394 395 }; 396 397 /* 398 ****************************************************************** 399 */ 400 401 /** 402 * <p>A StringPair holds a displayName/ID pair. ICUService uses it 403 * as the array elements returned by getDisplayNames. 404 */ 405 class U_COMMON_API StringPair : public UMemory { 406 public: 407 /** 408 * <p>The display name of the pair.</p> 409 */ 410 const UnicodeString displayName; 411 412 /** 413 * <p>The ID of the pair.</p> 414 */ 415 const UnicodeString id; 416 417 /** 418 * <p>Creates a string pair from a displayName and an ID.</p> 419 * 420 * @param displayName the displayName. 421 * @param id the ID. 422 * @param status the error code status. 423 * @return a StringPair if the creation was successful, otherwise NULL. 424 */ 425 static StringPair* create(const UnicodeString& displayName, 426 const UnicodeString& id, 427 UErrorCode& status); 428 429 /** 430 * <p>Return TRUE if either string of the pair is bogus.</p> 431 * @return TRUE if either string of the pair is bogus. 432 */ 433 UBool isBogus() const; 434 435 private: 436 StringPair(const UnicodeString& displayName, const UnicodeString& id); 437 }; 438 439 /******************************************************************* 440 * ICUService 441 */ 442 443 /** 444 * <p>A Service provides access to service objects that implement a 445 * particular service, e.g. transliterators. Users provide a String 446 * id (for example, a locale string) to the service, and get back an 447 * object for that id. Service objects can be any kind of object. A 448 * new service object is returned for each query. The caller is 449 * responsible for deleting it.</p> 450 * 451 * <p>Services 'canonicalize' the query ID and use the canonical ID to 452 * query for the service. The service also defines a mechanism to 453 * 'fallback' the ID multiple times. Clients can optionally request 454 * the actual ID that was matched by a query when they use an ID to 455 * retrieve a service object.</p> 456 * 457 * <p>Service objects are instantiated by ICUServiceFactory objects 458 * registered with the service. The service queries each 459 * ICUServiceFactory in turn, from most recently registered to 460 * earliest registered, until one returns a service object. If none 461 * responds with a service object, a fallback ID is generated, and the 462 * process repeats until a service object is returned or until the ID 463 * has no further fallbacks.</p> 464 * 465 * <p>In ICU 2.4, UObject (the base class of service instances) does 466 * not define a polymorphic clone function. ICUService uses clones to 467 * manage ownership. Thus, for now, ICUService defines an abstract 468 * method, cloneInstance, that clients must implement to create clones 469 * of the service instances. This may change in future releases of 470 * ICU.</p> 471 * 472 * <p>ICUServiceFactories can be dynamically registered and 473 * unregistered with the service. When registered, an 474 * ICUServiceFactory is installed at the head of the factory list, and 475 * so gets 'first crack' at any keys or fallback keys. When 476 * unregistered, it is removed from the service and can no longer be 477 * located through it. Service objects generated by this factory and 478 * held by the client are unaffected.</p> 479 * 480 * <p>If a service has variants (e.g., the different variants of 481 * BreakIterator) an ICUServiceFactory can use the prefix of the 482 * ICUServiceKey to determine the variant of a service to generate. 483 * If it does not support all variants, it can request 484 * previously-registered factories to handle the ones it does not 485 * support.</p> 486 * 487 * <p>ICUService uses ICUServiceKeys to query factories and perform 488 * fallback. The ICUServiceKey defines the canonical form of the ID, 489 * and implements the fallback strategy. Custom ICUServiceKeys can be 490 * defined that parse complex IDs into components that 491 * ICUServiceFactories can more easily use. The ICUServiceKey can 492 * cache the results of this parsing to save repeated effort. 493 * ICUService provides convenience APIs that take UnicodeStrings and 494 * generate default ICUServiceKeys for use in querying.</p> 495 * 496 * <p>ICUService provides API to get the list of IDs publicly 497 * supported by the service (although queries aren't restricted to 498 * this list). This list contains only 'simple' IDs, and not fully 499 * unique IDs. ICUServiceFactories are associated with each simple ID 500 * and the responsible factory can also return a human-readable 501 * localized version of the simple ID, for use in user interfaces. 502 * ICUService can also provide an array of the all the localized 503 * visible IDs and their corresponding internal IDs.</p> 504 * 505 * <p>ICUService implements ICUNotifier, so that clients can register 506 * to receive notification when factories are added or removed from 507 * the service. ICUService provides a default EventListener 508 * subinterface, ServiceListener, which can be registered with the 509 * service. When the service changes, the ServiceListener's 510 * serviceChanged method is called with the service as the 511 * argument.</p> 512 * 513 * <p>The ICUService API is both rich and generic, and it is expected 514 * that most implementations will statically 'wrap' ICUService to 515 * present a more appropriate API-- for example, to declare the type 516 * of the objects returned from get, to limit the factories that can 517 * be registered with the service, or to define their own listener 518 * interface with a custom callback method. They might also customize 519 * ICUService by overriding it, for example, to customize the 520 * ICUServiceKey and fallback strategy. ICULocaleService is a 521 * subclass of ICUService that uses Locale names as IDs and uses 522 * ICUServiceKeys that implement the standard resource bundle fallback 523 * strategy. Most clients will wish to subclass it instead of 524 * ICUService.</p> 525 */ 526 class U_COMMON_API ICUService : public ICUNotifier { 527 protected: 528 /** 529 * Name useful for debugging. 530 */ 531 const UnicodeString name; 532 533 private: 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