libjava/java/text/AttributedCharacterIterator.java

   1 /* AttributedCharacterIterator.java -- Iterate over attributes
   2    Copyright (C) 1998, 1999, 2004 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.text;
  40
  41 import java.io.InvalidObjectException;
  42 import java.io.Serializable;
  43 import java.util.Map;
  44 import java.util.Set;
  45
  46 /**
  47  * This interface extends the <code>CharacterIterator</code> interface
  48  * in order to support iteration over character attributes as well as
  49  * over the characters themselves.
  50  * <p>
  51  * In addition to attributes of specific characters, this interface
  52  * supports the concept of the "attribute run", which is an attribute
  53  * that is defined for a particular value across an entire range of
  54  * characters or which is undefined over a range of characters.
  55  *
  56  * @author Aaron M. Renn (arenn@urbanophile.com)
  57  */
  58 public interface AttributedCharacterIterator extends CharacterIterator
  59 {
  60   /**
  61    * This class defines attribute keys that are used as text attributes.
  62    */
  63   public static class Attribute implements Serializable
  64   {
  65     private static final long serialVersionUID = -9142742483513960612L;
  66
  67     /**
  68      * This is the attribute for the language of the text.  The value of
  69      * attributes of this key type are instances of <code>Locale</code>.
  70      */
  71     public static final Attribute LANGUAGE = new Attribute ("LANGUAGE");
  72
  73     /**
  74      * This is the attribute for the reading form of text.  This is used
  75      * for storing pronunciation along with the written text for languages
  76      * which need it.  The value of attributes of this key type are
  77      * instances of <code>Annotation</code> which wrappers a <code>String</code>.
  78      */
  79     public static final Attribute READING = new Attribute ("READING");
  80
  81     /**
  82      * This is the attribute for input method segments.  The value of attributes
  83      * of this key type are instances of <code>Annotation</code> which wrapper
  84      * a <code>String</code>.
  85      */
  86     public static final Attribute INPUT_METHOD_SEGMENT =
  87       new Attribute ("INPUT_METHOD_SEGMENT");
  88
  89     /**
  90      * This is the name of the attribute key
  91      * @serial
  92      */
  93     private String name;
  94
  95     /**
  96      * This method initializes a new instance of this class with the specified
  97      * name.
  98      *
  99      * @param name The name of this attribute key.
 100      */
 101     protected Attribute (String name)
 102     {
 103       this.name = name;
 104     }
 105
 106     /**
 107      * This method returns the name of this attribute.
 108      *
 109      * @return The attribute name
 110      */
 111     protected String getName()
 112     {
 113       return name;
 114     }
 115
 116     /**
 117      * This method resolves an instance of <code>AttributedCharacterIterator.Attribute</code>
 118      * that is being deserialized to one of the three pre-defined attribute
 119      * constants.  It does this by comparing the names of the attributes.  The
 120      * constant that the deserialized object resolves to is returned.
 121      *
 122      * @return The resolved contant value
 123      *
 124      * @exception InvalidObjectException If the object being deserialized cannot be resolved.
 125      */
 126     protected Object readResolve() throws InvalidObjectException
 127     {
 128       if (this.equals (READING))
 129         return READING;
 130
 131       if (this.equals (LANGUAGE))
 132         return LANGUAGE;
 133
 134       if (this.equals (INPUT_METHOD_SEGMENT))
 135         return INPUT_METHOD_SEGMENT;
 136
 137       throw new InvalidObjectException ("Can't resolve Attribute: " + getName());
 138     }
 139
 140     /**
 141      * This method tests this object for equality against the specified object.
 142      * The two objects will be considered equal if and only if:
 143      * <ul>
 144      * <li>The specified object is not <code>null</code>.
 145      * <li>The specified object is an instance of <code>AttributedCharacterIterator.Attribute</code>.
 146      * <li>The specified object has the same attribute name as this object.
 147      * </ul>
 148      *
 149      * @param The <code>Object</code> to test for equality against this object.
 150      *
 151      * @return <code>true</code> if the specified object is equal to this one, <code>false</code> otherwise.
 152      */
 153     public final boolean equals (Object obj)
 154     {
 155       if (obj == this)
 156         return true;
 157       else
 158         return false;
 159     }
 160
 161     /**
 162      * This method returns a hash value for this object.
 163      *
 164      * @return A hash value for this object.
 165      */
 166     public final int hashCode()
 167     {
 168       return super.hashCode();
 169     }
 170
 171     /**
 172      * This method returns a <code>String</code> representation of this object.
 173      *
 174      * @return A <code>String</code> representation of this object.
 175      */
 176     public String toString()
 177     {
 178       return getClass().getName() + "(" + getName() + ")";
 179     }
 180
 181   } // Inner class Attribute
 182
 183   /**
 184    * This method returns a list of all keys that are defined for the
 185    * text range.  This can be an empty list if no attributes are defined.
 186    *
 187    * @return A list of keys
 188    */
 189   Set getAllAttributeKeys();
 190
 191   /**
 192    * This method returns a <code>Map</code> of the attributed defined for
 193    * the current character.
 194    *
 195    * @return A <code>Map</code> of the attributes for the current character.
 196    */
 197   Map getAttributes();
 198
 199   /**
 200    * This method returns the value of the specified attribute for the
 201    * current character.  If the attribute is not defined for the current
 202    * character, <code>null</code> is returned.
 203    *
 204    * @param attrib The attribute to retrieve the value of.
 205    *
 206    * @return The value of the specified attribute
 207    */
 208   Object getAttribute (AttributedCharacterIterator.Attribute attrib);
 209
 210   /**
 211    * This method returns the index of the first character in the run that
 212    * contains all attributes defined for the current character.
 213    *
 214    * @return The start index of the run
 215    */
 216   int getRunStart();
 217
 218   /**
 219    * This method returns the index of the first character in the run that
 220    * contains all attributes in the specified <code>Set</code> defined for
 221    * the current character.
 222    *
 223    * @param attribs The <code>Set</code> of attributes.
 224    *
 225    * @return The start index of the run.
 226    */
 227   int getRunStart (Set attribs);
 228
 229   /**
 230    * This method returns the index of the first character in the run that
 231    * contains the specified attribute defined for the current character.
 232    *
 233    * @param attrib The attribute.
 234    *
 235    * @return The start index of the run.
 236    */
 237   int getRunStart (AttributedCharacterIterator.Attribute attrib);
 238
 239   /**
 240    * This method returns the index of the character after the end of the run
 241    * that contains all attributed defined for the current character.
 242    *
 243    * @return The end index of the run.
 244    */
 245   int getRunLimit();
 246
 247   /**
 248    * This method returns the index of the character after the end of the run
 249    * that contains all attributes in the specified <code>Set</code> defined
 250    * for the current character.
 251    *
 252    * @param attribs The <code>Set</code> of attributes.
 253    *
 254    * @return The end index of the run.
 255    */
 256   int getRunLimit (Set attribs);
 257
 258   /**
 259    * This methods returns the index of the character after the end of the run
 260    * that contains the specified attribute defined for the current character.
 261    *
 262    * @param attrib The attribute.
 263    *
 264    * @return The end index of the run.
 265    */
 266   int getRunLimit (AttributedCharacterIterator.Attribute attrib);
 267
 268 } // interface AttributedCharacterIterator