001: /*
002: * @(#)AttributedCharacterIterator.java 1.34 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.text;
029:
030: import java.io.InvalidObjectException;
031: import java.io.Serializable;
032: import java.util.HashMap;
033: import java.util.Map;
034: import java.util.Set;
035:
036: /**
037: * An AttributedCharacterIterator allows iteration through both text and
038: * related attribute information.
039: *
040: * <p>
041: * An attribute is a key/value pair, identified by the key. No two
042: * attributes on a given character can have the same key.
043: *
044: * <p>The values for an attribute are immutable, or must not be mutated
045: * by clients or storage. They are always passed by reference, and not
046: * cloned.
047: *
048: * <p>A <em>run with respect to an attribute</em> is a maximum text range for
049: * which:
050: * <ul>
051: * <li>the attribute is undefined or null for the entire range, or
052: * <li>the attribute value is defined and has the same non-null value for the
053: * entire range.
054: * </ul>
055: *
056: * <p>A <em>run with respect to a set of attributes</em> is a maximum text range for
057: * which this condition is met for each member attribute.
058: *
059: * <p>The returned indexes are limited to the range of the iterator.
060: *
061: * <p>The returned attribute information is limited to runs that contain
062: * the current character.
063: *
064: * <p>
065: * Attribute keys are instances of AttributedCharacterIterator.Attribute and its
066: * subclasses.
067: *
068: * @see AttributedCharacterIterator.Attribute
069: * @see AttributedString
070: * @see Annotation
071: * @since 1.2
072: */
073:
074: public interface AttributedCharacterIterator extends CharacterIterator {
075:
076: /**
077: * Defines attribute keys that are used to identify text attributes. These
078: * keys are used in AttributedCharacterIterator and AttributedString.
079: * @see AttributedCharacterIterator
080: * @see AttributedString
081: */
082:
083: public static class Attribute implements Serializable {
084:
085: /**
086: * The name of this Attribute. The name is used primarily by readResolve
087: * to look up the corresponding predefined instance when deserializing
088: * an instance.
089: * @serial
090: */
091: private String name;
092:
093: // table of all instances in this class, used by readResolve
094: private static final Map instanceMap = new HashMap(7);
095:
096: /**
097: * Constructs an Attribute with the given name.
098: */
099: protected Attribute(String name) {
100: this .name = name;
101: if (this .getClass() == Attribute.class) {
102: instanceMap.put(name, this );
103: }
104: }
105:
106: /**
107: * Compares two objects for equality. This version only returns true
108: * for <code>x.equals(y)</code> if <code>x</code> and <code>y</code> refer
109: * to the same object, and guarantees this for all subclasses.
110: */
111: public final boolean equals(Object obj) {
112: return super .equals(obj);
113: }
114:
115: /**
116: * Returns a hash code value for the object. This version is identical to
117: * the one in Object, but is also final.
118: */
119: public final int hashCode() {
120: return super .hashCode();
121: }
122:
123: /**
124: * Returns a string representation of the object. This version returns the
125: * concatenation of class name, "(", a name identifying the attribute and ")".
126: */
127: public String toString() {
128: return getClass().getName() + "(" + name + ")";
129: }
130:
131: /**
132: * Returns the name of the attribute.
133: */
134: protected String getName() {
135: return name;
136: }
137:
138: /**
139: * Resolves instances being deserialized to the predefined constants.
140: */
141: protected Object readResolve() throws InvalidObjectException {
142: if (this .getClass() != Attribute.class) {
143: throw new InvalidObjectException(
144: "subclass didn't correctly implement readResolve");
145: }
146:
147: Attribute instance = (Attribute) instanceMap.get(getName());
148: if (instance != null) {
149: return instance;
150: } else {
151: throw new InvalidObjectException(
152: "unknown attribute name");
153: }
154: }
155:
156: /**
157: * Attribute key for the language of some text.
158: * <p> Values are instances of Locale.
159: * @see java.util.Locale
160: */
161: public static final Attribute LANGUAGE = new Attribute(
162: "language");
163:
164: /**
165: * Attribute key for the reading of some text. In languages where the written form
166: * and the pronunciation of a word are only loosely related (such as Japanese),
167: * it is often necessary to store the reading (pronunciation) along with the
168: * written form.
169: * <p>Values are instances of Annotation holding instances of String.
170: * @see Annotation
171: * @see java.lang.String
172: */
173: public static final Attribute READING = new Attribute("reading");
174:
175: /**
176: * Attribute key for input method segments. Input methods often break
177: * up text into segments, which usually correspond to words.
178: * <p>Values are instances of Annotation holding a null reference.
179: * @see Annotation
180: */
181: public static final Attribute INPUT_METHOD_SEGMENT = new Attribute(
182: "input_method_segment");
183:
184: /* Declare serialVersionUID for interoperability */
185: private static final long serialVersionUID = -9142742483513960612L;
186:
187: };
188:
189: /**
190: * Returns the index of the first character of the run
191: * with respect to all attributes containing the current character.
192: */
193: public int getRunStart();
194:
195: /**
196: * Returns the index of the first character of the run
197: * with respect to the given attribute containing the current character.
198: */
199: public int getRunStart(Attribute attribute);
200:
201: /**
202: * Returns the index of the first character of the run
203: * with respect to the given attributes containing the current character.
204: */
205: public int getRunStart(Set attributes);
206:
207: /**
208: * Returns the index of the first character following the run
209: * with respect to all attributes containing the current character.
210: */
211: public int getRunLimit();
212:
213: /**
214: * Returns the index of the first character following the run
215: * with respect to the given attribute containing the current character.
216: */
217: public int getRunLimit(Attribute attribute);
218:
219: /**
220: * Returns the index of the first character following the run
221: * with respect to the given attributes containing the current character.
222: */
223: public int getRunLimit(Set attributes);
224:
225: /**
226: * Returns a map with the attributes defined on the current
227: * character.
228: */
229: public Map getAttributes();
230:
231: /**
232: * Returns the value of the named attribute for the current character.
233: * Returns null if the attribute is not defined.
234: * @param attribute the key of the attribute whose value is requested.
235: */
236: public Object getAttribute(Attribute attribute);
237:
238: /**
239: * Returns the keys of all attributes defined on the
240: * iterator's text range. The set is empty if no
241: * attributes are defined.
242: */
243: public Set getAllAttributeKeys();
244: };
|