1 /* 2 * Copyright (c) 1997, 2013, 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>{@code 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 * 80 * //... 81 * 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 * 86 * //... 87 * 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 * 116 * @return the source string of this CollationKey 117 */ getSourceString()118 public String getSourceString() { 119 return source; 120 } 121 122 123 /** 124 * Converts the CollationKey to a sequence of bits. If two CollationKeys 125 * could be legitimately compared, then one could compare the byte arrays 126 * for each of those keys to obtain the same result. Byte arrays are 127 * organized most significant byte first. 128 * 129 * @return a byte array representation of the CollationKey 130 */ toByteArray()131 abstract public byte[] toByteArray(); 132 133 134 /** 135 * CollationKey constructor. 136 * 137 * @param source the source string 138 * @exception NullPointerException if {@code source} is null 139 * @since 1.6 140 */ CollationKey(String source)141 protected CollationKey(String source) { 142 if (source==null){ 143 throw new NullPointerException(); 144 } 145 this.source = source; 146 } 147 148 final private String source; 149 } 150