Source for java.text.AttributedCharacterIterator

   1: /* AttributedCharacterIterator.java -- Iterate over attributes
   2:    Copyright (C) 1998, 1999, 2004, 2006, 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:  * @since 1.2
  57:  * 
  58:  * @author Aaron M. Renn (arenn@urbanophile.com)
  59:  * @since 1.2
  60:  */
  61: public interface AttributedCharacterIterator extends CharacterIterator
  62: {
  63:   /**
  64:    * Defines attribute keys that are used as text attributes.
  65:    */
  66:   public static class Attribute implements Serializable
  67:   {
  68:     private static final long serialVersionUID = -9142742483513960612L;
  69: 
  70:     /**
  71:      * This is the attribute for the language of the text.  The value of
  72:      * attributes of this key type are instances of <code>Locale</code>.
  73:      */
  74:     public static final Attribute LANGUAGE = new Attribute("language");
  75: 
  76:     /**
  77:      * This is the attribute for the reading form of text.  This is used
  78:      * for storing pronunciation along with the written text for languages
  79:      * which need it.  The value of attributes of this key type are
  80:      * instances of <code>Annotation</code> which wrappers a 
  81:      * <code>String</code>.
  82:      */
  83:     public static final Attribute READING = new Attribute("reading");
  84: 
  85:     /**
  86:      * This is the attribute for input method segments.  The value of attributes
  87:      * of this key type are instances of <code>Annotation</code> which wrapper
  88:      * a <code>String</code>.
  89:      */
  90:     public static final Attribute INPUT_METHOD_SEGMENT =
  91:       new Attribute("input_method_segment");
  92: 
  93:     /**
  94:      * The name of the attribute key
  95:      * @serial
  96:      */
  97:     private String name;
  98: 
  99:     /**
 100:      * Initializes a new instance of this class with the specified name.
 101:      *
 102:      * @param name The name of this attribute key.
 103:      */
 104:     protected Attribute(String name)
 105:     {
 106:       this.name = name;
 107:     }
 108: 
 109:     /**
 110:      * Returns the name of this attribute.
 111:      *
 112:      * @return The attribute name
 113:      */
 114:     protected String getName()
 115:     {
 116:       return name;
 117:     }
 118: 
 119:     /**
 120:      * Resolves an instance of 
 121:      * <code>AttributedCharacterIterator.Attribute</code>
 122:      * that is being deserialized to one of the three pre-defined attribute
 123:      * constants.  It does this by comparing the names of the attributes.  The
 124:      * constant that the deserialized object resolves to is returned.
 125:      *
 126:      * @return The resolved contant value
 127:      *
 128:      * @exception InvalidObjectException If the object being deserialized 
 129:      *            cannot be resolved.
 130:      */
 131:     protected Object readResolve() throws InvalidObjectException
 132:     {
 133:       if (getName().equals(READING.getName()))
 134:         return READING;
 135: 
 136:       if (getName().equals(LANGUAGE.getName()))
 137:         return LANGUAGE;
 138: 
 139:       if (getName().equals(INPUT_METHOD_SEGMENT.getName()))
 140:         return INPUT_METHOD_SEGMENT;
 141: 
 142:       throw new InvalidObjectException ("Can't resolve Attribute: " 
 143:               + getName());
 144:     }
 145:     
 146:     /**
 147:      * Tests this object for equality against the specified object.
 148:      * The two objects will be considered equal if and only if:
 149:      * <ul>
 150:      * <li>The specified object is not <code>null</code>.
 151:      * <li>The specified object is an instance of 
 152:      * <code>AttributedCharacterIterator.Attribute</code>.
 153:      * <li>The specified object has the same attribute name as this object.
 154:      * </ul>
 155:      *
 156:      * @param obj  the <code>Object</code> to test for equality against this 
 157:      *             object.
 158:      *
 159:      * @return <code>true</code> if the specified object is equal to this one, 
 160:      *         <code>false</code> otherwise.
 161:      */
 162:     public final boolean equals(Object obj)
 163:     {
 164:       if (obj == this)
 165:         return true;
 166:       else 
 167:         return false;
 168:     }
 169: 
 170:     /**
 171:      * Returns a hash value for this object.
 172:      *
 173:      * @return A hash value for this object.
 174:      */
 175:     public final int hashCode()
 176:     {
 177:       return super.hashCode();
 178:     }
 179: 
 180:     /**
 181:      * Returns a <code>String</code> representation of this object.
 182:      *
 183:      * @return A <code>String</code> representation of this object.
 184:      */
 185:     public String toString()
 186:     {
 187:       return getClass().getName() + "(" + getName() + ")";
 188:     }
 189: 
 190:   } // Inner class Attribute
 191: 
 192:   /**
 193:    * Returns a list of all keys that are defined for the 
 194:    * text range.  This can be an empty list if no attributes are defined.
 195:    *
 196:    * @return A list of keys 
 197:    */
 198:   Set<Attribute> getAllAttributeKeys();
 199: 
 200:   /**
 201:    * Returns a <code>Map</code> of the attributes defined for the current 
 202:    * character.
 203:    *
 204:    * @return A <code>Map</code> of the attributes for the current character.
 205:    */
 206:   Map<Attribute, Object> getAttributes();
 207: 
 208:   /**
 209:    * Returns the value of the specified attribute for the
 210:    * current character.  If the attribute is not defined for the current
 211:    * character, <code>null</code> is returned.
 212:    *
 213:    * @param attrib The attribute to retrieve the value of.
 214:    *
 215:    * @return The value of the specified attribute
 216:    */
 217:   Object getAttribute(AttributedCharacterIterator.Attribute attrib);
 218: 
 219:   /**
 220:    * Returns the index of the first character in the run that
 221:    * contains all attributes defined for the current character.
 222:    *
 223:    * @return The start index of the run
 224:    */
 225:   int getRunStart();
 226: 
 227:   /**
 228:    * Returns the index of the first character in the run that
 229:    * contains all attributes in the specified <code>Set</code> defined for
 230:    * the current character.
 231:    *
 232:    * @param attribs The <code>Set</code> of attributes.
 233:    *
 234:    * @return The start index of the run.
 235:    */
 236:   int getRunStart(Set<? extends Attribute> attribs);
 237:   
 238:   /**
 239:    * Returns the index of the first character in the run that
 240:    * contains the specified attribute defined for the current character.
 241:    *
 242:    * @param attrib The attribute.
 243:    *
 244:    * @return The start index of the run.
 245:    */
 246:   int getRunStart(AttributedCharacterIterator.Attribute attrib);
 247:   
 248:   /**
 249:    * Returns the index of the character after the end of the run
 250:    * that contains all attributes defined for the current character.
 251:    *
 252:    * @return The end index of the run.
 253:    */
 254:   int getRunLimit();
 255:   
 256:   /**
 257:    * Returns the index of the character after the end of the run
 258:    * that contains all attributes in the specified <code>Set</code> defined
 259:    * for the current character.
 260:    *
 261:    * @param attribs The <code>Set</code> of attributes.
 262:    *
 263:    * @return The end index of the run.
 264:    */
 265:   int getRunLimit(Set<? extends Attribute> attribs);
 266:   
 267:   /**
 268:    * Returns the index of the character after the end of the run
 269:    * that contains the specified attribute defined for the current character.
 270:    *
 271:    * @param attrib The attribute.
 272:    * 
 273:    * @return The end index of the run.
 274:    */
 275:   int getRunLimit(AttributedCharacterIterator.Attribute attrib);
 276: 
 277: } // interface AttributedCharacterIterator