← Back to branch summary

~alinuxninja/nginx-edge/trunk

« back to all changes in this revision

Viewing changes to debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/common/serv.h

  • Committer: Vivian
  • Date: 2015-12-04 18:20:11 UTC
  • Revision ID: git-v1:a36f2bc32e884f7473b3a47040e5411306144d7d
* Do not extract psol.tar.gz

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/common/serv.h
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