1 /*
2 * Copyright 1997-2004 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 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 null for the entire range, or
50 * <li>the attribute value is defined and has the same non-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>The returned indexes are limited to the range of the iterator.
58 *
59 * <p>The returned attribute information is limited to runs that contain
60 * the current character.
61 *
62 * <p>
63 * Attribute keys are instances of AttributedCharacterIterator.Attribute and its
64 * subclasses, such as java.awt.font.TextAttribute.
65 *
66 * @see AttributedCharacterIterator.Attribute
67 * @see java.awt.font.TextAttribute
68 * @see AttributedString
69 * @see Annotation
70 * @since 1.2
71 */
72
73 public interface AttributedCharacterIterator extends CharacterIterator {
74
75 /**
76 * Defines attribute keys that are used to identify text attributes. These
77 * keys are used in AttributedCharacterIterator and AttributedString.
78 * @see AttributedCharacterIterator
79 * @see AttributedString
80 * @since 1.2
81 */
82
83 public static class Attribute implements Serializable {
84
85 /**
86 * The name of this Attribute. The name is used primarily by readResolve
87 * to look up the corresponding predefined instance when deserializing
88 * an instance.
89 * @serial
90 */
91 private String name;
92
93 // table of all instances in this class, used by readResolve
94 private static final Map instanceMap = new HashMap(7);
95
96 /**
97 * Constructs an Attribute with the given name.
98 */
99 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("subclass didn't correctly implement readResolve");
144 }
145
146 Attribute instance = (Attribute) instanceMap.get(getName());
147 if (instance != null) {
148 return instance;
149 } else {
150 throw new InvalidObjectException("unknown attribute name");
151 }
152 }
153
154 /**
155 * Attribute key for the language of some text.
156 * <p> Values are instances of Locale.
157 * @see java.util.Locale
158 */
159 public static final Attribute LANGUAGE = new Attribute("language");
160
161 /**
162 * Attribute key for the reading of some text. In languages where the written form
163 * and the pronunciation of a word are only loosely related (such as Japanese),
164 * it is often necessary to store the reading (pronunciation) along with the
165 * written form.
166 * <p>Values are instances of Annotation holding instances of String.
167 * @see Annotation
168 * @see java.lang.String
169 */
170 public static final Attribute READING = new Attribute("reading");
171
172 /**
173 * Attribute key for input method segments. Input methods often break
174 * up text into segments, which usually correspond to words.
175 * <p>Values are instances of Annotation holding a null reference.
176 * @see Annotation
177 */
178 public static final Attribute INPUT_METHOD_SEGMENT = new Attribute("input_method_segment");
179
180 // make sure the serial version doesn't change between compiler versions
181 private static final long serialVersionUID = -9142742483513960612L;
182
183 };
184
185 /**
186 * Returns the index of the first character of the run
187 * with respect to all attributes containing the current character.
188 */
189 public int getRunStart();
190
191 /**
192 * Returns the index of the first character of the run
193 * with respect to the given attribute containing the current character.
194 */
195 public int getRunStart(Attribute attribute);
196
197 /**
198 * Returns the index of the first character of the run
199 * with respect to the given attributes containing the current character.
200 */
201 public int getRunStart(Set<? extends Attribute> attributes);
202
203 /**
204 * Returns the index of the first character following the run
205 * with respect to all attributes containing the current character.
206 */
207 public int getRunLimit();
208
209 /**
210 * Returns the index of the first character following the run
211 * with respect to the given attribute containing the current character.
212 */
213 public int getRunLimit(Attribute attribute);
214
215 /**
216 * Returns the index of the first character following the run
217 * with respect to the given attributes containing the current character.
218 */
219 public int getRunLimit(Set<? extends Attribute> attributes);
220
221 /**
222 * Returns a map with the attributes defined on the current
223 * character.
224 */
225 public Map<Attribute,Object> getAttributes();
226
227 /**
228 * Returns the value of the named attribute for the current character.
229 * Returns null if the attribute is not defined.
230 * @param attribute the key of the attribute whose value is requested.
231 */
232 public Object getAttribute(Attribute attribute);
233
234 /**
235 * Returns the keys of all attributes defined on the
236 * iterator's text range. The set is empty if no
237 * attributes are defined.
238 */
239 public Set<Attribute> getAllAttributeKeys();
240 };
Save This Page