/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package java.text;

import java.io.InvalidObjectException;
import java.io.Serializable;
import java.util.Map;
import java.util.Set;

import org.apache.harmony.text.internal.nls.Messages;

/**
 * Extends the
 * {@link CharacterIterator} interface, adding support for iterating over
 * attributes and not only characters. An
 * {@code AttributedCharacterIterator} also allows the user to find runs and
 * their limits. Runs are defined as ranges of characters that all have the same
 * attributes with the same values.
 * 
 * @since Android 1.0
 */
public interface AttributedCharacterIterator extends CharacterIterator {

    /**
     * Defines keys for text attributes.
     * 
     * @since Android 1.0
     */
    public static class Attribute implements Serializable {

        private static final long serialVersionUID = -9142742483513960612L;

        /**
         * This attribute marks segments from an input method. Most input
         * methods create these segments for words.
         * 
         * The value objects are of the type {@code Annotation} which contain
         * {@code null}.
         * 
         * @since Android 1.0
         */
        public static final Attribute INPUT_METHOD_SEGMENT = new Attribute(
                "input_method_segment"); //$NON-NLS-1$

        /**
         * The attribute describing the language of a character. The value
         * objects are of type {@code Locale} or a subtype of it.
         * 
         * @since Android 1.0
         */
        public static final Attribute LANGUAGE = new Attribute("language"); //$NON-NLS-1$

        /**
         * For languages that have different reading directions of text (like
         * Japanese), this attribute allows to define which reading should be
         * used. The value objects are of type {@code Annotation} which
         * contain a {@code String}.
         * 
         * @since Android 1.0
         */
        public static final Attribute READING = new Attribute("reading"); //$NON-NLS-1$

        private String name;

        /**
         * The constructor for an {@code Attribute} with the name passed.
         * 
         * @param name
         *            the name of the new {@code Attribute}.
         * @since Android 1.0
         */
        protected Attribute(String name) {
            this.name = name;
        }

        /**
         * Compares this attribute with the specified object. Checks if both
         * objects are the same instance. It is defined final so all subclasses
         * have the same behavior for this method.
         * 
         * @param object
         *            the object to compare against.
         * @return {@code true} if the object passed is equal to this instance;
         *         {@code false} otherwise.
         * @since Android 1.0
         */
        @Override
        public final boolean equals(Object object) {
            return super.equals(object);
        }

        /**
         * Returns the name of this attribute.
         * 
         * @return the name of this attribute.
         * @since Android 1.0
         */
        protected String getName() {
            return name;
        }

        /**
         * Calculates the hash code for objects of type {@code Attribute}. It
         * is defined final so all sub types calculate their hash code
         * identically.
         * 
         * @return the hash code for this instance of {@code Attribute}.
         * @since Android 1.0
         */
        @Override
        public final int hashCode() {
            return super.hashCode();
        }

        /**
         * Resolves a deserialized instance to the correct constant attribute.
         * 
         * @return the {@code Attribute} this instance represents.
         * @throws InvalidObjectException
         *             if this instance is not of type {@code Attribute.class}
         *             or if it is not a known {@code Attribute}.
         * @since Android 1.0
         */
        protected Object readResolve() throws InvalidObjectException {
            if (this.getClass() != Attribute.class) {
                // text.0C=cannot resolve subclasses
                throw new InvalidObjectException(Messages.getString("text.0C")); //$NON-NLS-1$
            }
            if (this.name.equals(INPUT_METHOD_SEGMENT.name)) {
                return INPUT_METHOD_SEGMENT;
            }
            if (this.name.equals(LANGUAGE.name)) {
                return LANGUAGE;
            }
            if (this.name.equals(READING.name)) {
                return READING;
            }
            // text.02=Unknown attribute
            throw new InvalidObjectException(Messages.getString("text.02")); //$NON-NLS-1$
        }

        /**
         * Returns the name of the class followed by a "(", the name of the
         * attribute, and a ")".
         * 
         * @return the string representing this instance.
         * @since Android 1.0
         */
        @Override
        public String toString() {
            return getClass().getName() + '(' + getName() + ')';
        }
    }

    /**
     * Returns a set of attributes present in the {@code
     * AttributedCharacterIterator}. An empty set is returned if no attributes
     * were defined.
     * 
     * @return a set of attribute keys; may be empty.
     * @since Android 1.0
     */
    public Set<Attribute> getAllAttributeKeys();

    /**
     * Returns the value stored in the attribute for the current character. If
     * the attribute was not defined then {@code null} is returned.
     * 
     * @param attribute the attribute for which the value should be returned.
     * @return the value of the requested attribute for the current character or
     *         {@code null} if it was not defined.
     * @since Android 1.0
     */
    public Object getAttribute(Attribute attribute);

    /**
     * Returns a map of all attributes of the current character. If no
     * attributes were defined for the current character then an empty map is
     * returned.
     * 
     * @return a map of all attributes for the current character or an empty
     *         map.
     * @since Android 1.0
     */
    public Map<Attribute, Object> getAttributes();

    /**
     * Returns the index of the last character in the run having the same
     * attributes as the current character.
     * 
     * @return the index of the last character of the current run.
     * @since Android 1.0
     */
    public int getRunLimit();

    /**
     * Returns the index of the last character in the run that has the same
     * attribute value for the given attribute as the current character.
     * 
     * @param attribute
     *            the attribute which the run is based on.
     * @return the index of the last character of the current run.
     * @since Android 1.0
     */
    public int getRunLimit(Attribute attribute);

    /**
     * Returns the index of the last character in the run that has the same
     * attribute values for the attributes in the set as the current character.
     * 
     * @param attributes
     *            the set of attributes which the run is based on.
     * @return the index of the last character of the current run.
     * @since Android 1.0
     */
    public int getRunLimit(Set<? extends Attribute> attributes);

    /**
     * Returns the index of the first character in the run that has the same
     * attributes as the current character.
     * 
     * @return the index of the last character of the current run.
     * @since Android 1.0
     */
    public int getRunStart();

    /**
     * Returns the index of the first character in the run that has the same
     * attribute value for the given attribute as the current character.
     * 
     * @param attribute
     *            the attribute which the run is based on.
     * @return the index of the last character of the current run.
     * @since Android 1.0
     */
    public int getRunStart(Attribute attribute);

    /**
     * Returns the index of the first character in the run that has the same
     * attribute values for the attributes in the set as the current character.
     * 
     * @param attributes
     *            the set of attributes which the run is based on.
     * @return the index of the last character of the current run.
     * @since Android 1.0
     */
    public int getRunStart(Set<? extends Attribute> attributes);
}