1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/serv.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,994 @@
1.4 +/**
1.5 + *******************************************************************************
1.6 + * Copyright (C) 2001-2011, International Business Machines Corporation. *
1.7 + * All Rights Reserved. *
1.8 + *******************************************************************************
1.9 + */
1.10 +
1.11 +#ifndef ICUSERV_H
1.12 +#define ICUSERV_H
1.13 +
1.14 +#include "unicode/utypes.h"
1.15 +
1.16 +#if UCONFIG_NO_SERVICE
1.17 +
1.18 +U_NAMESPACE_BEGIN
1.19 +
1.20 +/*
1.21 + * Allow the declaration of APIs with pointers to ICUService
1.22 + * even when service is removed from the build.
1.23 + */
1.24 +class ICUService;
1.25 +
1.26 +U_NAMESPACE_END
1.27 +
1.28 +#else
1.29 +
1.30 +#include "unicode/unistr.h"
1.31 +#include "unicode/locid.h"
1.32 +#include "unicode/umisc.h"
1.33 +
1.34 +#include "hash.h"
1.35 +#include "uvector.h"
1.36 +#include "servnotf.h"
1.37 +
1.38 +class ICUServiceTest;
1.39 +
1.40 +U_NAMESPACE_BEGIN
1.41 +
1.42 +class ICUServiceKey;
1.43 +class ICUServiceFactory;
1.44 +class SimpleFactory;
1.45 +class ServiceListener;
1.46 +class ICUService;
1.47 +
1.48 +class DNCache;
1.49 +
1.50 +/*******************************************************************
1.51 + * ICUServiceKey
1.52 + */
1.53 +
1.54 +/**
1.55 + * <p>ICUServiceKeys are used to communicate with factories to
1.56 + * generate an instance of the service. ICUServiceKeys define how
1.57 + * ids are canonicalized, provide both a current id and a current
1.58 + * descriptor to use in querying the cache and factories, and
1.59 + * determine the fallback strategy.</p>
1.60 + *
1.61 + * <p>ICUServiceKeys provide both a currentDescriptor and a currentID.
1.62 + * The descriptor contains an optional prefix, followed by '/'
1.63 + * and the currentID. Factories that handle complex keys,
1.64 + * for example number format factories that generate multiple
1.65 + * kinds of formatters for the same locale, use the descriptor
1.66 + * to provide a fully unique identifier for the service object,
1.67 + * while using the currentID (in this case, the locale string),
1.68 + * as the visible IDs that can be localized.</p>
1.69 + *
1.70 + * <p>The default implementation of ICUServiceKey has no fallbacks and
1.71 + * has no custom descriptors.</p>
1.72 + */
1.73 +class U_COMMON_API ICUServiceKey : public UObject {
1.74 + private:
1.75 + const UnicodeString _id;
1.76 +
1.77 + protected:
1.78 + static const UChar PREFIX_DELIMITER;
1.79 +
1.80 + public:
1.81 +
1.82 + /**
1.83 + * <p>Construct a key from an id.</p>
1.84 + *
1.85 + * @param id the ID from which to construct the key.
1.86 + */
1.87 + ICUServiceKey(const UnicodeString& id);
1.88 +
1.89 + /**
1.90 + * <p>Virtual destructor.</p>
1.91 + */
1.92 + virtual ~ICUServiceKey();
1.93 +
1.94 + /**
1.95 + * <p>Return the original ID used to construct this key.</p>
1.96 + *
1.97 + * @return the ID used to construct this key.
1.98 + */
1.99 + virtual const UnicodeString& getID() const;
1.100 +
1.101 + /**
1.102 + * <p>Return the canonical version of the original ID. This implementation
1.103 + * appends the original ID to result. Result is returned as a convenience.</p>
1.104 + *
1.105 + * @param result the output parameter to which the id will be appended.
1.106 + * @return the modified result.
1.107 + */
1.108 + virtual UnicodeString& canonicalID(UnicodeString& result) const;
1.109 +
1.110 + /**
1.111 + * <p>Return the (canonical) current ID. This implementation appends
1.112 + * the canonical ID to result. Result is returned as a convenience.</p>
1.113 + *
1.114 + * @param result the output parameter to which the current id will be appended.
1.115 + * @return the modified result.
1.116 + */
1.117 + virtual UnicodeString& currentID(UnicodeString& result) const;
1.118 +
1.119 + /**
1.120 + * <p>Return the current descriptor. This implementation appends
1.121 + * the current descriptor to result. Result is returned as a convenience.</p>
1.122 + *
1.123 + * <p>The current descriptor is used to fully
1.124 + * identify an instance of the service in the cache. A
1.125 + * factory may handle all descriptors for an ID, or just a
1.126 + * particular descriptor. The factory can either parse the
1.127 + * descriptor or use custom API on the key in order to
1.128 + * instantiate the service.</p>
1.129 + *
1.130 + * @param result the output parameter to which the current id will be appended.
1.131 + * @return the modified result.
1.132 + */
1.133 + virtual UnicodeString& currentDescriptor(UnicodeString& result) const;
1.134 +
1.135 + /**
1.136 + * <p>If the key has a fallback, modify the key and return true,
1.137 + * otherwise return false. The current ID will change if there
1.138 + * is a fallback. No currentIDs should be repeated, and fallback
1.139 + * must eventually return false. This implementation has no fallbacks
1.140 + * and always returns false.</p>
1.141 + *
1.142 + * @return TRUE if the ICUServiceKey changed to a valid fallback value.
1.143 + */
1.144 + virtual UBool fallback();
1.145 +
1.146 + /**
1.147 + * <p>Return TRUE if a key created from id matches, or would eventually
1.148 + * fallback to match, the canonical ID of this ICUServiceKey.</p>
1.149 + *
1.150 + * @param id the id to test.
1.151 + * @return TRUE if this ICUServiceKey's canonical ID is a fallback of id.
1.152 + */
1.153 + virtual UBool isFallbackOf(const UnicodeString& id) const;
1.154 +
1.155 + /**
1.156 + * <p>Return the prefix. This implementation leaves result unchanged.
1.157 + * Result is returned as a convenience.</p>
1.158 + *
1.159 + * @param result the output parameter to which the prefix will be appended.
1.160 + * @return the modified result.
1.161 + */
1.162 + virtual UnicodeString& prefix(UnicodeString& result) const;
1.163 +
1.164 + /**
1.165 + * <p>A utility to parse the prefix out of a descriptor string. Only
1.166 + * the (undelimited) prefix, if any, remains in result. Result is returned as a
1.167 + * convenience.</p>
1.168 + *
1.169 + * @param result an input/output parameter that on entry is a descriptor, and
1.170 + * on exit is the prefix of that descriptor.
1.171 + * @return the modified result.
1.172 + */
1.173 + static UnicodeString& parsePrefix(UnicodeString& result);
1.174 +
1.175 + /**
1.176 + * <p>A utility to parse the suffix out of a descriptor string. Only
1.177 + * the (undelimited) suffix, if any, remains in result. Result is returned as a
1.178 + * convenience.</p>
1.179 + *
1.180 + * @param result an input/output parameter that on entry is a descriptor, and
1.181 + * on exit is the suffix of that descriptor.
1.182 + * @return the modified result.
1.183 + */
1.184 + static UnicodeString& parseSuffix(UnicodeString& result);
1.185 +
1.186 +public:
1.187 + /**
1.188 + * UObject RTTI boilerplate.
1.189 + */
1.190 + static UClassID U_EXPORT2 getStaticClassID();
1.191 +
1.192 + /**
1.193 + * UObject RTTI boilerplate.
1.194 + */
1.195 + virtual UClassID getDynamicClassID() const;
1.196 +
1.197 +#ifdef SERVICE_DEBUG
1.198 + public:
1.199 + virtual UnicodeString& debug(UnicodeString& result) const;
1.200 + virtual UnicodeString& debugClass(UnicodeString& result) const;
1.201 +#endif
1.202 +
1.203 +};
1.204 +
1.205 + /*******************************************************************
1.206 + * ICUServiceFactory
1.207 + */
1.208 +
1.209 + /**
1.210 + * <p>An implementing ICUServiceFactory generates the service objects maintained by the
1.211 + * service. A factory generates a service object from a key,
1.212 + * updates id->factory mappings, and returns the display name for
1.213 + * a supported id.</p>
1.214 + */
1.215 +class U_COMMON_API ICUServiceFactory : public UObject {
1.216 + public:
1.217 + virtual ~ICUServiceFactory();
1.218 +
1.219 + /**
1.220 + * <p>Create a service object from the key, if this factory
1.221 + * supports the key. Otherwise, return NULL.</p>
1.222 + *
1.223 + * <p>If the factory supports the key, then it can call
1.224 + * the service's getKey(ICUServiceKey, String[], ICUServiceFactory) method
1.225 + * passing itself as the factory to get the object that
1.226 + * the service would have created prior to the factory's
1.227 + * registration with the service. This can change the
1.228 + * key, so any information required from the key should
1.229 + * be extracted before making such a callback.</p>
1.230 + *
1.231 + * @param key the service key.
1.232 + * @param service the service with which this factory is registered.
1.233 + * @param status the error code status.
1.234 + * @return the service object, or NULL if the factory does not support the key.
1.235 + */
1.236 + virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const = 0;
1.237 +
1.238 + /**
1.239 + * <p>Update result to reflect the IDs (not descriptors) that this
1.240 + * factory publicly handles. Result contains mappings from ID to
1.241 + * factory. On entry it will contain all (visible) mappings from
1.242 + * previously-registered factories.</p>
1.243 + *
1.244 + * <p>This function, together with getDisplayName, are used to
1.245 + * support ICUService::getDisplayNames. The factory determines
1.246 + * which IDs (of those it supports) it will make visible, and of
1.247 + * those, which it will provide localized display names for. In
1.248 + * most cases it will register mappings from all IDs it supports
1.249 + * to itself.</p>
1.250 + *
1.251 + * @param result the mapping table to update.
1.252 + * @param status the error code status.
1.253 + */
1.254 + virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const = 0;
1.255 +
1.256 + /**
1.257 + * <p>Return, in result, the display name of the id in the provided locale.
1.258 + * This is an id, not a descriptor. If the id is
1.259 + * not visible, sets result to bogus. If the
1.260 + * incoming result is bogus, it remains bogus. Result is returned as a
1.261 + * convenience. Results are not defined if id is not one supported by this
1.262 + * factory.</p>
1.263 + *
1.264 + * @param id a visible id supported by this factory.
1.265 + * @param locale the locale for which to generate the corresponding localized display name.
1.266 + * @param result output parameter to hold the display name.
1.267 + * @return result.
1.268 + */
1.269 + virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const = 0;
1.270 +};
1.271 +
1.272 +/*
1.273 + ******************************************************************
1.274 + */
1.275 +
1.276 + /**
1.277 + * <p>A default implementation of factory. This provides default
1.278 + * implementations for subclasses, and implements a singleton
1.279 + * factory that matches a single ID and returns a single
1.280 + * (possibly deferred-initialized) instance. This implements
1.281 + * updateVisibleIDs to add a mapping from its ID to itself
1.282 + * if visible is true, or to remove any existing mapping
1.283 + * for its ID if visible is false. No localization of display
1.284 + * names is performed.</p>
1.285 + */
1.286 +class U_COMMON_API SimpleFactory : public ICUServiceFactory {
1.287 + protected:
1.288 + UObject* _instance;
1.289 + const UnicodeString _id;
1.290 + const UBool _visible;
1.291 +
1.292 + public:
1.293 + /**
1.294 + * <p>Construct a SimpleFactory that maps a single ID to a single
1.295 + * service instance. If visible is TRUE, the ID will be visible.
1.296 + * The instance must not be NULL. The SimpleFactory will adopt
1.297 + * the instance, which must not be changed subsequent to this call.</p>
1.298 + *
1.299 + * @param instanceToAdopt the service instance to adopt.
1.300 + * @param id the ID to assign to this service instance.
1.301 + * @param visible if TRUE, the ID will be visible.
1.302 + */
1.303 + SimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible = TRUE);
1.304 +
1.305 + /**
1.306 + * <p>Destructor.</p>
1.307 + */
1.308 + virtual ~SimpleFactory();
1.309 +
1.310 + /**
1.311 + * <p>This implementation returns a clone of the service instance if the factory's ID is equal to
1.312 + * the key's currentID. Service and prefix are ignored.</p>
1.313 + *
1.314 + * @param key the service key.
1.315 + * @param service the service with which this factory is registered.
1.316 + * @param status the error code status.
1.317 + * @return the service object, or NULL if the factory does not support the key.
1.318 + */
1.319 + virtual UObject* create(const ICUServiceKey& key, const ICUService* service, UErrorCode& status) const;
1.320 +
1.321 + /**
1.322 + * <p>This implementation adds a mapping from ID -> this to result if visible is TRUE,
1.323 + * otherwise it removes ID from result.</p>
1.324 + *
1.325 + * @param result the mapping table to update.
1.326 + * @param status the error code status.
1.327 + */
1.328 + virtual void updateVisibleIDs(Hashtable& result, UErrorCode& status) const;
1.329 +
1.330 + /**
1.331 + * <p>This implementation returns the factory ID if it equals id and visible is TRUE,
1.332 + * otherwise it returns the empty string. (This implementation provides
1.333 + * no localized id information.)</p>
1.334 + *
1.335 + * @param id a visible id supported by this factory.
1.336 + * @param locale the locale for which to generate the corresponding localized display name.
1.337 + * @param result output parameter to hold the display name.
1.338 + * @return result.
1.339 + */
1.340 + virtual UnicodeString& getDisplayName(const UnicodeString& id, const Locale& locale, UnicodeString& result) const;
1.341 +
1.342 +public:
1.343 + /**
1.344 + * UObject RTTI boilerplate.
1.345 + */
1.346 + static UClassID U_EXPORT2 getStaticClassID();
1.347 +
1.348 + /**
1.349 + * UObject RTTI boilerplate.
1.350 + */
1.351 + virtual UClassID getDynamicClassID() const;
1.352 +
1.353 +#ifdef SERVICE_DEBUG
1.354 + public:
1.355 + virtual UnicodeString& debug(UnicodeString& toAppendTo) const;
1.356 + virtual UnicodeString& debugClass(UnicodeString& toAppendTo) const;
1.357 +#endif
1.358 +
1.359 +};
1.360 +
1.361 +/*
1.362 + ******************************************************************
1.363 + */
1.364 +
1.365 +/**
1.366 + * <p>ServiceListener is the listener that ICUService provides by default.
1.367 + * ICUService will notifiy this listener when factories are added to
1.368 + * or removed from the service. Subclasses can provide
1.369 + * different listener interfaces that extend EventListener, and modify
1.370 + * acceptsListener and notifyListener as appropriate.</p>
1.371 + */
1.372 +class U_COMMON_API ServiceListener : public EventListener {
1.373 +public:
1.374 + virtual ~ServiceListener();
1.375 +
1.376 + /**
1.377 + * <p>This method is called when the service changes. At the time of the
1.378 + * call this listener is registered with the service. It must
1.379 + * not modify the notifier in the context of this call.</p>
1.380 + *
1.381 + * @param service the service that changed.
1.382 + */
1.383 + virtual void serviceChanged(const ICUService& service) const = 0;
1.384 +
1.385 +public:
1.386 + /**
1.387 + * UObject RTTI boilerplate.
1.388 + */
1.389 + static UClassID U_EXPORT2 getStaticClassID();
1.390 +
1.391 + /**
1.392 + * UObject RTTI boilerplate.
1.393 + */
1.394 + virtual UClassID getDynamicClassID() const;
1.395 +
1.396 +};
1.397 +
1.398 +/*
1.399 + ******************************************************************
1.400 + */
1.401 +
1.402 +/**
1.403 + * <p>A StringPair holds a displayName/ID pair. ICUService uses it
1.404 + * as the array elements returned by getDisplayNames.
1.405 + */
1.406 +class U_COMMON_API StringPair : public UMemory {
1.407 +public:
1.408 + /**
1.409 + * <p>The display name of the pair.</p>
1.410 + */
1.411 + const UnicodeString displayName;
1.412 +
1.413 + /**
1.414 + * <p>The ID of the pair.</p>
1.415 + */
1.416 + const UnicodeString id;
1.417 +
1.418 + /**
1.419 + * <p>Creates a string pair from a displayName and an ID.</p>
1.420 + *
1.421 + * @param displayName the displayName.
1.422 + * @param id the ID.
1.423 + * @param status the error code status.
1.424 + * @return a StringPair if the creation was successful, otherwise NULL.
1.425 + */
1.426 + static StringPair* create(const UnicodeString& displayName,
1.427 + const UnicodeString& id,
1.428 + UErrorCode& status);
1.429 +
1.430 + /**
1.431 + * <p>Return TRUE if either string of the pair is bogus.</p>
1.432 + * @return TRUE if either string of the pair is bogus.
1.433 + */
1.434 + UBool isBogus() const;
1.435 +
1.436 +private:
1.437 + StringPair(const UnicodeString& displayName, const UnicodeString& id);
1.438 +};
1.439 +
1.440 +/*******************************************************************
1.441 + * ICUService
1.442 + */
1.443 +
1.444 + /**
1.445 + * <p>A Service provides access to service objects that implement a
1.446 + * particular service, e.g. transliterators. Users provide a String
1.447 + * id (for example, a locale string) to the service, and get back an
1.448 + * object for that id. Service objects can be any kind of object. A
1.449 + * new service object is returned for each query. The caller is
1.450 + * responsible for deleting it.</p>
1.451 + *
1.452 + * <p>Services 'canonicalize' the query ID and use the canonical ID to
1.453 + * query for the service. The service also defines a mechanism to
1.454 + * 'fallback' the ID multiple times. Clients can optionally request
1.455 + * the actual ID that was matched by a query when they use an ID to
1.456 + * retrieve a service object.</p>
1.457 + *
1.458 + * <p>Service objects are instantiated by ICUServiceFactory objects
1.459 + * registered with the service. The service queries each
1.460 + * ICUServiceFactory in turn, from most recently registered to
1.461 + * earliest registered, until one returns a service object. If none
1.462 + * responds with a service object, a fallback ID is generated, and the
1.463 + * process repeats until a service object is returned or until the ID
1.464 + * has no further fallbacks.</p>
1.465 + *
1.466 + * <p>In ICU 2.4, UObject (the base class of service instances) does
1.467 + * not define a polymorphic clone function. ICUService uses clones to
1.468 + * manage ownership. Thus, for now, ICUService defines an abstract
1.469 + * method, cloneInstance, that clients must implement to create clones
1.470 + * of the service instances. This may change in future releases of
1.471 + * ICU.</p>
1.472 + *
1.473 + * <p>ICUServiceFactories can be dynamically registered and
1.474 + * unregistered with the service. When registered, an
1.475 + * ICUServiceFactory is installed at the head of the factory list, and
1.476 + * so gets 'first crack' at any keys or fallback keys. When
1.477 + * unregistered, it is removed from the service and can no longer be
1.478 + * located through it. Service objects generated by this factory and
1.479 + * held by the client are unaffected.</p>
1.480 + *
1.481 + * <p>If a service has variants (e.g., the different variants of
1.482 + * BreakIterator) an ICUServiceFactory can use the prefix of the
1.483 + * ICUServiceKey to determine the variant of a service to generate.
1.484 + * If it does not support all variants, it can request
1.485 + * previously-registered factories to handle the ones it does not
1.486 + * support.</p>
1.487 + *
1.488 + * <p>ICUService uses ICUServiceKeys to query factories and perform
1.489 + * fallback. The ICUServiceKey defines the canonical form of the ID,
1.490 + * and implements the fallback strategy. Custom ICUServiceKeys can be
1.491 + * defined that parse complex IDs into components that
1.492 + * ICUServiceFactories can more easily use. The ICUServiceKey can
1.493 + * cache the results of this parsing to save repeated effort.
1.494 + * ICUService provides convenience APIs that take UnicodeStrings and
1.495 + * generate default ICUServiceKeys for use in querying.</p>
1.496 + *
1.497 + * <p>ICUService provides API to get the list of IDs publicly
1.498 + * supported by the service (although queries aren't restricted to
1.499 + * this list). This list contains only 'simple' IDs, and not fully
1.500 + * unique IDs. ICUServiceFactories are associated with each simple ID
1.501 + * and the responsible factory can also return a human-readable
1.502 + * localized version of the simple ID, for use in user interfaces.
1.503 + * ICUService can also provide an array of the all the localized
1.504 + * visible IDs and their corresponding internal IDs.</p>
1.505 + *
1.506 + * <p>ICUService implements ICUNotifier, so that clients can register
1.507 + * to receive notification when factories are added or removed from
1.508 + * the service. ICUService provides a default EventListener
1.509 + * subinterface, ServiceListener, which can be registered with the
1.510 + * service. When the service changes, the ServiceListener's
1.511 + * serviceChanged method is called with the service as the
1.512 + * argument.</p>
1.513 + *
1.514 + * <p>The ICUService API is both rich and generic, and it is expected
1.515 + * that most implementations will statically 'wrap' ICUService to
1.516 + * present a more appropriate API-- for example, to declare the type
1.517 + * of the objects returned from get, to limit the factories that can
1.518 + * be registered with the service, or to define their own listener
1.519 + * interface with a custom callback method. They might also customize
1.520 + * ICUService by overriding it, for example, to customize the
1.521 + * ICUServiceKey and fallback strategy. ICULocaleService is a
1.522 + * subclass of ICUService that uses Locale names as IDs and uses
1.523 + * ICUServiceKeys that implement the standard resource bundle fallback
1.524 + * strategy. Most clients will wish to subclass it instead of
1.525 + * ICUService.</p>
1.526 + */
1.527 +class U_COMMON_API ICUService : public ICUNotifier {
1.528 + protected:
1.529 + /**
1.530 + * Name useful for debugging.
1.531 + */
1.532 + const UnicodeString name;
1.533 +
1.534 + private:
1.535 +
1.536 + /**
1.537 + * Timestamp so iterators can be fail-fast.
1.538 + */
1.539 + uint32_t timestamp;
1.540 +
1.541 + /**
1.542 + * All the factories registered with this service.
1.543 + */
1.544 + UVector* factories;
1.545 +
1.546 + /**
1.547 + * The service cache.
1.548 + */
1.549 + Hashtable* serviceCache;
1.550 +
1.551 + /**
1.552 + * The ID cache.
1.553 + */
1.554 + Hashtable* idCache;
1.555 +
1.556 + /**
1.557 + * The name cache.
1.558 + */
1.559 + DNCache* dnCache;
1.560 +
1.561 + /**
1.562 + * Constructor.
1.563 + */
1.564 + public:
1.565 + /**
1.566 + * <p>Construct a new ICUService.</p>
1.567 + */
1.568 + ICUService();
1.569 +
1.570 + /**
1.571 + * <p>Construct with a name (useful for debugging).</p>
1.572 + *
1.573 + * @param name a name to use in debugging.
1.574 + */
1.575 + ICUService(const UnicodeString& name);
1.576 +
1.577 + /**
1.578 + * <p>Destructor.</p>
1.579 + */
1.580 + virtual ~ICUService();
1.581 +
1.582 + /**
1.583 + * <p>Return the name of this service. This will be the empty string if none was assigned.
1.584 + * Returns result as a convenience.</p>
1.585 + *
1.586 + * @param result an output parameter to contain the name of this service.
1.587 + * @return the name of this service.
1.588 + */
1.589 + UnicodeString& getName(UnicodeString& result) const;
1.590 +
1.591 + /**
1.592 + * <p>Convenience override for get(ICUServiceKey&, UnicodeString*). This uses
1.593 + * createKey to create a key for the provided descriptor.</p>
1.594 + *
1.595 + * @param descriptor the descriptor.
1.596 + * @param status the error code status.
1.597 + * @return the service instance, or NULL.
1.598 + */
1.599 + UObject* get(const UnicodeString& descriptor, UErrorCode& status) const;
1.600 +
1.601 + /**
1.602 + * <p>Convenience override for get(ICUServiceKey&, UnicodeString*). This uses
1.603 + * createKey to create a key from the provided descriptor.</p>
1.604 + *
1.605 + * @param descriptor the descriptor.
1.606 + * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
1.607 + * @param status the error code status.
1.608 + * @return the service instance, or NULL.
1.609 + */
1.610 + UObject* get(const UnicodeString& descriptor, UnicodeString* actualReturn, UErrorCode& status) const;
1.611 +
1.612 + /**
1.613 + * <p>Convenience override for get(ICUServiceKey&, UnicodeString*).</p>
1.614 + *
1.615 + * @param key the key.
1.616 + * @param status the error code status.
1.617 + * @return the service instance, or NULL.
1.618 + */
1.619 + UObject* getKey(ICUServiceKey& key, UErrorCode& status) const;
1.620 +
1.621 + /**
1.622 + * <p>Given a key, return a service object, and, if actualReturn
1.623 + * is not NULL, the descriptor with which it was found in the
1.624 + * first element of actualReturn. If no service object matches
1.625 + * this key, returns NULL and leaves actualReturn unchanged.</p>
1.626 + *
1.627 + * <p>This queries the cache using the key's descriptor, and if no
1.628 + * object in the cache matches, tries the key on each
1.629 + * registered factory, in order. If none generates a service
1.630 + * object for the key, repeats the process with each fallback of
1.631 + * the key, until either a factory returns a service object, or the key
1.632 + * has no fallback. If no object is found, the result of handleDefault
1.633 + * is returned.</p>
1.634 + *
1.635 + * <p>Subclasses can override this method to further customize the
1.636 + * result before returning it.
1.637 + *
1.638 + * @param key the key.
1.639 + * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
1.640 + * @param status the error code status.
1.641 + * @return the service instance, or NULL.
1.642 + */
1.643 + virtual UObject* getKey(ICUServiceKey& key, UnicodeString* actualReturn, UErrorCode& status) const;
1.644 +
1.645 + /**
1.646 + * <p>This version of getKey is only called by ICUServiceFactories within the scope
1.647 + * of a previous getKey call, to determine what previously-registered factories would
1.648 + * have returned. For details, see getKey(ICUServiceKey&, UErrorCode&). Subclasses
1.649 + * should not call it directly, but call through one of the other get functions.</p>
1.650 + *
1.651 + * @param key the key.
1.652 + * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
1.653 + * @param factory the factory making the recursive call.
1.654 + * @param status the error code status.
1.655 + * @return the service instance, or NULL.
1.656 + */
1.657 + UObject* getKey(ICUServiceKey& key, UnicodeString* actualReturn, const ICUServiceFactory* factory, UErrorCode& status) const;
1.658 +
1.659 + /**
1.660 + * <p>Convenience override for getVisibleIDs(String) that passes null
1.661 + * as the fallback, thus returning all visible IDs.</p>
1.662 + *
1.663 + * @param result a vector to hold the returned IDs.
1.664 + * @param status the error code status.
1.665 + * @return the result vector.
1.666 + */
1.667 + UVector& getVisibleIDs(UVector& result, UErrorCode& status) const;
1.668 +
1.669 + /**
1.670 + * <p>Return a snapshot of the visible IDs for this service. This
1.671 + * list will not change as ICUServiceFactories are added or removed, but the
1.672 + * supported IDs will, so there is no guarantee that all and only
1.673 + * the IDs in the returned list will be visible and supported by the
1.674 + * service in subsequent calls.</p>
1.675 + *
1.676 + * <p>The IDs are returned as pointers to UnicodeStrings. The
1.677 + * caller owns the IDs. Previous contents of result are discarded before
1.678 + * new elements, if any, are added.</p>
1.679 + *
1.680 + * <p>matchID is passed to createKey to create a key. If the key
1.681 + * is not NULL, its isFallbackOf method is used to filter out IDs
1.682 + * that don't match the key or have it as a fallback.</p>
1.683 + *
1.684 + * @param result a vector to hold the returned IDs.
1.685 + * @param matchID an ID used to filter the result, or NULL if all IDs are desired.
1.686 + * @param status the error code status.
1.687 + * @return the result vector.
1.688 + */
1.689 + UVector& getVisibleIDs(UVector& result, const UnicodeString* matchID, UErrorCode& status) const;
1.690 +
1.691 + /**
1.692 + * <p>Convenience override for getDisplayName(const UnicodeString&, const Locale&, UnicodeString&) that
1.693 + * uses the current default locale.</p>
1.694 + *
1.695 + * @param id the ID for which to retrieve the localized displayName.
1.696 + * @param result an output parameter to hold the display name.
1.697 + * @return the modified result.
1.698 + */
1.699 + UnicodeString& getDisplayName(const UnicodeString& id, UnicodeString& result) const;
1.700 +
1.701 + /**
1.702 + * <p>Given a visible ID, return the display name in the requested locale.
1.703 + * If there is no directly supported ID corresponding to this ID, result is
1.704 + * set to bogus.</p>
1.705 + *
1.706 + * @param id the ID for which to retrieve the localized displayName.
1.707 + * @param result an output parameter to hold the display name.
1.708 + * @param locale the locale in which to localize the ID.
1.709 + * @return the modified result.
1.710 + */
1.711 + UnicodeString& getDisplayName(const UnicodeString& id, UnicodeString& result, const Locale& locale) const;
1.712 +
1.713 + /**
1.714 + * <p>Convenience override of getDisplayNames(const Locale&, const UnicodeString*) that
1.715 + * uses the current default Locale as the locale and NULL for
1.716 + * the matchID.</p>
1.717 + *
1.718 + * @param result a vector to hold the returned displayName/id StringPairs.
1.719 + * @param status the error code status.
1.720 + * @return the modified result vector.
1.721 + */
1.722 + UVector& getDisplayNames(UVector& result, UErrorCode& status) const;
1.723 +
1.724 + /**
1.725 + * <p>Convenience override of getDisplayNames(const Locale&, const UnicodeString*) that
1.726 + * uses NULL for the matchID.</p>
1.727 + *
1.728 + * @param result a vector to hold the returned displayName/id StringPairs.
1.729 + * @param locale the locale in which to localize the ID.
1.730 + * @param status the error code status.
1.731 + * @return the modified result vector.
1.732 + */
1.733 + UVector& getDisplayNames(UVector& result, const Locale& locale, UErrorCode& status) const;
1.734 +
1.735 + /**
1.736 + * <p>Return a snapshot of the mapping from display names to visible
1.737 + * IDs for this service. This set will not change as factories
1.738 + * are added or removed, but the supported IDs will, so there is
1.739 + * no guarantee that all and only the IDs in the returned map will
1.740 + * be visible and supported by the service in subsequent calls,
1.741 + * nor is there any guarantee that the current display names match
1.742 + * those in the result.</p>
1.743 + *
1.744 + * <p>The names are returned as pointers to StringPairs, which
1.745 + * contain both the displayName and the corresponding ID. The
1.746 + * caller owns the StringPairs. Previous contents of result are
1.747 + * discarded before new elements, if any, are added.</p>
1.748 + *
1.749 + * <p>matchID is passed to createKey to create a key. If the key
1.750 + * is not NULL, its isFallbackOf method is used to filter out IDs
1.751 + * that don't match the key or have it as a fallback.</p>
1.752 + *
1.753 + * @param result a vector to hold the returned displayName/id StringPairs.
1.754 + * @param locale the locale in which to localize the ID.
1.755 + * @param matchID an ID used to filter the result, or NULL if all IDs are desired.
1.756 + * @param status the error code status.
1.757 + * @return the result vector. */
1.758 + UVector& getDisplayNames(UVector& result,
1.759 + const Locale& locale,
1.760 + const UnicodeString* matchID,
1.761 + UErrorCode& status) const;
1.762 +
1.763 + /**
1.764 + * <p>A convenience override of registerInstance(UObject*, const UnicodeString&, UBool)
1.765 + * that defaults visible to TRUE.</p>
1.766 + *
1.767 + * @param objToAdopt the object to register and adopt.
1.768 + * @param id the ID to assign to this object.
1.769 + * @param status the error code status.
1.770 + * @return a registry key that can be passed to unregister to unregister
1.771 + * (and discard) this instance.
1.772 + */
1.773 + URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& id, UErrorCode& status);
1.774 +
1.775 + /**
1.776 + * <p>Register a service instance with the provided ID. The ID will be
1.777 + * canonicalized. The canonicalized ID will be returned by
1.778 + * getVisibleIDs if visible is TRUE. The service instance will be adopted and
1.779 + * must not be modified subsequent to this call.</p>
1.780 + *
1.781 + * <p>This issues a serviceChanged notification to registered listeners.</p>
1.782 + *
1.783 + * <p>This implementation wraps the object using
1.784 + * createSimpleFactory, and calls registerFactory.</p>
1.785 + *
1.786 + * @param objToAdopt the object to register and adopt.
1.787 + * @param id the ID to assign to this object.
1.788 + * @param visible TRUE if getVisibleIDs is to return this ID.
1.789 + * @param status the error code status.
1.790 + * @return a registry key that can be passed to unregister() to unregister
1.791 + * (and discard) this instance.
1.792 + */
1.793 + virtual URegistryKey registerInstance(UObject* objToAdopt, const UnicodeString& id, UBool visible, UErrorCode& status);
1.794 +
1.795 + /**
1.796 + * <p>Register an ICUServiceFactory. Returns a registry key that
1.797 + * can be used to unregister the factory. The factory
1.798 + * must not be modified subsequent to this call. The service owns
1.799 + * all registered factories. In case of an error, the factory is
1.800 + * deleted.</p>
1.801 + *
1.802 + * <p>This issues a serviceChanged notification to registered listeners.</p>
1.803 + *
1.804 + * <p>The default implementation accepts all factories.</p>
1.805 + *
1.806 + * @param factoryToAdopt the factory to register and adopt.
1.807 + * @param status the error code status.
1.808 + * @return a registry key that can be passed to unregister to unregister
1.809 + * (and discard) this factory.
1.810 + */
1.811 + virtual URegistryKey registerFactory(ICUServiceFactory* factoryToAdopt, UErrorCode& status);
1.812 +
1.813 + /**
1.814 + * <p>Unregister a factory using a registry key returned by
1.815 + * registerInstance or registerFactory. After a successful call,
1.816 + * the factory will be removed from the service factory list and
1.817 + * deleted, and the key becomes invalid.</p>
1.818 + *
1.819 + * <p>This issues a serviceChanged notification to registered
1.820 + * listeners.</p>
1.821 + *
1.822 + * @param rkey the registry key.
1.823 + * @param status the error code status.
1.824 + * @return TRUE if the call successfully unregistered the factory.
1.825 + */
1.826 + virtual UBool unregister(URegistryKey rkey, UErrorCode& status);
1.827 +
1.828 + /**
1.829 + * </p>Reset the service to the default factories. The factory
1.830 + * lock is acquired and then reInitializeFactories is called.</p>
1.831 + *
1.832 + * <p>This issues a serviceChanged notification to registered listeners.</p>
1.833 + */
1.834 + virtual void reset(void);
1.835 +
1.836 + /**
1.837 + * <p>Return TRUE if the service is in its default state.</p>
1.838 + *
1.839 + * <p>The default implementation returns TRUE if there are no
1.840 + * factories registered.</p>
1.841 + */
1.842 + virtual UBool isDefault(void) const;
1.843 +
1.844 + /**
1.845 + * <p>Create a key from an ID. If ID is NULL, returns NULL.</p>
1.846 + *
1.847 + * <p>The default implementation creates an ICUServiceKey instance.
1.848 + * Subclasses can override to define more useful keys appropriate
1.849 + * to the factories they accept.</p>
1.850 + *
1.851 + * @param a pointer to the ID for which to create a default ICUServiceKey.
1.852 + * @param status the error code status.
1.853 + * @return the ICUServiceKey corresponding to ID, or NULL.
1.854 + */
1.855 + virtual ICUServiceKey* createKey(const UnicodeString* id, UErrorCode& status) const;
1.856 +
1.857 + /**
1.858 + * <p>Clone object so that caller can own the copy. In ICU2.4, UObject doesn't define
1.859 + * clone, so we need an instance-aware method that knows how to do this.
1.860 + * This is public so factories can call it, but should really be protected.</p>
1.861 + *
1.862 + * @param instance the service instance to clone.
1.863 + * @return a clone of the passed-in instance, or NULL if cloning was unsuccessful.
1.864 + */
1.865 + virtual UObject* cloneInstance(UObject* instance) const = 0;
1.866 +
1.867 +
1.868 + /************************************************************************
1.869 + * Subclassing API
1.870 + */
1.871 +
1.872 + protected:
1.873 +
1.874 + /**
1.875 + * <p>Create a factory that wraps a single service object. Called by registerInstance.</p>
1.876 + *
1.877 + * <p>The default implementation returns an instance of SimpleFactory.</p>
1.878 + *
1.879 + * @param instanceToAdopt the service instance to adopt.
1.880 + * @param id the ID to assign to this service instance.
1.881 + * @param visible if TRUE, the ID will be visible.
1.882 + * @param status the error code status.
1.883 + * @return an instance of ICUServiceFactory that maps this instance to the provided ID.
1.884 + */
1.885 + virtual ICUServiceFactory* createSimpleFactory(UObject* instanceToAdopt, const UnicodeString& id, UBool visible, UErrorCode& status);
1.886 +
1.887 + /**
1.888 + * <p>Reinitialize the factory list to its default state. After this call, isDefault()
1.889 + * must return TRUE.</p>
1.890 + *
1.891 + * <p>This issues a serviceChanged notification to registered listeners.</p>
1.892 + *
1.893 + * <p>The default implementation clears the factory list.
1.894 + * Subclasses can override to provide other default initialization
1.895 + * of the factory list. Subclasses must not call this method
1.896 + * directly, since it must only be called while holding write
1.897 + * access to the factory list.</p>
1.898 + */
1.899 + virtual void reInitializeFactories(void);
1.900 +
1.901 + /**
1.902 + * <p>Default handler for this service if no factory in the factory list
1.903 + * handled the key passed to getKey.</p>
1.904 + *
1.905 + * <p>The default implementation returns NULL.</p>
1.906 + *
1.907 + * @param key the key.
1.908 + * @param actualReturn a pointer to a UnicodeString to hold the matched descriptor, or NULL.
1.909 + * @param status the error code status.
1.910 + * @return the service instance, or NULL.
1.911 + */
1.912 + virtual UObject* handleDefault(const ICUServiceKey& key, UnicodeString* actualReturn, UErrorCode& status) const;
1.913 +
1.914 + /**
1.915 + * <p>Clear caches maintained by this service.</p>
1.916 + *
1.917 + * <p>Subclasses can override if they implement additional caches
1.918 + * that need to be cleared when the service changes. Subclasses
1.919 + * should generally not call this method directly, as it must only
1.920 + * be called while synchronized on the factory lock.</p>
1.921 + */
1.922 + virtual void clearCaches(void);
1.923 +
1.924 + /**
1.925 + * <p>Return true if the listener is accepted.</p>
1.926 + *
1.927 + * <p>The default implementation accepts the listener if it is
1.928 + * a ServiceListener. Subclasses can override this to accept
1.929 + * different listeners.</p>
1.930 + *
1.931 + * @param l the listener to test.
1.932 + * @return TRUE if the service accepts the listener.
1.933 + */
1.934 + virtual UBool acceptsListener(const EventListener& l) const;
1.935 +
1.936 + /**
1.937 + * <p>Notify the listener of a service change.</p>
1.938 + *
1.939 + * <p>The default implementation assumes a ServiceListener.
1.940 + * If acceptsListener has been overridden to accept different
1.941 + * listeners, this should be overridden as well.</p>
1.942 + *
1.943 + * @param l the listener to notify.
1.944 + */
1.945 + virtual void notifyListener(EventListener& l) const;
1.946 +
1.947 + /************************************************************************
1.948 + * Utilities for subclasses.
1.949 + */
1.950 +
1.951 + /**
1.952 + * <p>Clear only the service cache.</p>
1.953 + *
1.954 + * <p>This can be called by subclasses when a change affects the service
1.955 + * cache but not the ID caches, e.g., when the default locale changes
1.956 + * the resolution of IDs also changes, requiring the cache to be
1.957 + * flushed, but not the visible IDs themselves.</p>
1.958 + */
1.959 + void clearServiceCache(void);
1.960 +
1.961 + /**
1.962 + * <p>Return a map from visible IDs to factories.
1.963 + * This must only be called when the mutex is held.</p>
1.964 + *
1.965 + * @param status the error code status.
1.966 + * @return a Hashtable containing mappings from visible
1.967 + * IDs to factories.
1.968 + */
1.969 + const Hashtable* getVisibleIDMap(UErrorCode& status) const;
1.970 +
1.971 + /**
1.972 + * <p>Allow subclasses to read the time stamp.</p>
1.973 + *
1.974 + * @return the timestamp.
1.975 + */
1.976 + int32_t getTimestamp(void) const;
1.977 +
1.978 + /**
1.979 + * <p>Return the number of registered factories.</p>
1.980 + *
1.981 + * @return the number of factories registered at the time of the call.
1.982 + */
1.983 + int32_t countFactories(void) const;
1.984 +
1.985 +private:
1.986 +
1.987 + friend class ::ICUServiceTest; // give tests access to countFactories.
1.988 +};
1.989 +
1.990 +U_NAMESPACE_END
1.991 +
1.992 + /* UCONFIG_NO_SERVICE */
1.993 +#endif
1.994 +
1.995 + /* ICUSERV_H */
1.996 +#endif
1.997 +
