Source for java.text.AttributedCharacterIterator

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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