1 /* 2 * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /* 27 * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved 28 * (C) Copyright IBM Corp. 1996 - All Rights Reserved 29 * 30 * The original version of this source code and documentation is copyrighted 31 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These 32 * materials are provided under terms of a License Agreement between Taligent 33 * and Sun. This technology is protected by multiple US and International 34 * patents. This notice and attribution to Taligent may not be removed. 35 * Taligent is a registered trademark of Taligent, Inc. 36 * 37 */ 38 39 package java.text; 40 41 /** 42 * A <code>CollationKey</code> represents a <code>String</code> under the 43 * rules of a specific <code>Collator</code> object. Comparing two 44 * <code>CollationKey</code>s returns the relative order of the 45 * <code>String</code>s they represent. Using <code>CollationKey</code>s 46 * to compare <code>String</code>s is generally faster than using 47 * <code>Collator.compare</code>. Thus, when the <code>String</code>s 48 * must be compared multiple times, for example when sorting a list 49 * of <code>String</code>s. It's more efficient to use <code>CollationKey</code>s. 50 * 51 * <p> 52 * You can not create <code>CollationKey</code>s directly. Rather, 53 * generate them by calling <code>Collator.getCollationKey</code>. 54 * You can only compare <code>CollationKey</code>s generated from 55 * the same <code>Collator</code> object. 56 * 57 * <p> 58 * Generating a <code>CollationKey</code> for a <code>String</code> 59 * involves examining the entire <code>String</code> 60 * and converting it to series of bits that can be compared bitwise. This 61 * allows fast comparisons once the keys are generated. The cost of generating 62 * keys is recouped in faster comparisons when <code>String</code>s need 63 * to be compared many times. On the other hand, the result of a comparison 64 * is often determined by the first couple of characters of each <code>String</code>. 65 * <code>Collator.compare</code> examines only as many characters as it needs which 66 * allows it to be faster when doing single comparisons. 67 * <p> 68 * The following example shows how <code>CollationKey</code>s might be used 69 * to sort a list of <code>String</code>s. 70 * <blockquote> 71 * <pre> 72 * // Create an array of CollationKeys for the Strings to be sorted. 73 * Collator myCollator = Collator.getInstance(); 74 * CollationKey[] keys = new CollationKey[3]; 75 * keys[0] = myCollator.getCollationKey("Tom"); 76 * keys[1] = myCollator.getCollationKey("Dick"); 77 * keys[2] = myCollator.getCollationKey("Harry"); 78 * sort( keys ); 79 * <br> 80 * //... 81 * <br> 82 * // Inside body of sort routine, compare keys this way 83 * if( keys[i].compareTo( keys[j] ) > 0 ) 84 * // swap keys[i] and keys[j] 85 * <br> 86 * //... 87 * <br> 88 * // Finally, when we've returned from sort. 89 * System.out.println( keys[0].getSourceString() ); 90 * System.out.println( keys[1].getSourceString() ); 91 * System.out.println( keys[2].getSourceString() ); 92 * </pre> 93 * </blockquote> 94 * 95 * @see Collator 96 * @see RuleBasedCollator 97 * @author Helena Shih 98 */ 99 100 public abstract class CollationKey implements Comparable<CollationKey> { 101 /** 102 * Compare this CollationKey to the target CollationKey. The collation rules of the 103 * Collator object which created these keys are applied. <strong>Note:</strong> 104 * CollationKeys created by different Collators can not be compared. 105 * @param target target CollationKey 106 * @return Returns an integer value. Value is less than zero if this is less 107 * than target, value is zero if this and target are equal and value is greater than 108 * zero if this is greater than target. 109 * @see java.text.Collator#compare 110 */ compareTo(CollationKey target)111 abstract public int compareTo(CollationKey target); 112 113 /** 114 * Returns the String that this CollationKey represents. 115 */ getSourceString()116 public String getSourceString() { 117 return source; 118 } 119 120 121 /** 122 * Converts the CollationKey to a sequence of bits. If two CollationKeys 123 * could be legitimately compared, then one could compare the byte arrays 124 * for each of those keys to obtain the same result. Byte arrays are 125 * organized most significant byte first. 126 */ toByteArray()127 abstract public byte[] toByteArray(); 128 129 130 /** 131 * CollationKey constructor. 132 * 133 * @param source - the source string. 134 * @exception NullPointerException if <code>source</code> is null. 135 * @since 1.6 136 */ CollationKey(String source)137 protected CollationKey(String source) { 138 if (source==null){ 139 throw new NullPointerException(); 140 } 141 this.source = source; 142 } 143 144 final private String source; 145 } 146