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