1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/text/AttributedCharacterIterator.java Thu Oct 03 15:40:35 2013 +0200
1.3 @@ -0,0 +1,254 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.text;
1.30 +
1.31 +import java.io.InvalidObjectException;
1.32 +import java.io.Serializable;
1.33 +import java.util.HashMap;
1.34 +import java.util.Map;
1.35 +import java.util.Set;
1.36 +
1.37 +/**
1.38 + * An {@code AttributedCharacterIterator} allows iteration through both text and
1.39 + * related attribute information.
1.40 + *
1.41 + * <p>
1.42 + * An attribute is a key/value pair, identified by the key. No two
1.43 + * attributes on a given character can have the same key.
1.44 + *
1.45 + * <p>The values for an attribute are immutable, or must not be mutated
1.46 + * by clients or storage. They are always passed by reference, and not
1.47 + * cloned.
1.48 + *
1.49 + * <p>A <em>run with respect to an attribute</em> is a maximum text range for
1.50 + * which:
1.51 + * <ul>
1.52 + * <li>the attribute is undefined or {@code null} for the entire range, or
1.53 + * <li>the attribute value is defined and has the same non-{@code null} value for the
1.54 + * entire range.
1.55 + * </ul>
1.56 + *
1.57 + * <p>A <em>run with respect to a set of attributes</em> is a maximum text range for
1.58 + * which this condition is met for each member attribute.
1.59 + *
1.60 + * <p>When getting a run with no explicit attributes specified (i.e.,
1.61 + * calling {@link #getRunStart()} and {@link #getRunLimit()}), any
1.62 + * contiguous text segments having the same attributes (the same set
1.63 + * of attribute/value pairs) are treated as separate runs if the
1.64 + * attributes have been given to those text segments separately.
1.65 + *
1.66 + * <p>The returned indexes are limited to the range of the iterator.
1.67 + *
1.68 + * <p>The returned attribute information is limited to runs that contain
1.69 + * the current character.
1.70 + *
1.71 + * <p>
1.72 + * Attribute keys are instances of {@link AttributedCharacterIterator.Attribute} and its
1.73 + * subclasses, such as {@link java.awt.font.TextAttribute}.
1.74 + *
1.75 + * @see AttributedCharacterIterator.Attribute
1.76 + * @see java.awt.font.TextAttribute
1.77 + * @see AttributedString
1.78 + * @see Annotation
1.79 + * @since 1.2
1.80 + */
1.81 +
1.82 +public interface AttributedCharacterIterator extends CharacterIterator {
1.83 +
1.84 + /**
1.85 + * Defines attribute keys that are used to identify text attributes. These
1.86 + * keys are used in {@code AttributedCharacterIterator} and {@code AttributedString}.
1.87 + * @see AttributedCharacterIterator
1.88 + * @see AttributedString
1.89 + * @since 1.2
1.90 + */
1.91 +
1.92 + public static class Attribute implements Serializable {
1.93 +
1.94 + /**
1.95 + * The name of this {@code Attribute}. The name is used primarily by {@code readResolve}
1.96 + * to look up the corresponding predefined instance when deserializing
1.97 + * an instance.
1.98 + * @serial
1.99 + */
1.100 + private String name;
1.101 +
1.102 + // table of all instances in this class, used by readResolve
1.103 + private static final Map instanceMap = new HashMap(7);
1.104 +
1.105 + /**
1.106 + * Constructs an {@code Attribute} with the given name.
1.107 + */
1.108 + protected Attribute(String name) {
1.109 + this.name = name;
1.110 + if (this.getClass() == Attribute.class) {
1.111 + instanceMap.put(name, this);
1.112 + }
1.113 + }
1.114 +
1.115 + /**
1.116 + * Compares two objects for equality. This version only returns true
1.117 + * for <code>x.equals(y)</code> if <code>x</code> and <code>y</code> refer
1.118 + * to the same object, and guarantees this for all subclasses.
1.119 + */
1.120 + public final boolean equals(Object obj) {
1.121 + return super.equals(obj);
1.122 + }
1.123 +
1.124 + /**
1.125 + * Returns a hash code value for the object. This version is identical to
1.126 + * the one in {@code Object}, but is also final.
1.127 + */
1.128 + public final int hashCode() {
1.129 + return super.hashCode();
1.130 + }
1.131 +
1.132 + /**
1.133 + * Returns a string representation of the object. This version returns the
1.134 + * concatenation of class name, {@code "("}, a name identifying the attribute
1.135 + * and {@code ")"}.
1.136 + */
1.137 + public String toString() {
1.138 + return getClass().getName() + "(" + name + ")";
1.139 + }
1.140 +
1.141 + /**
1.142 + * Returns the name of the attribute.
1.143 + */
1.144 + protected String getName() {
1.145 + return name;
1.146 + }
1.147 +
1.148 + /**
1.149 + * Resolves instances being deserialized to the predefined constants.
1.150 + */
1.151 + protected Object readResolve() throws InvalidObjectException {
1.152 + if (this.getClass() != Attribute.class) {
1.153 + throw new InvalidObjectException("subclass didn't correctly implement readResolve");
1.154 + }
1.155 +
1.156 + Attribute instance = (Attribute) instanceMap.get(getName());
1.157 + if (instance != null) {
1.158 + return instance;
1.159 + } else {
1.160 + throw new InvalidObjectException("unknown attribute name");
1.161 + }
1.162 + }
1.163 +
1.164 + /**
1.165 + * Attribute key for the language of some text.
1.166 + * <p> Values are instances of {@link java.util.Locale Locale}.
1.167 + * @see java.util.Locale
1.168 + */
1.169 + public static final Attribute LANGUAGE = new Attribute("language");
1.170 +
1.171 + /**
1.172 + * Attribute key for the reading of some text. In languages where the written form
1.173 + * and the pronunciation of a word are only loosely related (such as Japanese),
1.174 + * it is often necessary to store the reading (pronunciation) along with the
1.175 + * written form.
1.176 + * <p>Values are instances of {@link Annotation} holding instances of {@link String}.
1.177 + * @see Annotation
1.178 + * @see java.lang.String
1.179 + */
1.180 + public static final Attribute READING = new Attribute("reading");
1.181 +
1.182 + /**
1.183 + * Attribute key for input method segments. Input methods often break
1.184 + * up text into segments, which usually correspond to words.
1.185 + * <p>Values are instances of {@link Annotation} holding a {@code null} reference.
1.186 + * @see Annotation
1.187 + */
1.188 + public static final Attribute INPUT_METHOD_SEGMENT = new Attribute("input_method_segment");
1.189 +
1.190 + // make sure the serial version doesn't change between compiler versions
1.191 + private static final long serialVersionUID = -9142742483513960612L;
1.192 +
1.193 + };
1.194 +
1.195 + /**
1.196 + * Returns the index of the first character of the run
1.197 + * with respect to all attributes containing the current character.
1.198 + *
1.199 + * <p>Any contiguous text segments having the same attributes (the
1.200 + * same set of attribute/value pairs) are treated as separate runs
1.201 + * if the attributes have been given to those text segments separately.
1.202 + */
1.203 + public int getRunStart();
1.204 +
1.205 + /**
1.206 + * Returns the index of the first character of the run
1.207 + * with respect to the given {@code attribute} containing the current character.
1.208 + */
1.209 + public int getRunStart(Attribute attribute);
1.210 +
1.211 + /**
1.212 + * Returns the index of the first character of the run
1.213 + * with respect to the given {@code attributes} containing the current character.
1.214 + */
1.215 + public int getRunStart(Set<? extends Attribute> attributes);
1.216 +
1.217 + /**
1.218 + * Returns the index of the first character following the run
1.219 + * with respect to all attributes containing the current character.
1.220 + *
1.221 + * <p>Any contiguous text segments having the same attributes (the
1.222 + * same set of attribute/value pairs) are treated as separate runs
1.223 + * if the attributes have been given to those text segments separately.
1.224 + */
1.225 + public int getRunLimit();
1.226 +
1.227 + /**
1.228 + * Returns the index of the first character following the run
1.229 + * with respect to the given {@code attribute} containing the current character.
1.230 + */
1.231 + public int getRunLimit(Attribute attribute);
1.232 +
1.233 + /**
1.234 + * Returns the index of the first character following the run
1.235 + * with respect to the given {@code attributes} containing the current character.
1.236 + */
1.237 + public int getRunLimit(Set<? extends Attribute> attributes);
1.238 +
1.239 + /**
1.240 + * Returns a map with the attributes defined on the current
1.241 + * character.
1.242 + */
1.243 + public Map<Attribute,Object> getAttributes();
1.244 +
1.245 + /**
1.246 + * Returns the value of the named {@code attribute} for the current character.
1.247 + * Returns {@code null} if the {@code attribute} is not defined.
1.248 + */
1.249 + public Object getAttribute(Attribute attribute);
1.250 +
1.251 + /**
1.252 + * Returns the keys of all attributes defined on the
1.253 + * iterator's text range. The set is empty if no
1.254 + * attributes are defined.
1.255 + */
1.256 + public Set<Attribute> getAllAttributeKeys();
1.257 +};