1 /* 2 * Copyright (c) 1997, 2019, 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} represents a {@code String} under the 43 * rules of a specific {@code Collator} object. Comparing two 44 * {@code CollationKey}s returns the relative order of the 45 * {@code String}s they represent. Using {@code CollationKey}s 46 * to compare {@code String}s is generally faster than using 47 * {@code Collator.compare}. Thus, when the {@code String}s 48 * must be compared multiple times, for example when sorting a list 49 * of {@code String}s. It's more efficient to use {@code CollationKey}s. 50 * 51 * <p> 52 * You can not create {@code CollationKey}s directly. Rather, 53 * generate them by calling {@code Collator.getCollationKey}. 54 * You can only compare {@code CollationKey}s generated from 55 * the same {@code Collator} object. 56 * 57 * <p> 58 * Generating a {@code CollationKey} for a {@code String} 59 * involves examining the entire {@code String} 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}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}. 65 * {@code Collator.compare} 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}s might be used 69 * to sort a list of {@code String}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 * @since 1.1 99 */ 100 101 public abstract class CollationKey implements Comparable<CollationKey> { 102 /** 103 * Compare this CollationKey to the target CollationKey. The collation rules of the 104 * Collator object which created these keys are applied. <strong>Note:</strong> 105 * CollationKeys created by different Collators can not be compared. 106 * @param target target CollationKey 107 * @return Returns an integer value. Value is less than zero if this is less 108 * than target, value is zero if this and target are equal and value is greater than 109 * zero if this is greater than target. 110 * @see java.text.Collator#compare 111 */ compareTo(CollationKey target)112 public abstract int compareTo(CollationKey target); 113 114 /** 115 * Returns the String that this CollationKey represents. 116 * 117 * @return the source string of this CollationKey 118 */ getSourceString()119 public String getSourceString() { 120 return source; 121 } 122 123 124 /** 125 * Converts the CollationKey to a sequence of bits. If two CollationKeys 126 * could be legitimately compared, then one could compare the byte arrays 127 * for each of those keys to obtain the same result. Byte arrays are 128 * organized most significant byte first. 129 * 130 * @return a byte array representation of the CollationKey 131 */ toByteArray()132 public abstract byte[] toByteArray(); 133 134 135 /** 136 * CollationKey constructor. 137 * 138 * @param source the source string 139 * @throws NullPointerException if {@code source} is null 140 * @since 1.6 141 */ CollationKey(String source)142 protected CollationKey(String source) { 143 if (source==null){ 144 throw new NullPointerException(); 145 } 146 this.source = source; 147 } 148 149 private final String source; 150 } 151