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 &lt; str2, 0 if str1 == str2, or
156       * a positive integer if str1 &gt; 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 &lt; obj2, 0 if obj1 == obj2, or
170       * a positive integer if obj1 &gt; 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    }