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:    * 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 
  78:      * <code>String</code>.
  79:      */
  80:     public static final Attribute READING = new Attribute ("READING");
  81: 
  82:     /**
  83:      * This is the attribute for input method segments.  The value of attributes
  84:      * of this key type are instances of <code>Annotation</code> which wrapper
  85:      * a <code>String</code>.
  86:      */
  87:     public static final Attribute INPUT_METHOD_SEGMENT =
  88:       new Attribute ("INPUT_METHOD_SEGMENT");
  89: 
  90:     /**
  91:      * The name of the attribute key
  92:      * @serial
  93:      */
  94:     private String name;
  95: 
  96:     /**
  97:      * Initializes a new instance of this class with the specified 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:      * 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:      * Resolves an instance of 
 118:      * <code>AttributedCharacterIterator.Attribute</code>
 119:      * that is being deserialized to one of the three pre-defined attribute
 120:      * constants.  It does this by comparing the names of the attributes.  The
 121:      * constant that the deserialized object resolves to is returned.
 122:      *
 123:      * @return The resolved contant value
 124:      *
 125:      * @exception InvalidObjectException If the object being deserialized 
 126:      *            cannot be resolved.
 127:      */
 128:     protected Object readResolve() throws InvalidObjectException
 129:     {
 130:       if (this.equals (READING))
 131:         return READING;
 132: 
 133:       if (this.equals (LANGUAGE))
 134:         return LANGUAGE;
 135: 
 136:       if (this.equals (INPUT_METHOD_SEGMENT))
 137:         return INPUT_METHOD_SEGMENT;
 138: 
 139:       throw new InvalidObjectException ("Can't resolve Attribute: " 
 140:               + getName());
 141:     }
 142:     
 143:     /**
 144:      * Tests this object for equality against the specified object.
 145:      * The two objects will be considered equal if and only if:
 146:      * <ul>
 147:      * <li>The specified object is not <code>null</code>.
 148:      * <li>The specified object is an instance of 
 149:      * <code>AttributedCharacterIterator.Attribute</code>.
 150:      * <li>The specified object has the same attribute name as this object.
 151:      * </ul>
 152:      *
 153:      * @param obj  the <code>Object</code> to test for equality against this 
 154:      *             object.
 155:      *
 156:      * @return <code>true</code> if the specified object is equal to this one, 
 157:      *         <code>false</code> otherwise.
 158:      */
 159:     public final boolean equals (Object obj)
 160:     {
 161:       if (obj == this)
 162:         return true;
 163:       else 
 164:         return false;
 165:     }
 166: 
 167:     /**
 168:      * Returns a hash value for this object.
 169:      *
 170:      * @return A hash value for this object.
 171:      */
 172:     public final int hashCode()
 173:     {
 174:       return super.hashCode();
 175:     }
 176: 
 177:     /**
 178:      * Returns a <code>String</code> representation of this object.
 179:      *
 180:      * @return A <code>String</code> representation of this object.
 181:      */
 182:     public String toString()
 183:     {
 184:       return getClass().getName() + "(" + getName() + ")";
 185:     }
 186: 
 187:   } // Inner class Attribute
 188: 
 189:   /**
 190:    * Returns a list of all keys that are defined for the 
 191:    * text range.  This can be an empty list if no attributes are defined.
 192:    *
 193:    * @return A list of keys 
 194:    */
 195:   Set getAllAttributeKeys();
 196: 
 197:   /**
 198:    * Returns a <code>Map</code> of the attributes defined for the current 
 199:    * character.
 200:    *
 201:    * @return A <code>Map</code> of the attributes for the current character.
 202:    */
 203:   Map getAttributes();
 204: 
 205:   /**
 206:    * Returns the value of the specified attribute for the
 207:    * current character.  If the attribute is not defined for the current
 208:    * character, <code>null</code> is returned.
 209:    *
 210:    * @param attrib The attribute to retrieve the value of.
 211:    *
 212:    * @return The value of the specified attribute
 213:    */
 214:   Object getAttribute (AttributedCharacterIterator.Attribute attrib);
 215: 
 216:   /**
 217:    * Returns the index of the first character in the run that
 218:    * contains all attributes defined for the current character.
 219:    *
 220:    * @return The start index of the run
 221:    */
 222:   int getRunStart();
 223: 
 224:   /**
 225:    * Returns the index of the first character in the run that
 226:    * contains all attributes in the specified <code>Set</code> defined for
 227:    * the current character.
 228:    *
 229:    * @param attribs The <code>Set</code> of attributes.
 230:    *
 231:    * @return The start index of the run.
 232:    */
 233:   int getRunStart (Set attribs);
 234:   
 235:   /**
 236:    * Returns the index of the first character in the run that
 237:    * contains the specified attribute defined for the current character.
 238:    *
 239:    * @param attrib The attribute.
 240:    *
 241:    * @return The start index of the run.
 242:    */
 243:   int getRunStart (AttributedCharacterIterator.Attribute attrib);
 244:   
 245:   /**
 246:    * Returns the index of the character after the end of the run
 247:    * that contains all attributes defined for the current character.
 248:    *
 249:    * @return The end index of the run.
 250:    */
 251:   int getRunLimit();
 252:   
 253:   /**
 254:    * Returns the index of the character after the end of the run
 255:    * that contains all attributes in the specified <code>Set</code> defined
 256:    * for the current character.
 257:    *
 258:    * @param attribs The <code>Set</code> of attributes.
 259:    *
 260:    * @return The end index of the run.
 261:    */
 262:   int getRunLimit (Set attribs);
 263:   
 264:   /**
 265:    * Returns the index of the character after the end of the run
 266:    * that contains the specified attribute defined for the current character.
 267:    *
 268:    * @param attrib The attribute.
 269:    * 
 270:    * @return The end index of the run.
 271:    */
 272:   int getRunLimit (AttributedCharacterIterator.Attribute attrib);
 273: 
 274: } // interface AttributedCharacterIterator