1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.text;
19
20import java.io.InvalidObjectException;
21import java.io.Serializable;
22import java.util.Map;
23import java.util.Set;
24
25import org.apache.harmony.text.internal.nls.Messages;
26
27/**
28 * Extends the
29 * {@link CharacterIterator} interface, adding support for iterating over
30 * attributes and not only characters. An
31 * {@code AttributedCharacterIterator} also allows the user to find runs and
32 * their limits. Runs are defined as ranges of characters that all have the same
33 * attributes with the same values.
34 */
35public interface AttributedCharacterIterator extends CharacterIterator {
36
37    /**
38     * Defines keys for text attributes.
39     */
40    public static class Attribute implements Serializable {
41
42        private static final long serialVersionUID = -9142742483513960612L;
43
44        /**
45         * This attribute marks segments from an input method. Most input
46         * methods create these segments for words.
47         *
48         * The value objects are of the type {@code Annotation} which contain
49         * {@code null}.
50         */
51        public static final Attribute INPUT_METHOD_SEGMENT = new Attribute(
52                "input_method_segment"); //$NON-NLS-1$
53
54        /**
55         * The attribute describing the language of a character. The value
56         * objects are of type {@code Locale} or a subtype of it.
57         */
58        public static final Attribute LANGUAGE = new Attribute("language"); //$NON-NLS-1$
59
60        /**
61         * For languages that have different reading directions of text (like
62         * Japanese), this attribute allows to define which reading should be
63         * used. The value objects are of type {@code Annotation} which
64         * contain a {@code String}.
65         */
66        public static final Attribute READING = new Attribute("reading"); //$NON-NLS-1$
67
68        private String name;
69
70        /**
71         * The constructor for an {@code Attribute} with the name passed.
72         *
73         * @param name
74         *            the name of the new {@code Attribute}.
75         */
76        protected Attribute(String name) {
77            this.name = name;
78        }
79
80        /**
81         * Compares this attribute with the specified object. Checks if both
82         * objects are the same instance. It is defined final so all subclasses
83         * have the same behavior for this method.
84         *
85         * @param object
86         *            the object to compare against.
87         * @return {@code true} if the object passed is equal to this instance;
88         *         {@code false} otherwise.
89         */
90        @Override
91        public final boolean equals(Object object) {
92            return this == object;
93        }
94
95        /**
96         * Returns the name of this attribute.
97         *
98         * @return the name of this attribute.
99         */
100        protected String getName() {
101            return name;
102        }
103
104        /**
105         * Calculates the hash code for objects of type {@code Attribute}. It
106         * is defined final so all sub types calculate their hash code
107         * identically.
108         *
109         * @return the hash code for this instance of {@code Attribute}.
110         */
111        @Override
112        public final int hashCode() {
113            return super.hashCode();
114        }
115
116        /**
117         * Resolves a deserialized instance to the correct constant attribute.
118         *
119         * @return the {@code Attribute} this instance represents.
120         * @throws InvalidObjectException
121         *             if this instance is not of type {@code Attribute.class}
122         *             or if it is not a known {@code Attribute}.
123         */
124        protected Object readResolve() throws InvalidObjectException {
125            if (this.getClass() != Attribute.class) {
126                // text.0C=cannot resolve subclasses
127                throw new InvalidObjectException(Messages.getString("text.0C")); //$NON-NLS-1$
128            }
129            // BEGIN android-changed
130            // call getName() only once
131            String name = this.getName();
132            if (name.equals(INPUT_METHOD_SEGMENT.getName())) {
133                return INPUT_METHOD_SEGMENT;
134            }
135            if (name.equals(LANGUAGE.getName())) {
136                return LANGUAGE;
137            }
138            if (name.equals(READING.getName())) {
139                return READING;
140            }
141            // END android-changed
142            // text.02=Unknown attribute
143            throw new InvalidObjectException(Messages.getString("text.02")); //$NON-NLS-1$
144        }
145
146        /**
147         * Returns the name of the class followed by a "(", the name of the
148         * attribute, and a ")".
149         *
150         * @return the string representing this instance.
151         */
152        @Override
153        public String toString() {
154            return getClass().getName() + '(' + getName() + ')';
155        }
156    }
157
158    /**
159     * Returns a set of attributes present in the {@code
160     * AttributedCharacterIterator}. An empty set is returned if no attributes
161     * were defined.
162     *
163     * @return a set of attribute keys; may be empty.
164     */
165    public Set<Attribute> getAllAttributeKeys();
166
167    /**
168     * Returns the value stored in the attribute for the current character. If
169     * the attribute was not defined then {@code null} is returned.
170     *
171     * @param attribute the attribute for which the value should be returned.
172     * @return the value of the requested attribute for the current character or
173     *         {@code null} if it was not defined.
174     */
175    public Object getAttribute(Attribute attribute);
176
177    /**
178     * Returns a map of all attributes of the current character. If no
179     * attributes were defined for the current character then an empty map is
180     * returned.
181     *
182     * @return a map of all attributes for the current character or an empty
183     *         map.
184     */
185    public Map<Attribute, Object> getAttributes();
186
187    /**
188     * Returns the index of the last character in the run having the same
189     * attributes as the current character.
190     *
191     * @return the index of the last character of the current run.
192     */
193    public int getRunLimit();
194
195    /**
196     * Returns the index of the last character in the run that has the same
197     * attribute value for the given attribute as the current character.
198     *
199     * @param attribute
200     *            the attribute which the run is based on.
201     * @return the index of the last character of the current run.
202     */
203    public int getRunLimit(Attribute attribute);
204
205    /**
206     * Returns the index of the last character in the run that has the same
207     * attribute values for the attributes in the set as the current character.
208     *
209     * @param attributes
210     *            the set of attributes which the run is based on.
211     * @return the index of the last character of the current run.
212     */
213    public int getRunLimit(Set<? extends Attribute> attributes);
214
215    /**
216     * Returns the index of the first character in the run that has the same
217     * attributes as the current character.
218     *
219     * @return the index of the last character of the current run.
220     */
221    public int getRunStart();
222
223    /**
224     * Returns the index of the first character in the run that has the same
225     * attribute value for the given attribute as the current character.
226     *
227     * @param attribute
228     *            the attribute which the run is based on.
229     * @return the index of the last character of the current run.
230     */
231    public int getRunStart(Attribute attribute);
232
233    /**
234     * Returns the index of the first character in the run that has the same
235     * attribute values for the attributes in the set as the current character.
236     *
237     * @param attributes
238     *            the set of attributes which the run is based on.
239     * @return the index of the last character of the current run.
240     */
241    public int getRunStart(Set<? extends Attribute> attributes);
242}
243