001 /*
002 * Copyright 1997-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.text;
027
028 import java.io.InvalidObjectException;
029 import java.io.Serializable;
030 import java.util.HashMap;
031 import java.util.Map;
032 import java.util.Set;
033
034 /**
035 * An AttributedCharacterIterator allows iteration through both text and
036 * related attribute information.
037 *
038 * <p>
039 * An attribute is a key/value pair, identified by the key. No two
040 * attributes on a given character can have the same key.
041 *
042 * <p>The values for an attribute are immutable, or must not be mutated
043 * by clients or storage. They are always passed by reference, and not
044 * cloned.
045 *
046 * <p>A <em>run with respect to an attribute</em> is a maximum text range for
047 * which:
048 * <ul>
049 * <li>the attribute is undefined or null for the entire range, or
050 * <li>the attribute value is defined and has the same non-null value for the
051 * entire range.
052 * </ul>
053 *
054 * <p>A <em>run with respect to a set of attributes</em> is a maximum text range for
055 * which this condition is met for each member attribute.
056 *
057 * <p>The returned indexes are limited to the range of the iterator.
058 *
059 * <p>The returned attribute information is limited to runs that contain
060 * the current character.
061 *
062 * <p>
063 * Attribute keys are instances of AttributedCharacterIterator.Attribute and its
064 * subclasses, such as java.awt.font.TextAttribute.
065 *
066 * @see AttributedCharacterIterator.Attribute
067 * @see java.awt.font.TextAttribute
068 * @see AttributedString
069 * @see Annotation
070 * @since 1.2
071 */
072
073 public interface AttributedCharacterIterator extends CharacterIterator {
074
075 /**
076 * Defines attribute keys that are used to identify text attributes. These
077 * keys are used in AttributedCharacterIterator and AttributedString.
078 * @see AttributedCharacterIterator
079 * @see AttributedString
080 * @since 1.2
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 // make sure the serial version doesn't change between compiler versions
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<? extends Attribute> 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<? extends Attribute> attributes);
224
225 /**
226 * Returns a map with the attributes defined on the current
227 * character.
228 */
229 public Map<Attribute, Object> 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<Attribute> getAllAttributeKeys();
244 };
|