KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibm > icu > text > Collator


1 /**
2 *******************************************************************************
3 * Copyright (C) 1996-2006, International Business Machines Corporation and *
4 * others. All Rights Reserved. *
5 *******************************************************************************
6 */

7 package com.ibm.icu.text;
8
9 import java.util.Comparator JavaDoc;
10 import java.util.Locale JavaDoc;
11 import java.util.MissingResourceException JavaDoc;
12 import java.util.Set JavaDoc;
13
14 import com.ibm.icu.impl.ICUDebug;
15 import com.ibm.icu.impl.ICUResourceBundle;
16 import com.ibm.icu.impl.LocaleUtility;
17 import com.ibm.icu.util.ULocale;
18 import com.ibm.icu.util.UResourceBundle;
19 import com.ibm.icu.util.VersionInfo;
20
21 /**
22 * <p>Collator performs locale-sensitive string comparison. A concrete
23 * subclass, RuleBasedCollator, allows customization of the collation
24 * ordering by the use of rule sets.</p>
25 *
26 * <p>Following the <a HREF=http://www.unicode.org>Unicode
27 * Consortium</a>'s specifications for the
28 * <a HREF="http://www.unicode.org/unicode/reports/tr10/"> Unicode Collation
29 * Algorithm (UCA)</a>, there are 5 different levels of strength used
30 * in comparisons:
31 *
32 * <ul>
33 * <li>PRIMARY strength: Typically, this is used to denote differences between
34 * base characters (for example, "a" &lt; "b").
35 * It is the strongest difference. For example, dictionaries are divided
36 * into different sections by base character.
37 * <li>SECONDARY strength: Accents in the characters are considered secondary
38 * differences (for example, "as" &lt; "&agrave;s" &lt; "at"). Other
39 * differences
40 * between letters can also be considered secondary differences, depending
41 * on the language. A secondary difference is ignored when there is a
42 * primary difference anywhere in the strings.
43 * <li>TERTIARY strength: Upper and lower case differences in characters are
44 * distinguished at tertiary strength (for example, "ao" &lt; "Ao" &lt;
45 * "a&ograve;"). In addition, a variant of a letter differs from the base
46 * form on the tertiary strength (such as "A" and "&#9398;"). Another
47 * example is the
48 * difference between large and small Kana. A tertiary difference is ignored
49 * when there is a primary or secondary difference anywhere in the strings.
50 * <li>QUATERNARY strength: When punctuation is ignored
51 * <a HREF="http://icu.sourceforge.net/userguide/Collate_Concepts.html#Ignoring_Punctuation">
52 * (see Ignoring Punctuations in the user guide)</a> at PRIMARY to TERTIARY
53 * strength, an additional strength level can
54 * be used to distinguish words with and without punctuation (for example,
55 * "ab" &lt; "a-b" &lt; "aB").
56 * This difference is ignored when there is a PRIMARY, SECONDARY or TERTIARY
57 * difference. The QUATERNARY strength should only be used if ignoring
58 * punctuation is required.
59 * <li>IDENTICAL strength:
60 * When all other strengths are equal, the IDENTICAL strength is used as a
61 * tiebreaker. The Unicode code point values of the NFD form of each string
62 * are compared, just in case there is no difference.
63 * For example, Hebrew cantellation marks are only distinguished at this
64 * strength. This strength should be used sparingly, as only code point
65 * value differences between two strings is an extremely rare occurrence.
66 * Using this strength substantially decreases the performance for both
67 * comparison and collation key generation APIs. This strength also
68 * increases the size of the collation key.
69 * </ul>
70 *
71 * Unlike the JDK, ICU4J's Collator deals only with 2 decomposition modes,
72 * the canonical decomposition mode and one that does not use any decomposition.
73 * The compatibility decomposition mode, java.text.Collator.FULL_DECOMPOSITION
74 * is not supported here. If the canonical
75 * decomposition mode is set, the Collator handles un-normalized text properly,
76 * producing the same results as if the text were normalized in NFD. If
77 * canonical decomposition is turned off, it is the user's responsibility to
78 * ensure that all text is already in the appropriate form before performing
79 * a comparison or before getting a CollationKey.</p>
80 *
81 * <p>For more information about the collation service see the
82 * <a HREF="http://icu.sourceforge.net/userguide/Collate_Intro.html">users
83 * guide</a>.</p>
84 *
85 * <p>Examples of use
86 * <pre>
87 * // Get the Collator for US English and set its strength to PRIMARY
88 * Collator usCollator = Collator.getInstance(Locale.US);
89 * usCollator.setStrength(Collator.PRIMARY);
90 * if (usCollator.compare("abc", "ABC") == 0) {
91 * System.out.println("Strings are equivalent");
92 * }
93 *
94 * The following example shows how to compare two strings using the
95 * Collator for the default locale.
96 *
97 * // Compare two strings in the default locale
98 * Collator myCollator = Collator.getInstance();
99 * myCollator.setDecomposition(NO_DECOMPOSITION);
100 * if (myCollator.compare("&agrave;&#92;u0325", "a&#92;u0325&#768;") != 0) {
101 * System.out.println("&agrave;&#92;u0325 is not equals to a&#92;u0325&#768; without decomposition");
102 * myCollator.setDecomposition(CANONICAL_DECOMPOSITION);
103 * if (myCollator.compare("&agrave;&#92;u0325", "a&#92;u0325&#768;") != 0) {
104 * System.out.println("Error: &agrave;&#92;u0325 should be equals to a&#92;u0325&#768; with decomposition");
105 * }
106 * else {
107 * System.out.println("&agrave;&#92;u0325 is equals to a&#92;u0325&#768; with decomposition");
108 * }
109 * }
110 * else {
111 * System.out.println("Error: &agrave;&#92;u0325 should be not equals to a&#92;u0325&#768; without decomposition");
112 * }
113 * </pre>
114 * </p>
115 * @see RuleBasedCollator
116 * @see CollationKey
117 * @author Syn Wee Quek
118 * @stable ICU 2.8
119 */

120 public abstract class Collator implements Comparator JavaDoc, Cloneable JavaDoc
121 {
122     // public data members ---------------------------------------------------
123

124     /**
125      * Strongest collator strength value. Typically used to denote differences
126      * between base characters. See class documentation for more explanation.
127      * @see #setStrength
128      * @see #getStrength
129      * @stable ICU 2.8
130      */

131     public final static int PRIMARY = 0;
132
133     /**
134      * Second level collator strength value.
135      * Accents in the characters are considered secondary differences.
136      * Other differences between letters can also be considered secondary
137      * differences, depending on the language.
138      * See class documentation for more explanation.
139      * @see #setStrength
140      * @see #getStrength
141      * @stable ICU 2.8
142      */

143     public final static int SECONDARY = 1;
144
145     /**
146      * Third level collator strength value.
147      * Upper and lower case differences in characters are distinguished at this
148      * strength level. In addition, a variant of a letter differs from the base
149      * form on the tertiary level.
150      * See class documentation for more explanation.
151      * @see #setStrength
152      * @see #getStrength
153      * @stable ICU 2.8
154      */

155     public final static int TERTIARY = 2;
156
157     /**
158      * Fourth level collator strength value.
159      * When punctuation is ignored
160      * <a HREF="http://icu.sourceforge.net/userguide/Collate_Concepts.html#Ignoring_Punctuation">
161      * (see Ignoring Punctuations in the user guide)</a> at PRIMARY to TERTIARY
162      * strength, an additional strength level can
163      * be used to distinguish words with and without punctuation.
164      * See class documentation for more explanation.
165      * @see #setStrength
166      * @see #getStrength
167      * @stable ICU 2.8
168      */

169     public final static int QUATERNARY = 3;
170
171     /**
172      * <p>
173      * Smallest Collator strength value. When all other strengths are equal,
174      * the IDENTICAL strength is used as a tiebreaker. The Unicode code point
175      * values of the NFD form of each string are compared, just in case there
176      * is no difference.
177      * See class documentation for more explanation.
178      * </p>
179      * <p>
180      * Note this value is different from JDK's
181      * </p>
182      * @stable ICU 2.8
183      */

184     public final static int IDENTICAL = 15;
185
186     /**
187      * This is for backwards compatibility with Java APIs only. It
188      * should not be used, IDENTICAL should be used instead. ICU's
189      * collation does not support Java's FULL_DECOMPOSITION mode.
190      * @draft ICU 3.4
191      * @provisional This API might change or be removed in a future release.
192      */

193     public final static int FULL_DECOMPOSITION = IDENTICAL;
194
195     /**
196      * <p>Decomposition mode value. With NO_DECOMPOSITION set, Strings
197      * will not be decomposed for collation. This is the default
198      * decomposition setting unless otherwise specified by the locale
199      * used to create the Collator.</p>
200      *
201      * <p><strong>Note</strong> this value is different from the JDK's.</p>
202      * @see #CANONICAL_DECOMPOSITION
203      * @see #getDecomposition
204      * @see #setDecomposition
205      * @stable ICU 2.8
206      */

207     public final static int NO_DECOMPOSITION = 16;
208
209     /**
210      * <p>Decomposition mode value. With CANONICAL_DECOMPOSITION set,
211      * characters that are canonical variants according to the Unicode standard
212      * will be decomposed for collation.</p>
213      *
214      * <p>CANONICAL_DECOMPOSITION corresponds to Normalization Form D as
215      * described in <a HREF="http://www.unicode.org/unicode/reports/tr15/">
216      * Unicode Technical Report #15</a>.
217      * </p>
218      * @see #NO_DECOMPOSITION
219      * @see #getDecomposition
220      * @see #setDecomposition
221      * @stable ICU 2.8
222      */

223     public final static int CANONICAL_DECOMPOSITION = 17;
224
225     // public methods --------------------------------------------------------
226

227     // public setters --------------------------------------------------------
228

229     /**
230      * <p>Sets this Collator's strength property. The strength property
231      * determines the minimum level of difference considered significant
232      * during comparison.</p>
233      *
234      * <p>The default strength for the Collator is TERTIARY, unless specified
235      * otherwise by the locale used to create the Collator.</p>
236      *
237      * <p>See the Collator class description for an example of use.</p>
238      * @param newStrength the new strength value.
239      * @see #getStrength
240      * @see #PRIMARY
241      * @see #SECONDARY
242      * @see #TERTIARY
243      * @see #QUATERNARY
244      * @see #IDENTICAL
245      * @exception IllegalArgumentException if the new strength value is not one
246      * of PRIMARY, SECONDARY, TERTIARY, QUATERNARY or IDENTICAL.
247      * @stable ICU 2.8
248      */

249     public void setStrength(int newStrength)
250     {
251         if ((newStrength != PRIMARY) &&
252             (newStrength != SECONDARY) &&
253             (newStrength != TERTIARY) &&
254             (newStrength != QUATERNARY) &&
255             (newStrength != IDENTICAL)) {
256             throw new IllegalArgumentException JavaDoc("Incorrect comparison level.");
257         }
258         m_strength_ = newStrength;
259     }
260
261     /**
262      * <p>Set the decomposition mode of this Collator. Setting this
263      * decomposition property with CANONICAL_DECOMPOSITION allows the
264      * Collator to handle un-normalized text properly, producing the
265      * same results as if the text were normalized. If
266      * NO_DECOMPOSITION is set, it is the user's responsibility to
267      * insure that all text is already in the appropriate form before
268      * a comparison or before getting a CollationKey. Adjusting
269      * decomposition mode allows the user to select between faster and
270      * more complete collation behavior.</p>
271      *
272      * <p>Since a great many of the world's languages do not require
273      * text normalization, most locales set NO_DECOMPOSITION as the
274      * default decomposition mode.</p>
275      *
276      * The default decompositon mode for the Collator is
277      * NO_DECOMPOSITON, unless specified otherwise by the locale used
278      * to create the Collator.</p>
279      *
280      * <p>See getDecomposition for a description of decomposition
281      * mode.</p>
282      *
283      * @param decomposition the new decomposition mode
284      * @see #getDecomposition
285      * @see #NO_DECOMPOSITION
286      * @see #CANONICAL_DECOMPOSITION
287      * @exception IllegalArgumentException If the given value is not a valid
288      * decomposition mode.
289      * @stable ICU 2.8
290      */

291     public void setDecomposition(int decomposition)
292     {
293         if ((decomposition != NO_DECOMPOSITION) &&
294             (decomposition != CANONICAL_DECOMPOSITION)) {
295             throw new IllegalArgumentException JavaDoc("Wrong decomposition mode.");
296         }
297         m_decomposition_ = decomposition;
298     }
299
300     // public getters --------------------------------------------------------
301

302     /**
303      * Gets the Collator for the current default locale.
304      * The default locale is determined by java.util.Locale.getDefault().
305      * @return the Collator for the default locale (for example, en_US) if it
306      * is created successfully. Otherwise if there is no Collator
307      * associated with the current locale, the default UCA collator
308      * will be returned.
309      * @see java.util.Locale#getDefault()
310      * @see #getInstance(Locale)
311      * @stable ICU 2.8
312      */

313     public static final Collator getInstance()
314     {
315         return getInstance(ULocale.getDefault());
316     }
317
318     /**
319      * Clone the collator.
320      * @stable ICU 2.6
321      * @return a clone of this collator.
322      */

323     public Object JavaDoc clone() throws CloneNotSupportedException JavaDoc {
324         return super.clone();
325     }
326
327     // begin registry stuff
328

329     /**
330      * A factory used with registerFactory to register multiple collators and provide
331      * display names for them. If standard locale display names are sufficient,
332      * Collator instances may be registered instead.
333      * <p><b>Note:</b> as of ICU4J 3.2, the default API for CollatorFactory uses
334      * ULocale instead of Locale. Instead of overriding createCollator(Locale),
335      * new implementations should override createCollator(ULocale). Note that
336      * one of these two methods <b>MUST</b> be overridden or else an infinite
337      * loop will occur.
338      * @stable ICU 2.6
339      */

340     public static abstract class CollatorFactory {
341         /**
342          * Return true if this factory will be visible. Default is true.
343          * If not visible, the locales supported by this factory will not
344          * be listed by getAvailableLocales.
345          *
346          * @return true if this factory is visible
347          * @stable ICU 2.6
348          */

349         public boolean visible() {
350             return true;
351         }
352
353         /**
354          * Return an instance of the appropriate collator. If the locale
355          * is not supported, return null.
356          * <b>Note:</b> as of ICU4J 3.2, implementations should override
357          * this method instead of createCollator(Locale).
358          * @param loc the locale for which this collator is to be created.
359          * @return the newly created collator.
360          * @draft ICU 3.2
361          * @provisional This API might change or be removed in a future release.
362          */

363         public Collator createCollator(ULocale loc) {
364             return createCollator(loc.toLocale());
365         }
366
367         /**
368          * Return an instance of the appropriate collator. If the locale
369          * is not supported, return null.
370          * <p><b>Note:</b> as of ICU4J 3.2, implementations should override
371          * createCollator(ULocale) instead of this method, and inherit this
372          * method's implementation. This method is no longer abstract
373          * and instead delegates to createCollator(ULocale).
374          * @param loc the locale for which this collator is to be created.
375          * @return the newly created collator.
376          * @stable ICU 2.6
377          */

378          public Collator createCollator(Locale JavaDoc loc) {
379             return createCollator(ULocale.forLocale(loc));
380         }
381
382         /**
383          * Return the name of the collator for the objectLocale, localized for the displayLocale.
384          * If objectLocale is not visible or not defined by the factory, return null.
385          * @param objectLocale the locale identifying the collator
386          * @param displayLocale the locale for which the display name of the collator should be localized
387          * @return the display name
388          * @stable ICU 2.6
389          */

390         public String JavaDoc getDisplayName(Locale JavaDoc objectLocale, Locale JavaDoc displayLocale) {
391             return getDisplayName(ULocale.forLocale(objectLocale), ULocale.forLocale(displayLocale));
392         }
393
394         /**
395          * Return the name of the collator for the objectLocale, localized for the displayLocale.
396          * If objectLocale is not visible or not defined by the factory, return null.
397          * @param objectLocale the locale identifying the collator
398          * @param displayLocale the locale for which the display name of the collator should be localized
399          * @return the display name
400          * @draft ICU 3.2
401          * @provisional This API might change or be removed in a future release.
402          */

403         public String JavaDoc getDisplayName(ULocale objectLocale, ULocale displayLocale) {
404             if (visible()) {
405                 Set JavaDoc supported = getSupportedLocaleIDs();
406                 String JavaDoc name = objectLocale.getBaseName();
407                 if (supported.contains(name)) {
408                     return objectLocale.getDisplayName(displayLocale);
409                 }
410             }
411             return null;
412         }
413
414         /**
415          * Return an unmodifiable collection of the locale names directly
416          * supported by this factory.
417          *
418          * @return the set of supported locale IDs.
419          * @stable ICU 2.6
420          */

421         public abstract Set JavaDoc getSupportedLocaleIDs();
422
423         /**
424          * Empty default constructor.
425          * @stable ICU 2.6
426          */

427         protected CollatorFactory() {
428         }
429     }
430
431     static abstract class ServiceShim {
432         abstract Collator getInstance(ULocale l);
433         abstract Object JavaDoc registerInstance(Collator c, ULocale l);
434         abstract Object JavaDoc registerFactory(CollatorFactory f);
435         abstract boolean unregister(Object JavaDoc k);
436         abstract Locale JavaDoc[] getAvailableLocales(); // TODO remove
437
abstract ULocale[] getAvailableULocales();
438         abstract String JavaDoc getDisplayName(ULocale ol, ULocale dl);
439     }
440     
441     private static ServiceShim shim;
442     private static ServiceShim getShim() {
443         // Note: this instantiation is safe on loose-memory-model configurations
444
// despite lack of synchronization, since the shim instance has no state--
445
// it's all in the class init. The worst problem is we might instantiate
446
// two shim instances, but they'll share the same state so that's ok.
447
if (shim == null) {
448             try {
449                 Class JavaDoc cls = Class.forName("com.ibm.icu.text.CollatorServiceShim");
450                 shim = (ServiceShim)cls.newInstance();
451             }
452             catch (MissingResourceException JavaDoc e)
453             {
454                 throw e;
455             }
456             catch (Exception JavaDoc e) {
457                 ///CLOVER:OFF
458
if(DEBUG){
459                     e.printStackTrace();
460                 }
461                 throw new RuntimeException JavaDoc(e.getMessage());
462                 ///CLOVER:ON
463
}
464         }
465         return shim;
466     }
467
468     /**
469      * Gets the Collator for the desired locale.
470      * @param locale the desired locale.
471      * @return Collator for the desired locale if it is created successfully.
472      * Otherwise if there is no Collator
473      * associated with the current locale, a default UCA collator will
474      * be returned.
475      * @see java.util.Locale
476      * @see java.util.ResourceBundle
477      * @see #getInstance(Locale)
478      * @see #getInstance()
479      * @stable ICU 3.0
480      */

481     public static final Collator getInstance(ULocale locale) {
482         // fetching from service cache is faster than instantiation
483
return getShim().getInstance(locale);
484     }
485
486     /**
487      * Gets the Collator for the desired locale.
488      * @param locale the desired locale.
489      * @return Collator for the desired locale if it is created successfully.
490      * Otherwise if there is no Collator
491      * associated with the current locale, a default UCA collator will
492      * be returned.
493      * @see java.util.Locale
494      * @see java.util.ResourceBundle
495      * @see #getInstance(ULocale)
496      * @see #getInstance()
497      * @stable ICU 2.8
498      */

499     public static final Collator getInstance(Locale JavaDoc locale) {
500         return getInstance(ULocale.forLocale(locale));
501     }
502
503     /**
504      * Register a collator as the default collator for the provided locale. The
505      * collator should not be modified after it is registered.
506      *
507      * @param collator the collator to register
508      * @param locale the locale for which this is the default collator
509      * @return an object that can be used to unregister the registered collator.
510      *
511      * @draft ICU 3.2
512      * @provisional This API might change or be removed in a future release.
513      */

514     public static final Object JavaDoc registerInstance(Collator collator, ULocale locale) {
515         return getShim().registerInstance(collator, locale);
516     }
517
518     /**
519      * Register a collator factory.
520      *
521      * @param factory the factory to register
522      * @return an object that can be used to unregister the registered factory.
523      *
524      * @stable ICU 2.6
525      */

526     public static final Object JavaDoc registerFactory(CollatorFactory factory) {
527         return getShim().registerFactory(factory);
528     }
529
530     /**
531      * Unregister a collator previously registered using registerInstance.
532      * @param registryKey the object previously returned by registerInstance.
533      * @return true if the collator was successfully unregistered.
534      * @stable ICU 2.6
535      */

536     public static final boolean unregister(Object JavaDoc registryKey) {
537         if (shim == null) {
538             return false;
539         }
540         return shim.unregister(registryKey);
541     }
542
543     /**
544      * Get the set of locales, as Locale objects, for which collators
545      * are installed. Note that Locale objects do not support RFC 3066.
546      * @return the list of locales in which collators are installed.
547      * This list includes any that have been registered, in addition to
548      * those that are installed with ICU4J.
549      * @stable ICU 2.4
550      */

551     public static Locale JavaDoc[] getAvailableLocales() {
552         // TODO make this wrap getAvailableULocales later
553
if (shim == null) {
554             return ICUResourceBundle.getAvailableLocales(ICUResourceBundle.ICU_COLLATION_BASE_NAME);
555         }
556         return shim.getAvailableLocales();
557     }
558
559     /**
560      * Get the set of locales, as ULocale objects, for which collators
561      * are installed. ULocale objects support RFC 3066.
562      * @return the list of locales in which collators are installed.
563      * This list includes any that have been registered, in addition to
564      * those that are installed with ICU4J.
565      * @stable ICU 3.0
566      */

567     public static final ULocale[] getAvailableULocales() {
568         if (shim == null) {
569             return ICUResourceBundle.getAvailableULocales(ICUResourceBundle.ICU_COLLATION_BASE_NAME);
570         }
571         return shim.getAvailableULocales();
572     }
573     
574     /**
575      * The list of keywords for this service. This must be kept in sync with
576      * the resource data.
577      * @since ICU 3.0
578      */

579     private static final String JavaDoc[] KEYWORDS = { "collation" };
580
581     /**
582      * The resource name for this service. Note that this is not the same as
583      * the keyword for this service.
584      * @since ICU 3.0
585      */

586     private static final String JavaDoc RESOURCE = "collations";
587
588     /**
589      * The resource bundle base name for this service.
590      * *since ICU 3.0
591      */

592     private static final String JavaDoc BASE = ICUResourceBundle.ICU_COLLATION_BASE_NAME;
593
594     /**
595      * Return an array of all possible keywords that are relevant to
596      * collation. At this point, the only recognized keyword for this
597      * service is "collation".
598      * @return an array of valid collation keywords.
599      * @see #getKeywordValues
600      * @stable ICU 3.0
601      */

602     public static final String JavaDoc[] getKeywords() {
603         return KEYWORDS;
604     }
605     
606     /**
607      * Given a keyword, return an array of all values for
608      * that keyword that are currently in use.
609      * @param keyword one of the keywords returned by getKeywords.
610      * @see #getKeywords
611      * @stable ICU 3.0
612      */

613     public static final String JavaDoc[] getKeywordValues(String JavaDoc keyword) {
614         if (!keyword.equals(KEYWORDS[0])) {
615             throw new IllegalArgumentException JavaDoc("Invalid keyword: " + keyword);
616         }
617         return ICUResourceBundle.getKeywordValues(BASE, RESOURCE);
618     }
619
620     /**
621      * Return the functionally equivalent locale for the given
622      * requested locale, with respect to given keyword, for the
623      * collation service. If two locales return the same result, then
624      * collators instantiated for these locales will behave
625      * equivalently. The converse is not always true; two collators
626      * may in fact be equivalent, but return different results, due to
627      * internal details. The return result has no other meaning than
628      * that stated above, and implies nothing as to the relationship
629      * between the two locales. This is intended for use by
630      * applications who wish to cache collators, or otherwise reuse
631      * collators when possible. The functional equivalent may change
632      * over time. For more information, please see the <a
633      * HREF="http://icu.sourceforge.net/userguide/locale.html#services">
634      * Locales and Services</a> section of the ICU User Guide.
635      * @param keyword a particular keyword as enumerated by
636      * getKeywords.
637      * @param locID The requested locale
638      * @param isAvailable If non-null, isAvailable[0] will receive and
639      * output boolean that indicates whether the requested locale was
640      * 'available' to the collation service. The locale is defined as
641      * 'available' if it physically exists within the collation locale
642      * data. If non-null, isAvailable must have length >= 1.
643      * @return the locale
644      * @stable ICU 3.0
645      */

646     public static final ULocale getFunctionalEquivalent(String JavaDoc keyword,
647                                                         ULocale locID,
648                                                         boolean isAvailable[]) {
649         return ICUResourceBundle.getFunctionalEquivalent(
650                                                          BASE, RESOURCE, keyword, locID, isAvailable);
651     }
652     
653     /**
654      * Return the functionally equivalent locale for the given
655      * requested locale, with respect to given keyword, for the
656      * collation service.
657      * @param keyword a particular keyword as enumerated by
658      * getKeywords.
659      * @param locID The requested locale
660      * @return the locale
661      * @see #getFunctionalEquivalent(String,ULocale,boolean[])
662      * @stable ICU 3.0
663      */

664     public static final ULocale getFunctionalEquivalent(String JavaDoc keyword,
665                                                         ULocale locID) {
666         return getFunctionalEquivalent(keyword, locID, null);
667     }
668     
669     /**
670      * Get the name of the collator for the objectLocale, localized for the displayLocale.
671      * @param objectLocale the locale of the collator
672      * @param displayLocale the locale for the collator's display name
673      * @return the display name
674      * @stable ICU 2.6
675      */

676     static public String JavaDoc getDisplayName(Locale JavaDoc objectLocale, Locale JavaDoc displayLocale) {
677         return getShim().getDisplayName(ULocale.forLocale(objectLocale),
678                                         ULocale.forLocale(displayLocale));
679     }
680
681     /**
682      * Get the name of the collator for the objectLocale, localized for the displayLocale.
683      * @param objectLocale the locale of the collator
684      * @param displayLocale the locale for the collator's display name
685      * @return the display name
686      * @draft ICU 3.2
687      * @provisional This API might change or be removed in a future release.
688      */

689     static public String JavaDoc getDisplayName(ULocale objectLocale, ULocale displayLocale) {
690         return getShim().getDisplayName(objectLocale, displayLocale);
691     }
692
693     /**
694      * Get the name of the collator for the objectLocale, localized for the current locale.
695      * @param objectLocale the locale of the collator
696      * @return the display name
697      * @stable ICU 2.6
698      */

699     static public String JavaDoc getDisplayName(Locale JavaDoc objectLocale) {
700         return getShim().getDisplayName(ULocale.forLocale(objectLocale), ULocale.getDefault());
701     }
702
703     /**
704      * Get the name of the collator for the objectLocale, localized for the current locale.
705      * @param objectLocale the locale of the collator
706      * @return the display name
707      * @draft ICU 3.2
708      * @provisional This API might change or be removed in a future release.
709      */

710     static public String JavaDoc getDisplayName(ULocale objectLocale) {
711         return getShim().getDisplayName(objectLocale, ULocale.getDefault());
712     }
713
714     /**
715      * <p>Returns this Collator's strength property. The strength property
716      * determines the minimum level of difference considered significant.
717      * </p>
718      * <p>
719      * See the Collator class description for more details.
720      * </p>
721      * @return this Collator's current strength property.
722      * @see #setStrength
723      * @see #PRIMARY
724      * @see #SECONDARY
725      * @see #TERTIARY
726      * @see #QUATERNARY
727      * @see #IDENTICAL
728      * @stable ICU 2.8
729      */

730     public int getStrength()
731     {
732         return m_strength_;
733     }
734
735     /**
736      * <p>
737      * Get the decomposition mode of this Collator. Decomposition mode
738      * determines how Unicode composed characters are handled.
739      * </p>
740      * <p>
741      * See the Collator class description for more details.
742      * </p>
743      * @return the decomposition mode
744      * @see #setDecomposition
745      * @see #NO_DECOMPOSITION
746      * @see #CANONICAL_DECOMPOSITION
747      * @stable ICU 2.8
748      */

749     public int getDecomposition()
750     {
751         return m_decomposition_;
752     }
753
754     /**
755      * <p>
756      * Compares the source text String to the target text String according to
757      * this Collator's rules, strength and decomposition mode.
758      * Returns an integer less than,
759      * equal to or greater than zero depending on whether the source String is
760      * less than, equal to or greater than the target String. See the Collator
761      * class description for an example of use.
762      * </p>
763      * @param source the source String.
764      * @param target the target String.
765      * @return Returns an integer value. Value is less than zero if source is
766      * less than target, value is zero if source and target are equal,
767      * value is greater than zero if source is greater than target.
768      * @see CollationKey
769      * @see #getCollationKey
770      * @exception NullPointerException thrown if either arguments is null.
771      * IllegalArgumentException thrown if either source or target is
772      * not of the class String.
773      * @stable ICU 2.8
774      */

775     public int compare(Object JavaDoc source, Object JavaDoc target)
776     {
777         if (!(source instanceof String JavaDoc) || !(target instanceof String JavaDoc)) {
778             throw new IllegalArgumentException JavaDoc("Arguments have to be of type String");
779         }
780         return compare((String JavaDoc)source, (String JavaDoc)target);
781     }
782
783     // public other methods -------------------------------------------------
784

785     /**
786      * Convenience method for comparing the equality of two text Strings using
787      * this Collator's rules, strength and decomposition mode.
788      * @param source the source string to be compared.
789      * @param target the target string to be compared.
790      * @return true if the strings are equal according to the collation
791      * rules, otherwise false.
792      * @see #compare
793      * @exception NullPointerException thrown if either arguments is null.
794      * @stable ICU 2.8
795      */

796     public boolean equals(String JavaDoc source, String JavaDoc target)
797     {
798         return (compare(source, target) == 0);
799     }
800
801     /**
802      * Get an UnicodeSet that contains all the characters and sequences
803      * tailored in this collator.
804      * @return a pointer to a UnicodeSet object containing all the
805      * code points and sequences that may sort differently than
806      * in the UCA.
807      * @stable ICU 2.4
808      */

809     public UnicodeSet getTailoredSet()
810     {
811         return new UnicodeSet(0, 0x10FFFF);
812     }
813
814     /**
815      * <p>
816      * Compares the source text String to the target text String according to
817      * this Collator's rules, strength and decomposition mode.
818      * Returns an integer less than,
819      * equal to or greater than zero depending on whether the source String is
820      * less than, equal to or greater than the target String. See the Collator
821      * class description for an example of use.
822      * </p>
823      * @param source the source String.
824      * @param target the target String.
825      * @return Returns an integer value. Value is less than zero if source is
826      * less than target, value is zero if source and target are equal,
827      * value is greater than zero if source is greater than target.
828      * @see CollationKey
829      * @see #getCollationKey
830      * @exception NullPointerException thrown if either arguments is null.
831      * @stable ICU 2.8
832      */

833     public abstract int compare(String JavaDoc source, String JavaDoc target);
834
835     /**
836      * <p>
837      * Transforms the String into a CollationKey suitable for efficient
838      * repeated comparison. The resulting key depends on the collator's
839      * rules, strength and decomposition mode.
840      * </p>
841      * <p>See the CollationKey class documentation for more information.</p>
842      * @param source the string to be transformed into a CollationKey.
843      * @return the CollationKey for the given String based on this Collator's
844      * collation rules. If the source String is null, a null
845      * CollationKey is returned.
846      * @see CollationKey
847      * @see #compare(String, String)
848      * @see #getRawCollationKey
849      * @stable ICU 2.8
850      */

851     public abstract CollationKey getCollationKey(String JavaDoc source);
852     
853     /**
854      * Gets the simpler form of a CollationKey for the String source following
855      * the rules of this Collator and stores the result into the user provided
856      * argument key.
857      * If key has a internal byte array of length that's too small for the
858      * result, the internal byte array will be grown to the exact required
859      * size.
860      * @param source the text String to be transformed into a RawCollationKey
861      * @return If key is null, a new instance of RawCollationKey will be
862      * created and returned, otherwise the user provided key will be
863      * returned.
864      * @see #compare(String, String)
865      * @see #getCollationKey
866      * @see RawCollationKey
867      * @stable ICU 2.8
868      */

869     public abstract RawCollationKey getRawCollationKey(String JavaDoc source,
870                                                        RawCollationKey key);
871
872     /**
873      * <p>
874      * Variable top is a two byte primary value which causes all the codepoints
875      * with primary values that are less or equal than the variable top to be
876      * shifted when alternate handling is set to SHIFTED.
877      * </p>
878      * <p>
879      * Sets the variable top to a collation element value of a string supplied.
880      * </p>
881      * @param varTop one or more (if contraction) characters to which the
882      * variable top should be set
883      * @return a int value containing the value of the variable top in upper 16
884      * bits. Lower 16 bits are undefined.
885      * @exception IllegalArgumentException is thrown if varTop argument is not
886      * a valid variable top element. A variable top element is
887      * invalid when it is a contraction that does not exist in the
888      * Collation order or when the PRIMARY strength collation
889      * element for the variable top has more than two bytes
890      * @see #getVariableTop
891      * @see RuleBasedCollator#setAlternateHandlingShifted
892      * @stable ICU 2.6
893      */

894     public abstract int setVariableTop(String JavaDoc varTop);
895     
896     /**
897      * Gets the variable top value of a Collator.
898      * Lower 16 bits are undefined and should be ignored.
899      * @return the variable top value of a Collator.
900      * @see #setVariableTop
901      * @stable ICU 2.6
902      */

903     public abstract int getVariableTop();
904     
905     /**
906      * Sets the variable top to a collation element value supplied.
907      * Variable top is set to the upper 16 bits.
908      * Lower 16 bits are ignored.
909      * @param varTop Collation element value, as returned by setVariableTop or
910      * getVariableTop
911      * @see #getVariableTop
912      * @see #setVariableTop
913      * @stable ICU 2.6
914      */

915     public abstract void setVariableTop(int varTop);
916
917     /**
918      * Get the version of this collator object.
919      * @return the version object associated with this collator
920      * @stable ICU 2.8
921      */

922     public abstract VersionInfo getVersion();
923         
924     /**
925      * Get the UCA version of this collator object.
926      * @return the version object associated with this collator
927      * @stable ICU 2.8
928      */

929     public abstract VersionInfo getUCAVersion();
930         
931     // protected constructor -------------------------------------------------
932

933     /**
934      * Empty default constructor to make javadocs happy
935      * @stable ICU 2.4
936      */

937     protected Collator()
938     {
939     }
940     
941     // package private methods -----------------------------------------------
942

943     // private data members --------------------------------------------------
944

945     /**
946      * Collation strength
947      */

948     private int m_strength_ = TERTIARY;
949
950     /**
951      * Decomposition mode
952      */

953     private int m_decomposition_ = CANONICAL_DECOMPOSITION;
954     
955     private static final boolean DEBUG = ICUDebug.enabled("collator");
956     
957     // private methods -------------------------------------------------------
958

959     // end registry stuff
960

961     // -------- BEGIN ULocale boilerplate --------
962

963     /**
964      * Return the locale that was used to create this object, or null.
965      * This may may differ from the locale requested at the time of
966      * this object's creation. For example, if an object is created
967      * for locale <tt>en_US_CALIFORNIA</tt>, the actual data may be
968      * drawn from <tt>en</tt> (the <i>actual</i> locale), and
969      * <tt>en_US</tt> may be the most specific locale that exists (the
970      * <i>valid</i> locale).
971      *
972      * <p>Note: This method will be implemented in ICU 3.0; ICU 2.8
973      * contains a partial preview implementation. The * <i>actual</i>
974      * locale is returned correctly, but the <i>valid</i> locale is
975      * not, in most cases.
976      * @param type type of information requested, either {@link
977      * com.ibm.icu.util.ULocale#VALID_LOCALE} or {@link
978      * com.ibm.icu.util.ULocale#ACTUAL_LOCALE}.
979      * @return the information specified by <i>type</i>, or null if
980      * this object was not constructed from locale data.
981      * @see com.ibm.icu.util.ULocale
982      * @see com.ibm.icu.util.ULocale#VALID_LOCALE
983      * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE
984      * @draft ICU 2.8 (retain)
985      * @provisional This API might change or be removed in a future release.
986      */

987     public final ULocale getLocale(ULocale.Type type) {
988         return type == ULocale.ACTUAL_LOCALE ?
989             this.actualLocale : this.validLocale;
990     }
991
992     /**
993      * Set information about the locales that were used to create this
994      * object. If the object was not constructed from locale data,
995      * both arguments should be set to null. Otherwise, neither
996      * should be null. The actual locale must be at the same level or
997      * less specific than the valid locale. This method is intended
998      * for use by factories or other entities that create objects of
999      * this class.
1000     * @param valid the most specific locale containing any resource
1001     * data, or null
1002     * @param actual the locale containing data used to construct this
1003     * object, or null
1004     * @see com.ibm.icu.util.ULocale
1005     * @see com.ibm.icu.util.ULocale#VALID_LOCALE
1006     * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE
1007     * @internal
1008     */

1009    final void setLocale(ULocale valid, ULocale actual) {
1010        // Change the following to an assertion later
1011
if ((valid == null) != (actual == null)) {
1012            ///CLOVER:OFF
1013
throw new IllegalArgumentException JavaDoc();
1014            ///CLOVER:ON
1015
}
1016        // Another check we could do is that the actual locale is at
1017
// the same level or less specific than the valid locale.
1018
this.validLocale = valid;
1019        this.actualLocale = actual;
1020    }
1021
1022    /**
1023     * The most specific locale containing any resource data, or null.
1024     * @see com.ibm.icu.util.ULocale
1025     * @internal
1026     */

1027    private ULocale validLocale;
1028
1029    /**
1030     * The locale containing data used to construct this object, or
1031     * null.
1032     * @see com.ibm.icu.util.ULocale
1033     * @internal
1034     */

1035    private ULocale actualLocale;
1036
1037    // -------- END ULocale boilerplate --------
1038
}
1039
Popular Tags