001 /* Collator.java -- Perform locale dependent String comparisons. 002 Copyright (C) 1998, 1999, 2000, 2001, 2004, 2005, 2007 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.text; 040 041 import java.text.spi.CollatorProvider; 042 043 import java.util.Comparator; 044 import java.util.Locale; 045 import java.util.MissingResourceException; 046 import java.util.ResourceBundle; 047 import java.util.ServiceLoader; 048 049 /** 050 * This class is the abstract superclass of classes which perform 051 * locale dependent <code>String</code> comparisons. A caller requests 052 * an instance of <code>Collator</code> for a particular locale using 053 * the <code>getInstance()</code> static method in this class. That method 054 * will return a locale specific subclass of <code>Collator</code> which 055 * can be used to perform <code>String</code> comparisons for that locale. 056 * If a subclass of <code>Collator</code> cannot be located for a particular 057 * locale, a default instance for the current locale will be returned. 058 * 059 * In addition to setting the correct locale, there are two additional 060 * settings that can be adjusted to affect <code>String</code> comparisons: 061 * strength and decomposition. The strength value determines the level 062 * of signficance of character differences required for them to sort 063 * differently. (For example, whether or not capital letters are considered 064 * different from lower case letters). The decomposition value affects how 065 * variants of the same character are treated for sorting purposes. (For 066 * example, whether or not an accent is signficant or not). These settings 067 * are described in detail in the documentation for the methods and values 068 * that are related to them. 069 * 070 * @author Tom Tromey (tromey@cygnus.com) 071 * @author Aaron M. Renn (arenn@urbanophile.com) 072 * @date March 18, 1999 073 */ 074 public abstract class Collator implements Comparator<Object>, Cloneable 075 { 076 /** 077 * This constant is a strength value which indicates that only primary 078 * differences between characters will be considered signficant. As an 079 * example, two completely different English letters such as 'a' and 'b' 080 * are considered to have a primary difference. 081 */ 082 public static final int PRIMARY = 0; 083 084 /** 085 * This constant is a strength value which indicates that only secondary 086 * or primary differences between characters will be considered 087 * significant. An example of a secondary difference between characters 088 * are instances of the same letter with different accented forms. 089 */ 090 public static final int SECONDARY = 1; 091 092 /** 093 * This constant is a strength value which indicates that tertiary, 094 * secondary, and primary differences will be considered during sorting. 095 * An example of a tertiary difference is capitalization of a given letter. 096 * This is the default value for the strength setting. 097 */ 098 public static final int TERTIARY = 2; 099 100 /** 101 * This constant is a strength value which indicates that any difference 102 * at all between character values are considered significant. 103 */ 104 public static final int IDENTICAL = 3; 105 106 /** 107 * This constant indicates that accented characters won't be decomposed 108 * when performing comparisons. This will yield the fastest results, but 109 * will only work correctly in call cases for languages which do not 110 * use accents such as English. 111 */ 112 public static final int NO_DECOMPOSITION = 0; 113 114 /** 115 * This constant indicates that only characters which are canonical variants 116 * in Unicode 2.0 will be decomposed prior to performing comparisons. This 117 * will cause accented languages to be sorted correctly. This is the 118 * default decomposition value. 119 */ 120 public static final int CANONICAL_DECOMPOSITION = 1; 121 122 /** 123 * This constant indicates that both canonical variants and compatibility 124 * variants in Unicode 2.0 will be decomposed prior to performing 125 * comparisons. This is the slowest mode, but is required to get the 126 * correct sorting for certain languages with certain special formats. 127 */ 128 public static final int FULL_DECOMPOSITION = 2; 129 130 /** 131 * This method initializes a new instance of <code>Collator</code> to have 132 * the default strength (TERTIARY) and decomposition 133 * (CANONICAL_DECOMPOSITION) settings. This constructor is protected and 134 * is for use by subclasses only. Non-subclass callers should use the 135 * static <code>getInstance()</code> methods of this class to instantiate 136 * <code>Collation</code> objects for the desired locale. 137 */ 138 protected Collator () 139 { 140 strength = TERTIARY; 141 decmp = CANONICAL_DECOMPOSITION; 142 } 143 144 /** 145 * This method compares the two <code>String</code>'s and returns an 146 * integer indicating whether or not the first argument is less than, 147 * equal to, or greater than the second argument. The comparison is 148 * performed according to the rules of the locale for this 149 * <code>Collator</code> and the strength and decomposition rules in 150 * effect. 151 * 152 * @param source The first object to compare 153 * @param target The second object to compare 154 * 155 * @return A negative integer if str1 < str2, 0 if str1 == str2, or 156 * a positive integer if str1 > str2. 157 */ 158 public abstract int compare (String source, String target); 159 160 /** 161 * This method compares the two <code>Object</code>'s and returns an 162 * integer indicating whether or not the first argument is less than, 163 * equal to, or greater than the second argument. These two objects 164 * must be <code>String</code>'s or an exception will be thrown. 165 * 166 * @param o1 The first object to compare 167 * @param o2 The second object to compare 168 * 169 * @return A negative integer if obj1 < obj2, 0 if obj1 == obj2, or 170 * a positive integer if obj1 > obj2. 171 * 172 * @exception ClassCastException If the arguments are not instances 173 * of <code>String</code>. 174 */ 175 public int compare (Object o1, Object o2) 176 { 177 return compare ((String) o1, (String) o2); 178 } 179 180 /** 181 * This method tests the specified object for equality against this 182 * object. This will be true if and only if the following conditions are 183 * met: 184 * <ul> 185 * <li>The specified object is not <code>null</code>.</li> 186 * <li>The specified object is an instance of <code>Collator</code>.</li> 187 * <li>The specified object has the same strength and decomposition 188 * settings as this object.</li> 189 * </ul> 190 * 191 * @param obj The <code>Object</code> to test for equality against 192 * this object. 193 * 194 * @return <code>true</code> if the specified object is equal to 195 * this one, <code>false</code> otherwise. 196 */ 197 public boolean equals (Object obj) 198 { 199 if (! (obj instanceof Collator)) 200 return false; 201 Collator c = (Collator) obj; 202 return decmp == c.decmp && strength == c.strength; 203 } 204 205 /** 206 * This method tests whether the specified <code>String</code>'s are equal 207 * according to the collation rules for the locale of this object and 208 * the current strength and decomposition settings. 209 * 210 * @param source The first <code>String</code> to compare 211 * @param target The second <code>String</code> to compare 212 * 213 * @return <code>true</code> if the two strings are equal, 214 * <code>false</code> otherwise. 215 */ 216 public boolean equals (String source, String target) 217 { 218 return compare (source, target) == 0; 219 } 220 221 /** 222 * This method returns a copy of this <code>Collator</code> object. 223 * 224 * @return A duplicate of this object. 225 */ 226 public Object clone () 227 { 228 try 229 { 230 return super.clone (); 231 } 232 catch (CloneNotSupportedException _) 233 { 234 return null; 235 } 236 } 237 238 /** 239 * This method returns an array of <code>Locale</code> objects which is 240 * the list of locales for which <code>Collator</code> objects exist. 241 * 242 * @return The list of locales for which <code>Collator</code>'s exist. 243 */ 244 public static synchronized Locale[] getAvailableLocales () 245 { 246 // FIXME 247 Locale[] l = new Locale[1]; 248 l[0] = Locale.US; 249 return l; 250 } 251 252 /** 253 * This method transforms the specified <code>String</code> into a 254 * <code>CollationKey</code> for faster comparisons. This is useful when 255 * comparisons against a string might be performed multiple times, such 256 * as during a sort operation. 257 * 258 * @param source The <code>String</code> to convert. 259 * 260 * @return A <code>CollationKey</code> for the specified <code>String</code>. 261 */ 262 public abstract CollationKey getCollationKey (String source); 263 264 /** 265 * This method returns the current decomposition setting for this 266 * object. This * will be one of NO_DECOMPOSITION, 267 * CANONICAL_DECOMPOSITION, or * FULL_DECOMPOSITION. See the 268 * documentation for those constants for an * explanation of this 269 * setting. 270 * 271 * @return The current decomposition setting. 272 */ 273 public synchronized int getDecomposition () 274 { 275 return decmp; 276 } 277 278 /** 279 * This method returns an instance of <code>Collator</code> for the 280 * default locale. 281 * 282 * @return A <code>Collator</code> for the default locale. 283 */ 284 public static Collator getInstance () 285 { 286 return getInstance (Locale.getDefault()); 287 } 288 289 /** 290 * This method returns an instance of <code>Collator</code> for the 291 * specified locale. If no <code>Collator</code> exists for the desired 292 * locale, the fallback procedure described in 293 * {@link java.util.spi.LocaleServiceProvider} is invoked. 294 * 295 * @param loc The desired locale to load a <code>Collator</code> for. 296 * 297 * @return A <code>Collator</code> for the requested locale 298 */ 299 public static Collator getInstance (Locale loc) 300 { 301 String pattern; 302 try 303 { 304 ResourceBundle res = 305 ResourceBundle.getBundle("gnu.java.locale.LocaleInformation", 306 loc, ClassLoader.getSystemClassLoader()); 307 return new RuleBasedCollator(res.getString("collation_rules")); 308 } 309 catch (MissingResourceException x) 310 { 311 /* This means runtime support for the locale 312 * is not available, so we check providers. */ 313 } 314 catch (ParseException x) 315 { 316 throw (InternalError)new InternalError().initCause(x); 317 } 318 for (CollatorProvider p : ServiceLoader.load(CollatorProvider.class)) 319 { 320 for (Locale l : p.getAvailableLocales()) 321 { 322 if (l.equals(loc)) 323 { 324 Collator c = p.getInstance(loc); 325 if (c != null) 326 return c; 327 break; 328 } 329 } 330 } 331 if (loc.equals(Locale.ROOT)) 332 { 333 try 334 { 335 return new RuleBasedCollator("<0<1<2<3<4<5<6<7<8<9<A,a<b,B<c," + 336 "C<d,D<e,E<f,F<g,G<h,H<i,I<j,J<k,K" + 337 "<l,L<m,M<n,N<o,O<p,P<q,Q<r,R<s,S<t,"+ 338 "T<u,U<v,V<w,W<x,X<y,Y<z,Z"); 339 } 340 catch (ParseException x) 341 { 342 throw (InternalError)new InternalError().initCause(x); 343 } 344 } 345 // FIXME 346 return getInstance(Locale.US); 347 } 348 349 /** 350 * This method returns the current strength setting for this object. This 351 * will be one of PRIMARY, SECONDARY, TERTIARY, or IDENTICAL. See the 352 * documentation for those constants for an explanation of this setting. 353 * 354 * @return The current strength setting. 355 */ 356 public synchronized int getStrength () 357 { 358 return strength; 359 } 360 361 /** 362 * This method returns a hash code value for this object. 363 * 364 * @return A hash value for this object. 365 */ 366 public abstract int hashCode (); 367 368 /** 369 * This method sets the decomposition setting for this object to the 370 * specified value. This must be one of NO_DECOMPOSITION, 371 * CANONICAL_DECOMPOSITION, or FULL_DECOMPOSITION. Otherwise an 372 * exception will be thrown. See the documentation for those 373 * contants for an explanation of this setting. 374 * 375 * @param mode The new decomposition setting. 376 * 377 * @exception IllegalArgumentException If the requested 378 * decomposition setting is not valid. 379 */ 380 public synchronized void setDecomposition (int mode) 381 { 382 if (mode != NO_DECOMPOSITION 383 && mode != CANONICAL_DECOMPOSITION 384 && mode != FULL_DECOMPOSITION) 385 throw new IllegalArgumentException (); 386 decmp = mode; 387 } 388 389 /** 390 * This method sets the strength setting for this object to the specified 391 * value. This must be one of PRIMARY, SECONDARY, TERTIARY, or IDENTICAL. 392 * Otherwise an exception is thrown. See the documentation for these 393 * constants for an explanation of this setting. 394 * 395 * @param strength The new strength setting. 396 * 397 * @exception IllegalArgumentException If the requested strength 398 * setting value is not valid. 399 */ 400 public synchronized void setStrength (int strength) 401 { 402 if (strength != PRIMARY && strength != SECONDARY 403 && strength != TERTIARY && strength != IDENTICAL) 404 throw new IllegalArgumentException (); 405 this.strength = strength; 406 } 407 408 // Decompose a single character and append results to the buffer. 409 native final void decomposeCharacter (char c, StringBuffer buf); 410 411 /** 412 * This is the current collation decomposition setting. 413 */ 414 int decmp; 415 416 /** 417 * This is the current collation strength setting. 418 */ 419 int strength; 420 }