AttributedCharacterIterator


1   /*
2    * @(#)AttributedCharacterIterator.java 1.32 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.text;
9   
10  import java.io.InvalidObjectException  ;
11  import java.io.Serializable  ;
12  import java.util.HashMap  ;
13  import java.util.Map  ;
14  import java.util.Set  ;
15  
16  /**
17   * An AttributedCharacterIterator allows iteration through both text and
18   * related attribute information.
19   *
20   * <p>
21   * An attribute is a key/value pair, identified by the key.  No two
22   * attributes on a given character can have the same key.
23   *
24   * <p>The values for an attribute are immutable, or must not be mutated
25   * by clients or storage.  They are always passed by reference, and not
26   * cloned.
27   *
28   * <p>A <em>run with respect to an attribute</em> is a maximum text range for
29   * which:
30   * <ul>
31   * <li>the attribute is undefined or null for the entire range, or
32   * <li>the attribute value is defined and has the same non-null value for the
33   *     entire range.
34   * </ul>
35   *
36   * <p>A <em>run with respect to a set of attributes</em> is a maximum text range for
37   * which this condition is met for each member attribute.
38   *
39   * <p>The returned indexes are limited to the range of the iterator.
40   *
41   * <p>The returned attribute information is limited to runs that contain
42   * the current character.
43   *
44   * <p>
45   * Attribute keys are instances of AttributedCharacterIterator.Attribute and its
46   * subclasses, such as java.awt.font.TextAttribute.
47   *
48   * @see AttributedCharacterIterator.Attribute
49   * @see java.awt.font.TextAttribute
50   * @see AttributedString
51   * @see Annotation
52   * @since 1.2
53   */
54  
55  public interface AttributedCharacterIterator extends CharacterIterator   {
56  
57      /**
58       * Defines attribute keys that are used to identify text attributes. These
59       * keys are used in AttributedCharacterIterator and AttributedString.
60       * @see AttributedCharacterIterator
61       * @see AttributedString
62       * @since 1.2
63       */
64  
65      public static class Attribute implements Serializable   {
66  
67          /**
68           * The name of this Attribute. The name is used primarily by readResolve
69           * to look up the corresponding predefined instance when deserializing
70           * an instance.
71           * @serial
72           */
73          private String   name;
74  
75          // table of all instances in this class, used by readResolve
76          private static final Map   instanceMap = new HashMap  (7);
77  
78          /**
79           * Constructs an Attribute with the given name.
80           */
81          protected Attribute(String   name) {
82              this.name = name;
83              if (this.getClass() == Attribute.class) {
84                  instanceMap.put(name, this);
85              }
86          }
87  
88          /**
89           * Compares two objects for equality. This version only returns true
90           * for <code>x.equals(y)</code> if <code>x</code> and <code>y</code> refer
91           * to the same object, and guarantees this for all subclasses.
92           */
93          public final boolean equals(Object   obj) {
94              return super.equals(obj);
95          }
96  
97          /**
98           * Returns a hash code value for the object. This version is identical to
99           * the one in Object, but is also final.
100          */
101         public final int hashCode() {
102             return super.hashCode();
103         }
104 
105         /**
106          * Returns a string representation of the object. This version returns the
107          * concatenation of class name, "(", a name identifying the attribute and ")".
108          */
109         public String   toString() {
110             return getClass().getName() + "(" + name + ")";
111         }
112 
113         /**
114          * Returns the name of the attribute.
115          */
116         protected String   getName() {
117             return name;
118         }
119 
120         /**
121          * Resolves instances being deserialized to the predefined constants.
122          */
123         protected Object   readResolve() throws InvalidObjectException   {
124             if (this.getClass() != Attribute.class) {
125                 throw new InvalidObjectException  ("subclass didn't correctly implement readResolve");
126             }
127 
128             Attribute instance = (Attribute) instanceMap.get(getName());
129             if (instance != null) {
130                 return instance;
131             } else {
132                 throw new InvalidObjectException  ("unknown attribute name");
133             }
134         }
135 
136         /**
137          * Attribute key for the language of some text.
138          * <p> Values are instances of Locale.
139          * @see java.util.Locale
140          */
141         public static final Attribute LANGUAGE = new Attribute("language");
142 
143         /**
144          * Attribute key for the reading of some text. In languages where the written form
145          * and the pronunciation of a word are only loosely related (such as Japanese),
146          * it is often necessary to store the reading (pronunciation) along with the
147          * written form.
148          * <p>Values are instances of Annotation holding instances of String.
149          * @see Annotation
150          * @see java.lang.String
151          */
152         public static final Attribute READING = new Attribute("reading");
153 
154         /**
155          * Attribute key for input method segments. Input methods often break
156          * up text into segments, which usually correspond to words.
157          * <p>Values are instances of Annotation holding a null reference.
158          * @see Annotation
159          */
160         public static final Attribute INPUT_METHOD_SEGMENT = new Attribute("input_method_segment");
161 
162         // make sure the serial version doesn't change between compiler versions
163         private static final long serialVersionUID = -9142742483513960612L;
164 
165     };
166 
167     /**
168      * Returns the index of the first character of the run
169      * with respect to all attributes containing the current character.
170      */
171     public int getRunStart();
172 
173     /**
174      * Returns the index of the first character of the run
175      * with respect to the given attribute containing the current character.
176      */
177     public int getRunStart(Attribute attribute);
178 
179     /**
180      * Returns the index of the first character of the run
181      * with respect to the given attributes containing the current character.
182      */
183     public int getRunStart(Set  <? extends Attribute> attributes);
184 
185     /**
186      * Returns the index of the first character following the run
187      * with respect to all attributes containing the current character.
188      */
189     public int getRunLimit();
190 
191     /**
192      * Returns the index of the first character following the run
193      * with respect to the given attribute containing the current character.
194      */
195     public int getRunLimit(Attribute attribute);
196 
197     /**
198      * Returns the index of the first character following the run
199      * with respect to the given attributes containing the current character.
200      */
201     public int getRunLimit(Set  <? extends Attribute> attributes);
202 
203     /**
204      * Returns a map with the attributes defined on the current
205      * character.
206      */
207     public Map  <Attribute,Object  > getAttributes();
208 
209     /**
210      * Returns the value of the named attribute for the current character.
211      * Returns null if the attribute is not defined.
212      * @param attribute the key of the attribute whose value is requested.
213      */
214     public Object   getAttribute(Attribute attribute);
215 
216     /**
217      * Returns the keys of all attributes defined on the
218      * iterator's text range. The set is empty if no
219      * attributes are defined.
220      */
221     public Set  <Attribute> getAllAttributeKeys();
222 };
223
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags