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 package java.text; 27 28 import java.io.InvalidObjectException; 29 import java.io.Serializable; 30 import java.util.HashMap; 31 import java.util.Map; 32 import java.util.Set; 33 34 /** 35 * An {@code AttributedCharacterIterator} allows iteration through both text and 36 * related attribute information. 37 * 38 * <p> 39 * An attribute is a key/value pair, identified by the key. No two 40 * attributes on a given character can have the same key. 41 * 42 * <p>The values for an attribute are immutable, or must not be mutated 43 * by clients or storage. They are always passed by reference, and not 44 * cloned. 45 * 46 * <p>A <em>run with respect to an attribute</em> is a maximum text range for 47 * which: 48 * <ul> 49 * <li>the attribute is undefined or {@code null} for the entire range, or 50 * <li>the attribute value is defined and has the same non-{@code null} value for the 51 * entire range. 52 * </ul> 53 * 54 * <p>A <em>run with respect to a set of attributes</em> is a maximum text range for 55 * which this condition is met for each member attribute. 56 * 57 * <p>When getting a run with no explicit attributes specified (i.e., 58 * calling {@link #getRunStart()} and {@link #getRunLimit()}), any 59 * contiguous text segments having the same attributes (the same set 60 * of attribute/value pairs) are treated as separate runs if the 61 * attributes have been given to those text segments separately. 62 * 63 * <p>The returned indexes are limited to the range of the iterator. 64 * 65 * <p>The returned attribute information is limited to runs that contain 66 * the current character. 67 * 68 * <p> 69 * Attribute keys are instances of {@link AttributedCharacterIterator.Attribute} and its 70 * subclasses, such as {@link java.awt.font.TextAttribute}. 71 * 72 * @see AttributedCharacterIterator.Attribute 73 * @see java.awt.font.TextAttribute 74 * @see AttributedString 75 * @see Annotation 76 * @since 1.2 77 */ 78 79 public interface AttributedCharacterIterator extends CharacterIterator { 80 81 /** 82 * Defines attribute keys that are used to identify text attributes. These 83 * keys are used in {@code AttributedCharacterIterator} and {@code AttributedString}. 84 * @see AttributedCharacterIterator 85 * @see AttributedString 86 * @since 1.2 87 */ 88 89 public static class Attribute implements Serializable { 90 91 /** 92 * The name of this {@code Attribute}. The name is used primarily by {@code readResolve} 93 * to look up the corresponding predefined instance when deserializing 94 * an instance. 95 * @serial 96 */ 97 private String name; 98 99 // table of all instances in this class, used by readResolve 100 private static final Map<String, Attribute> instanceMap = new HashMap<>(7); 101 102 /** 103 * Constructs an {@code Attribute} with the given name. 104 * 105 * @param name the name of {@code Attribute} 106 */ 107 protected Attribute(String name) { 108 this.name = name; 109 if (this.getClass() == Attribute.class) { 110 instanceMap.put(name, this); 111 } 112 } 113 114 /** 115 * Compares two objects for equality. This version only returns true 116 * for {@code x.equals(y)} if {@code x} and {@code y} refer 117 * to the same object, and guarantees this for all subclasses. 118 */ 119 public final boolean equals(Object obj) { 120 return super.equals(obj); 121 } 122 123 /** 124 * Returns a hash code value for the object. This version is identical to 125 * the one in {@code Object}, but is also final. 126 */ 127 public final int hashCode() { 128 return super.hashCode(); 129 } 130 131 /** 132 * Returns a string representation of the object. This version returns the 133 * concatenation of class name, {@code "("}, a name identifying the attribute 134 * and {@code ")"}. 135 */ 136 public String toString() { 137 return getClass().getName() + "(" + name + ")"; 138 } 139 140 /** 141 * Returns the name of the attribute. 142 * 143 * @return the name of {@code Attribute} 144 */ 145 protected String getName() { 146 return name; 147 } 148 149 /** 150 * Resolves instances being deserialized to the predefined constants. 151 * 152 * @return the resolved {@code Attribute} object 153 * @throws InvalidObjectException if the object to resolve is not 154 * an instance of {@code Attribute} 155 */ 156 protected Object readResolve() throws InvalidObjectException { 157 if (this.getClass() != Attribute.class) { 158 throw new InvalidObjectException("subclass didn't correctly implement readResolve"); 159 } 160 161 Attribute instance = instanceMap.get(getName()); 162 if (instance != null) { 163 return instance; 164 } else { 165 throw new InvalidObjectException("unknown attribute name"); 166 } 167 } 168 169 /** 170 * Attribute key for the language of some text. 171 * <p> Values are instances of {@link java.util.Locale Locale}. 172 * @see java.util.Locale 173 */ 174 public static final Attribute LANGUAGE = new Attribute("language"); 175 176 /** 177 * Attribute key for the reading of some text. In languages where the written form 178 * and the pronunciation of a word are only loosely related (such as Japanese), 179 * it is often necessary to store the reading (pronunciation) along with the 180 * written form. 181 * <p>Values are instances of {@link Annotation} holding instances of {@link String}. 182 * 183 * @see Annotation 184 * @see java.lang.String 185 */ 186 public static final Attribute READING = new Attribute("reading"); 187 188 /** 189 * Attribute key for input method segments. Input methods often break 190 * up text into segments, which usually correspond to words. 191 * <p>Values are instances of {@link Annotation} holding a {@code null} reference. 192 * @see Annotation 193 */ 194 public static final Attribute INPUT_METHOD_SEGMENT = new Attribute("input_method_segment"); 195 196 // make sure the serial version doesn't change between compiler versions 197 private static final long serialVersionUID = -9142742483513960612L; 198 199 }; 200 201 /** 202 * Returns the index of the first character of the run 203 * with respect to all attributes containing the current character. 204 * 205 * <p>Any contiguous text segments having the same attributes (the 206 * same set of attribute/value pairs) are treated as separate runs 207 * if the attributes have been given to those text segments separately. 208 * 209 * @return the index of the first character of the run 210 */ 211 public int getRunStart(); 212 213 /** 214 * Returns the index of the first character of the run 215 * with respect to the given {@code attribute} containing the current character. 216 * 217 * @param attribute the desired attribute. 218 * @return the index of the first character of the run 219 */ 220 public int getRunStart(Attribute attribute); 221 222 /** 223 * Returns the index of the first character of the run 224 * with respect to the given {@code attributes} containing the current character. 225 * 226 * @param attributes a set of the desired attributes. 227 * @return the index of the first character of the run 228 */ 229 public int getRunStart(Set<? extends Attribute> attributes); 230 231 /** 232 * Returns the index of the first character following the run 233 * with respect to all attributes containing the current character. 234 * 235 * <p>Any contiguous text segments having the same attributes (the 236 * same set of attribute/value pairs) are treated as separate runs 237 * if the attributes have been given to those text segments separately. 238 * 239 * @return the index of the first character following the run 240 */ 241 public int getRunLimit(); 242 243 /** 244 * Returns the index of the first character following the run 245 * with respect to the given {@code attribute} containing the current character. 246 * 247 * @param attribute the desired attribute 248 * @return the index of the first character following the run 249 */ 250 public int getRunLimit(Attribute attribute); 251 252 /** 253 * Returns the index of the first character following the run 254 * with respect to the given {@code attributes} containing the current character. 255 * 256 * @param attributes a set of the desired attributes 257 * @return the index of the first character following the run 258 */ 259 public int getRunLimit(Set<? extends Attribute> attributes); 260 261 /** 262 * Returns a map with the attributes defined on the current 263 * character. 264 * 265 * @return a map with the attributes defined on the current character 266 */ 267 public Map<Attribute,Object> getAttributes(); 268 269 /** 270 * Returns the value of the named {@code attribute} for the current character. 271 * Returns {@code null} if the {@code attribute} is not defined. 272 * 273 * @param attribute the desired attribute 274 * @return the value of the named {@code attribute} or {@code null} 275 */ 276 public Object getAttribute(Attribute attribute); 277 278 /** 279 * Returns the keys of all attributes defined on the 280 * iterator's text range. The set is empty if no 281 * attributes are defined. 282 * 283 * @return the keys of all attributes 284 */ 285 public Set<Attribute> getAllAttributeKeys(); 286 }; 287
