CollationKey.java revision f33eae7e84eb6d3b0f4e86b59605bb3de73009f3 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.text;
19
20/**
21 * Represents a string under the rules of a specific {@code Collator} object.
22 * Comparing two {@code CollationKey} instances returns the relative order of
23 * the strings they represent.
24 * <p>
25 * Since the rule set of collators can differ, the sort orders of the same
26 * string under two different {@code Collator} instances might differ. Hence
27 * comparing collation keys generated from different {@code Collator} instances
28 * can give incorrect results.
29 * <p>
30 * Both the method {@code CollationKey.compareTo(CollationKey)} and the method
31 * {@code Collator.compare(String, String)} compares two strings and returns
32 * their relative order. The performance characteristics of these two approaches
33 * can differ.
34 * <p>
35 * During the construction of a {@code CollationKey}, the entire source string
36 * is examined and processed into a series of bits terminated by a null, that
37 * are stored in the {@code CollationKey}. When
38 * {@code CollationKey.compareTo(CollationKey)} executes, it performs bitwise
39 * comparison on the bit sequences. This can incur startup cost when creating
40 * the {@code CollationKey}, but once the key is created, binary comparisons
41 * are fast. This approach is recommended when the same strings are to be
42 * compared over and over again.
43 * <p>
44 * On the other hand, implementations of
45 * {@code Collator.compare(String, String)} can examine and process the strings
46 * only until the first characters differ in order. This approach is
47 * recommended if the strings are to be compared only once.
48 * <p>
49 * The following example shows how collation keys can be used to sort a
50 * list of strings:
51 * <blockquote>
52 *
53 * <pre>
54 * // Create an array of CollationKeys for the Strings to be sorted.
55 * Collator myCollator = Collator.getInstance();
56 * CollationKey[] keys = new CollationKey[3];
57 * keys[0] = myCollator.getCollationKey(&quot;Tom&quot;);
58 * keys[1] = myCollator.getCollationKey(&quot;Dick&quot;);
59 * keys[2] = myCollator.getCollationKey(&quot;Harry&quot;);
60 * sort(keys);
61 * <br>
62 * //...
63 * <br>
64 * // Inside body of sort routine, compare keys this way
65 * if( keys[i].compareTo( keys[j] ) &gt; 0 )
66 *    // swap keys[i] and keys[j]
67 * <br>
68 * //...
69 * <br>
70 * // Finally, when we've returned from sort.
71 * System.out.println(keys[0].getSourceString());
72 * System.out.println(keys[1].getSourceString());
73 * System.out.println(keys[2].getSourceString());
74 * </pre>
75 *
76 * </blockquote>
77 *
78 * @see Collator
79 * @see RuleBasedCollator
80 */
81public abstract class CollationKey implements Comparable<CollationKey> {
82    private final String source;
83
84    protected CollationKey(String source) {
85        this.source = source;
86    }
87
88    /**
89     * Compares this collation key to the given collation key.
90     *
91     * @param value the other collation key.
92     * @return a negative value if this key is less than {@code value},
93     *         0 if they are equal, and a positive value if this key is greater.
94     */
95    public abstract int compareTo(CollationKey value);
96
97    /**
98     * Returns the string from which this collation key was created.
99     *
100     * @return the source string of this collation key.
101     */
102    public String getSourceString() {
103        return source;
104    }
105
106    /**
107     * Returns this collation key as a byte array.
108     *
109     * @return an array of bytes.
110     */
111    public abstract byte[] toByteArray();
112}
113