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 20import java.io.InvalidObjectException; 21import java.io.Serializable; 22import java.util.Map; 23import java.util.Set; 24 25import org.apache.harmony.text.internal.nls.Messages; 26 27/** 28 * Extends the 29 * {@link CharacterIterator} interface, adding support for iterating over 30 * attributes and not only characters. An 31 * {@code AttributedCharacterIterator} also allows the user to find runs and 32 * their limits. Runs are defined as ranges of characters that all have the same 33 * attributes with the same values. 34 */ 35public interface AttributedCharacterIterator extends CharacterIterator { 36 37 /** 38 * Defines keys for text attributes. 39 */ 40 public static class Attribute implements Serializable { 41 42 private static final long serialVersionUID = -9142742483513960612L; 43 44 /** 45 * This attribute marks segments from an input method. Most input 46 * methods create these segments for words. 47 * 48 * The value objects are of the type {@code Annotation} which contain 49 * {@code null}. 50 */ 51 public static final Attribute INPUT_METHOD_SEGMENT = new Attribute( 52 "input_method_segment"); //$NON-NLS-1$ 53 54 /** 55 * The attribute describing the language of a character. The value 56 * objects are of type {@code Locale} or a subtype of it. 57 */ 58 public static final Attribute LANGUAGE = new Attribute("language"); //$NON-NLS-1$ 59 60 /** 61 * For languages that have different reading directions of text (like 62 * Japanese), this attribute allows to define which reading should be 63 * used. The value objects are of type {@code Annotation} which 64 * contain a {@code String}. 65 */ 66 public static final Attribute READING = new Attribute("reading"); //$NON-NLS-1$ 67 68 private String name; 69 70 /** 71 * The constructor for an {@code Attribute} with the name passed. 72 * 73 * @param name 74 * the name of the new {@code Attribute}. 75 */ 76 protected Attribute(String name) { 77 this.name = name; 78 } 79 80 /** 81 * Compares this attribute with the specified object. Checks if both 82 * objects are the same instance. It is defined final so all subclasses 83 * have the same behavior for this method. 84 * 85 * @param object 86 * the object to compare against. 87 * @return {@code true} if the object passed is equal to this instance; 88 * {@code false} otherwise. 89 */ 90 @Override 91 public final boolean equals(Object object) { 92 return this == object; 93 } 94 95 /** 96 * Returns the name of this attribute. 97 * 98 * @return the name of this attribute. 99 */ 100 protected String getName() { 101 return name; 102 } 103 104 /** 105 * Calculates the hash code for objects of type {@code Attribute}. It 106 * is defined final so all sub types calculate their hash code 107 * identically. 108 * 109 * @return the hash code for this instance of {@code Attribute}. 110 */ 111 @Override 112 public final int hashCode() { 113 return super.hashCode(); 114 } 115 116 /** 117 * Resolves a deserialized instance to the correct constant attribute. 118 * 119 * @return the {@code Attribute} this instance represents. 120 * @throws InvalidObjectException 121 * if this instance is not of type {@code Attribute.class} 122 * or if it is not a known {@code Attribute}. 123 */ 124 protected Object readResolve() throws InvalidObjectException { 125 if (this.getClass() != Attribute.class) { 126 // text.0C=cannot resolve subclasses 127 throw new InvalidObjectException(Messages.getString("text.0C")); //$NON-NLS-1$ 128 } 129 // BEGIN android-changed 130 // call getName() only once 131 String name = this.getName(); 132 if (name.equals(INPUT_METHOD_SEGMENT.getName())) { 133 return INPUT_METHOD_SEGMENT; 134 } 135 if (name.equals(LANGUAGE.getName())) { 136 return LANGUAGE; 137 } 138 if (name.equals(READING.getName())) { 139 return READING; 140 } 141 // END android-changed 142 // text.02=Unknown attribute 143 throw new InvalidObjectException(Messages.getString("text.02")); //$NON-NLS-1$ 144 } 145 146 /** 147 * Returns the name of the class followed by a "(", the name of the 148 * attribute, and a ")". 149 * 150 * @return the string representing this instance. 151 */ 152 @Override 153 public String toString() { 154 return getClass().getName() + '(' + getName() + ')'; 155 } 156 } 157 158 /** 159 * Returns a set of attributes present in the {@code 160 * AttributedCharacterIterator}. An empty set is returned if no attributes 161 * were defined. 162 * 163 * @return a set of attribute keys; may be empty. 164 */ 165 public Set<Attribute> getAllAttributeKeys(); 166 167 /** 168 * Returns the value stored in the attribute for the current character. If 169 * the attribute was not defined then {@code null} is returned. 170 * 171 * @param attribute the attribute for which the value should be returned. 172 * @return the value of the requested attribute for the current character or 173 * {@code null} if it was not defined. 174 */ 175 public Object getAttribute(Attribute attribute); 176 177 /** 178 * Returns a map of all attributes of the current character. If no 179 * attributes were defined for the current character then an empty map is 180 * returned. 181 * 182 * @return a map of all attributes for the current character or an empty 183 * map. 184 */ 185 public Map<Attribute, Object> getAttributes(); 186 187 /** 188 * Returns the index of the last character in the run having the same 189 * attributes as the current character. 190 * 191 * @return the index of the last character of the current run. 192 */ 193 public int getRunLimit(); 194 195 /** 196 * Returns the index of the last character in the run that has the same 197 * attribute value for the given attribute as the current character. 198 * 199 * @param attribute 200 * the attribute which the run is based on. 201 * @return the index of the last character of the current run. 202 */ 203 public int getRunLimit(Attribute attribute); 204 205 /** 206 * Returns the index of the last character in the run that has the same 207 * attribute values for the attributes in the set as the current character. 208 * 209 * @param attributes 210 * the set of attributes which the run is based on. 211 * @return the index of the last character of the current run. 212 */ 213 public int getRunLimit(Set<? extends Attribute> attributes); 214 215 /** 216 * Returns the index of the first character in the run that has the same 217 * attributes as the current character. 218 * 219 * @return the index of the last character of the current run. 220 */ 221 public int getRunStart(); 222 223 /** 224 * Returns the index of the first character in the run that has the same 225 * attribute value for the given attribute as the current character. 226 * 227 * @param attribute 228 * the attribute which the run is based on. 229 * @return the index of the last character of the current run. 230 */ 231 public int getRunStart(Attribute attribute); 232 233 /** 234 * Returns the index of the first character in the run that has the same 235 * attribute values for the attributes in the set as the current character. 236 * 237 * @param attributes 238 * the set of attributes which the run is based on. 239 * @return the index of the last character of the current run. 240 */ 241 public int getRunStart(Set<? extends Attribute> attributes); 242} 243