1: /* AttributedCharacterIterator.java -- Iterate over attributes 2: Copyright (C) 1998, 1999, 2004, 2006, Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.text; 40: 41: import java.io.InvalidObjectException; 42: import java.io.Serializable; 43: import java.util.Map; 44: import java.util.Set; 45: 46: /** 47: * This interface extends the <code>CharacterIterator</code> interface 48: * in order to support iteration over character attributes as well as 49: * over the characters themselves. 50: * <p> 51: * In addition to attributes of specific characters, this interface 52: * supports the concept of the "attribute run", which is an attribute 53: * that is defined for a particular value across an entire range of 54: * characters or which is undefined over a range of characters. 55: * 56: * @since 1.2 57: * 58: * @author Aaron M. Renn (arenn@urbanophile.com) 59: * @since 1.2 60: */ 61: public interface AttributedCharacterIterator extends CharacterIterator 62: { 63: /** 64: * Defines attribute keys that are used as text attributes. 65: */ 66: public static class Attribute implements Serializable 67: { 68: private static final long serialVersionUID = -9142742483513960612L; 69: 70: /** 71: * This is the attribute for the language of the text. The value of 72: * attributes of this key type are instances of <code>Locale</code>. 73: */ 74: public static final Attribute LANGUAGE = new Attribute("language"); 75: 76: /** 77: * This is the attribute for the reading form of text. This is used 78: * for storing pronunciation along with the written text for languages 79: * which need it. The value of attributes of this key type are 80: * instances of <code>Annotation</code> which wrappers a 81: * <code>String</code>. 82: */ 83: public static final Attribute READING = new Attribute("reading"); 84: 85: /** 86: * This is the attribute for input method segments. The value of attributes 87: * of this key type are instances of <code>Annotation</code> which wrapper 88: * a <code>String</code>. 89: */ 90: public static final Attribute INPUT_METHOD_SEGMENT = 91: new Attribute("input_method_segment"); 92: 93: /** 94: * The name of the attribute key 95: * @serial 96: */ 97: private String name; 98: 99: /** 100: * Initializes a new instance of this class with the specified name. 101: * 102: * @param name The name of this attribute key. 103: */ 104: protected Attribute(String name) 105: { 106: this.name = name; 107: } 108: 109: /** 110: * Returns the name of this attribute. 111: * 112: * @return The attribute name 113: */ 114: protected String getName() 115: { 116: return name; 117: } 118: 119: /** 120: * Resolves an instance of 121: * <code>AttributedCharacterIterator.Attribute</code> 122: * that is being deserialized to one of the three pre-defined attribute 123: * constants. It does this by comparing the names of the attributes. The 124: * constant that the deserialized object resolves to is returned. 125: * 126: * @return The resolved contant value 127: * 128: * @exception InvalidObjectException If the object being deserialized 129: * cannot be resolved. 130: */ 131: protected Object readResolve() throws InvalidObjectException 132: { 133: if (getName().equals(READING.getName())) 134: return READING; 135: 136: if (getName().equals(LANGUAGE.getName())) 137: return LANGUAGE; 138: 139: if (getName().equals(INPUT_METHOD_SEGMENT.getName())) 140: return INPUT_METHOD_SEGMENT; 141: 142: throw new InvalidObjectException ("Can't resolve Attribute: " 143: + getName()); 144: } 145: 146: /** 147: * Tests this object for equality against the specified object. 148: * The two objects will be considered equal if and only if: 149: * <ul> 150: * <li>The specified object is not <code>null</code>. 151: * <li>The specified object is an instance of 152: * <code>AttributedCharacterIterator.Attribute</code>. 153: * <li>The specified object has the same attribute name as this object. 154: * </ul> 155: * 156: * @param obj the <code>Object</code> to test for equality against this 157: * object. 158: * 159: * @return <code>true</code> if the specified object is equal to this one, 160: * <code>false</code> otherwise. 161: */ 162: public final boolean equals(Object obj) 163: { 164: if (obj == this) 165: return true; 166: else 167: return false; 168: } 169: 170: /** 171: * Returns a hash value for this object. 172: * 173: * @return A hash value for this object. 174: */ 175: public final int hashCode() 176: { 177: return super.hashCode(); 178: } 179: 180: /** 181: * Returns a <code>String</code> representation of this object. 182: * 183: * @return A <code>String</code> representation of this object. 184: */ 185: public String toString() 186: { 187: return getClass().getName() + "(" + getName() + ")"; 188: } 189: 190: } // Inner class Attribute 191: 192: /** 193: * Returns a list of all keys that are defined for the 194: * text range. This can be an empty list if no attributes are defined. 195: * 196: * @return A list of keys 197: */ 198: Set<Attribute> getAllAttributeKeys(); 199: 200: /** 201: * Returns a <code>Map</code> of the attributes defined for the current 202: * character. 203: * 204: * @return A <code>Map</code> of the attributes for the current character. 205: */ 206: Map<Attribute, Object> getAttributes(); 207: 208: /** 209: * Returns the value of the specified attribute for the 210: * current character. If the attribute is not defined for the current 211: * character, <code>null</code> is returned. 212: * 213: * @param attrib The attribute to retrieve the value of. 214: * 215: * @return The value of the specified attribute 216: */ 217: Object getAttribute(AttributedCharacterIterator.Attribute attrib); 218: 219: /** 220: * Returns the index of the first character in the run that 221: * contains all attributes defined for the current character. 222: * 223: * @return The start index of the run 224: */ 225: int getRunStart(); 226: 227: /** 228: * Returns the index of the first character in the run that 229: * contains all attributes in the specified <code>Set</code> defined for 230: * the current character. 231: * 232: * @param attribs The <code>Set</code> of attributes. 233: * 234: * @return The start index of the run. 235: */ 236: int getRunStart(Set<? extends Attribute> attribs); 237: 238: /** 239: * Returns the index of the first character in the run that 240: * contains the specified attribute defined for the current character. 241: * 242: * @param attrib The attribute. 243: * 244: * @return The start index of the run. 245: */ 246: int getRunStart(AttributedCharacterIterator.Attribute attrib); 247: 248: /** 249: * Returns the index of the character after the end of the run 250: * that contains all attributes defined for the current character. 251: * 252: * @return The end index of the run. 253: */ 254: int getRunLimit(); 255: 256: /** 257: * Returns the index of the character after the end of the run 258: * that contains all attributes in the specified <code>Set</code> defined 259: * for the current character. 260: * 261: * @param attribs The <code>Set</code> of attributes. 262: * 263: * @return The end index of the run. 264: */ 265: int getRunLimit(Set<? extends Attribute> attribs); 266: 267: /** 268: * Returns the index of the character after the end of the run 269: * that contains the specified attribute defined for the current character. 270: * 271: * @param attrib The attribute. 272: * 273: * @return The end index of the run. 274: */ 275: int getRunLimit(AttributedCharacterIterator.Attribute attrib); 276: 277: } // interface AttributedCharacterIterator