/*
 * 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 org.apache.sis.feature;

import java.util.Map;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.io.Serializable;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.InvalidObjectException;
import java.io.IOException;
import org.opengis.util.GenericName;
import org.opengis.metadata.quality.DataQuality;
import org.opengis.metadata.maintenance.ScopeCode;
import org.apache.sis.util.Classes;
import org.apache.sis.util.ArgumentChecks;


/**
 * An instance of an {@linkplain DefaultAttributeType attribute type} containing the value of an attribute in a feature.
 * {@code Attribute} holds three main information:
 *
 * <ul>
 *   <li>A {@linkplain #getType() reference to an attribute type}
 *       which defines the base Java type and domain of valid values.</li>
 *   <li>One or more {@linkplain #getValues() values}, which may be a singleton ([0 … 1] multiplicity)
 *       or multi-valued ([0 … ∞] multiplicity).</li>
 *   <li>Optional {@linkplain #characteristics() characteristics} about the attribute
 *       (e.g. a <var>temperature</var> attribute may have a characteristic holding the measurement <var>accuracy</var>).
 *       Characteristics are often, but not necessarily, constant for all attributes of the same type in a dataset.</li>
 * </ul>
 *
 * {@code AbstractAttribute} can be instantiated by calls to {@link DefaultAttributeType#newInstance()}.
 *
 * <div class="section">Limitations</div>
 * <ul>
 *   <li><b>Multi-threading:</b> {@code AbstractAttribute} instances are <strong>not</strong> thread-safe.
 *       Synchronization, if needed, shall be done externally by the caller.</li>
 *   <li><b>Serialization:</b> serialized objects of this class are not guaranteed to be compatible with future
 *       versions. Serialization should be used only for short term storage or RMI between applications running
 *       the same SIS version.</li>
 *   <li><b>Cloning:</b> despite providing a public {@link #clone()} method, this base class is <strong>not</strong>
 *       cloneable by default. Subclasses shall implement the {@link Cloneable} interface themselves if they choose
 *       to support cloning.</li>
 * </ul>
 *
 * @author  Johann Sorel (Geomatys)
 * @author  Martin Desruisseaux (Geomatys)
 * @version 0.8
 *
 * @param <V>  the type of attribute values.
 *
 * @see AbstractFeature
 * @see DefaultAttributeType
 *
 * @since 0.5
 * @module
 */
@SuppressWarnings("CloneInNonCloneableClass")       // Decision left to subclasses - see javadoc
public abstract class AbstractAttribute<V> extends Field<V> implements Serializable {
    /**
     * For cross-version compatibility.
     */
    private static final long serialVersionUID = 7442739120526654676L;

    /**
     * Information about the attribute (base Java class, domain of values, <i>etc.</i>).
     */
    final DefaultAttributeType<V> type;

    /**
     * Other attributes that describes this attribute, or {@code null} if not yet created.
     *
     * <div class="note"><b>Design note:</b>
     * We could question if it is a good idea to put this field here, given that this field add a slight cost
     * to all attribute implementations while only a small fraction of them will want attribute characteristics.
     * Since attributes may exist in a very large amount, that question may be significant.
     * However {@link AbstractFeature} tries hard to not create {@code Attribute} instances at all (it tries to
     * store only their value instead), so we presume that peoples who ask for {@code Attribute} instances are
     * willing to accept their cost.</div>
     *
     * @see #characteristics()
     */
    private transient Map<String,AbstractAttribute<?>> characteristics;

    /**
     * Creates a new attribute of the given type.
     *
     * @param type  information about the attribute (base Java class, domain of values, <i>etc.</i>).
     *
     * @see #create(DefaultAttributeType)
     */
    protected AbstractAttribute(final DefaultAttributeType<V> type) {
        this.type = type;
    }

    /**
     * Creates a new attribute of the given type initialized to the
     * {@linkplain DefaultAttributeType#getDefaultValue() default value}.
     *
     * @param  <V>   the type of attribute values.
     * @param  type  information about the attribute (base Java class, domain of values, <i>etc.</i>).
     * @return the new attribute.
     *
     * @see DefaultAttributeType#newInstance()
     */
    public static <V> AbstractAttribute<V> create(final DefaultAttributeType<V> type) {
        ArgumentChecks.ensureNonNull("type", type);
        return isSingleton(type.getMaximumOccurs())
               ? new SingletonAttribute<>(type)
               : new MultiValuedAttribute<>(type);
    }

    /**
     * Creates a new attribute of the given type initialized to the given value.
     * Note that a {@code null} value may not be the same as the default value.
     *
     * @param  <V>    the type of attribute values.
     * @param  type   information about the attribute (base Java class, domain of values, <i>etc.</i>).
     * @param  value  the initial value (may be {@code null}).
     * @return the new attribute.
     */
    static <V> AbstractAttribute<V> create(final DefaultAttributeType<V> type, final Object value) {
        ArgumentChecks.ensureNonNull("type", type);
        return isSingleton(type.getMaximumOccurs())
               ? new SingletonAttribute<>(type, value)
               : new MultiValuedAttribute<>(type, value);
    }

    /**
     * Invoked on serialization for saving the {@link #characteristics} field.
     *
     * @param  out  the output stream where to serialize this attribute.
     * @throws IOException if an I/O error occurred while writing.
     */
    private void writeObject(final ObjectOutputStream out) throws IOException {
        out.defaultWriteObject();
        final AbstractAttribute<?>[] characterizedBy;
        if (characteristics instanceof CharacteristicMap) {
            characterizedBy = characteristics.values().toArray(new AbstractAttribute<?>[characteristics.size()]);
        } else {
            characterizedBy = null;
        }
        out.writeObject(characterizedBy);
    }

    /**
     * Invoked on deserialization for restoring the {@link #characteristics} field.
     *
     * @param  in  the input stream from which to deserialize an attribute.
     * @throws IOException if an I/O error occurred while reading or if the stream contains invalid data.
     * @throws ClassNotFoundException if the class serialized on the stream is not on the classpath.
     */
    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
        in.defaultReadObject();
        try {
            final AbstractAttribute<?>[] characterizedBy = (AbstractAttribute<?>[]) in.readObject();
            if (characterizedBy != null) {
                characteristics = newCharacteristicsMap();
                characteristics.values().addAll(Arrays.asList(characterizedBy));
            }
        } catch (RuntimeException e) {
            // At least ClassCastException, NullPointerException, IllegalArgumentException and IllegalStateException.
            throw (IOException) new InvalidObjectException(e.getLocalizedMessage()).initCause(e);
        }
    }

    /**
     * Returns the name of this attribute as defined by its {@linkplain #getType() type}.
     * This convenience method delegates to {@link DefaultAttributeType#getName()}.
     *
     * @return the attribute name specified by its type.
     */
    @Override
    public GenericName getName() {
        return type.getName();
    }

    /**
     * Returns information about the attribute (base Java class, domain of values, <i>etc.</i>).
     *
     * <div class="warning"><b>Warning:</b> In a future SIS version, the return type may be changed
     * to {@code org.opengis.feature.AttributeType}. This change is pending GeoAPI revision.</div>
     *
     * @return information about the attribute.
     */
    public DefaultAttributeType<V> getType() {
        return type;
    }

    /**
     * Returns the attribute value, or {@code null} if none. This convenience method can be invoked in
     * the common case where the {@linkplain DefaultAttributeType#getMaximumOccurs() maximum number}
     * of attribute values is restricted to 1 or 0.
     *
     * @return the attribute value (may be {@code null}).
     * @throws IllegalStateException if this attribute contains more than one value.
     *
     * @see AbstractFeature#getPropertyValue(String)
     */
    @Override
    public abstract V getValue() throws IllegalStateException;

    /**
     * Returns all attribute values, or an empty collection if none.
     * The returned collection is <cite>live</cite>: changes in the returned collection
     * will be reflected immediately in this {@code Attribute} instance, and conversely.
     *
     * <p>The default implementation returns a collection which will delegate its work to
     * {@link #getValue()} and {@link #setValue(Object)}.</p>
     *
     * @return the attribute values in a <cite>live</cite> collection.
     */
    @Override
    public Collection<V> getValues() {
        return super.getValues();
    }

    /**
     * Sets the attribute value. All previous values are replaced by the given singleton.
     *
     * <div class="section">Validation</div>
     * The amount of validation performed by this method is implementation dependent.
     * Usually, only the most basic constraints are verified. This is so for performance reasons
     * and also because some rules may be temporarily broken while constructing a feature.
     * A more exhaustive verification can be performed by invoking the {@link #quality()} method.
     *
     * @param  value  the new value, or {@code null} for removing all values from this attribute.
     * @throws IllegalArgumentException if this method verifies argument validity and the given value
     *         does not met the attribute constraints.
     *
     * @see AbstractFeature#setPropertyValue(String, Object)
     */
    @Override
    public abstract void setValue(final V value) throws IllegalArgumentException;

    /**
     * Sets the attribute values. All previous values are replaced by the given collection.
     *
     * <p>The default implementation ensures that the given collection contains at most one element,
     * then delegates to {@link #setValue(Object)}.</p>
     *
     * @param  values  the new values.
     * @throws IllegalArgumentException if the given collection contains too many elements.
     */
    @Override
    public void setValues(final Collection<? extends V> values) throws IllegalArgumentException {
        super.setValues(values);
    }

    /**
     * Other attributes that describes this attribute. For example if this attribute carries a measurement,
     * then a characteristic of this attribute could be the measurement accuracy.
     * See <cite>"Attribute characterization"</cite> in {@link DefaultAttributeType} Javadoc for more information.
     *
     * <p>The map returned by this method contains only the characteristics explicitly defined for this attribute.
     * If the map contains no characteristic for a given name, a {@linkplain DefaultAttributeType#getDefaultValue()
     * default value} may still exist.
     * In such cases, callers may also need to inspect the {@link DefaultAttributeType#characteristics()}
     * as shown in the <cite>Reading a characteristic</cite> section below.</p>
     *
     * <div class="note"><b>Rational:</b>
     * Very often, all attributes of a given type in the same dataset have the same characteristics.
     * For example it is very common that all temperature measurements in a dataset have the same accuracy,
     * and setting a different accuracy for a single measurement is relatively rare.
     * Consequently, {@code characteristics.isEmpty()} is a convenient way to check that an attribute have
     * all the "standard" characteristics and need no special processing.</div>
     *
     * <div class="section">Reading a characteristic</div>
     * The characteristic values are enumerated in the {@linkplain Map#values() map values}.
     * The {@linkplain Map#keySet() map keys} are the {@code String} representations of characteristics
     * {@linkplain DefaultAttributeType#getName() name}, for more convenient lookups.
     *
     * <p>If an attribute is known to be a measurement with a characteristic named "accuracy"
     * of type {@link Float}, then the accuracy value could be read as below:</p>
     *
     * {@preformat java
     *     Float getAccuracy(Attribute<?> measurement) {
     *         Attribute<?> accuracy = measurement.characteristics().get("accuracy");
     *         if (accuracy != null) {
     *             return (Float) accuracy.getValue(); // Value may be null.
     *         } else {
     *             return (Float) measurement.getType().characteristics().get("accuracy").getDefaultValue();
     *             // A more sophisticated implementation would probably cache the default value somewhere.
     *         }
     *     }
     * }
     *
     * <div class="section">Adding a characteristic</div>
     * A new characteristic can be added in the map in three different ways:
     * <ol>
     *   <li>Putting the (<var>name</var>, <var>characteristic</var>) pair explicitly.
     *     If an older characteristic existed for that name, it will be replaced.
     *     Example:
     *
     *     {@preformat java
     *       Attribute<?> accuracy = ...;                               // To be created by the caller.
     *       characteristics.put("accuracy", accuracy);
     *     }</li>
     *
     *   <li>Adding the new characteristic to the {@linkplain Map#values() values} collection.
     *     The name is inferred automatically from the characteristic type.
     *     If an older characteristic existed for the same name, an {@link IllegalStateException} will be thrown.
     *     Example:
     *
     *     {@preformat java
     *       Attribute<?> accuracy = ...;                               // To be created by the caller.
     *       characteristics.values().add(accuracy);
     *     }</li>
     *
     *   <li>Adding the characteristic name to the {@linkplain Map#keySet() key set}.
     *     If no characteristic existed for that name, a default one will be created.
     *     Example:
     *
     *     {@preformat java
     *       characteristics.keySet().add("accuracy");                  // Ensure that an entry will exist for that name.
     *       Attribute<?> accuracy = characteristics.get("accuracy");
     *       Features.cast(accuracy, Float.class).setValue(...);        // Set new accuracy value here as a float.
     *     }</li>
     * </ol>
     *
     * @return other attribute types that describes this attribute type, or an empty map if none.
     *
     * @see DefaultAttributeType#characteristics()
     */
    @SuppressWarnings("ReturnOfCollectionOrArrayField")
    public Map<String,AbstractAttribute<?>> characteristics() {
        if (characteristics == null) {
            characteristics = newCharacteristicsMap();
        }
        return characteristics;                                 // Intentionally modifiable
    }

    /**
     * Creates an initially empty map of characteristics for this attribute.
     * This method does not store the new map in the {@link #characteristics} field;
     * it is caller responsibility to do so if desired.
     */
    private Map<String,AbstractAttribute<?>> newCharacteristicsMap() {
        if (type instanceof DefaultAttributeType<?>) {
            Map<String, DefaultAttributeType<?>> map = type.characteristics();
            if (!map.isEmpty()) {
                if (!(map instanceof CharacteristicTypeMap)) {
                    final Collection<DefaultAttributeType<?>> types = map.values();
                    map = CharacteristicTypeMap.create(type, types.toArray(new DefaultAttributeType<?>[types.size()]));
                }
                return new CharacteristicMap(this, (CharacteristicTypeMap) map);
            }
        }
        return Collections.emptyMap();
    }

    /**
     * Returns the characteristics, or an empty map if the characteristics have not yet been built.
     * Contrarily to {@link #characteristics()}, this method does not create the map. This method
     * is suitable when then caller only wants to read the map and does not plan to write anything.
     */
    final Map<String,AbstractAttribute<?>> characteristicsReadOnly() {
        return (characteristics != null) ? characteristics : Collections.emptyMap();
    }

    /**
     * Evaluates the quality of this attribute at this method invocation time. The data quality reports
     * may include information about whether the attribute value mets the constraints defined by the
     * {@linkplain DefaultAttributeType attribute type}, or any other criterion at implementation choice.
     *
     * <p>The default implementation reports data quality with at least the following information:</p>
     * <ul>
     *   <li>
     *     The {@linkplain org.apache.sis.metadata.iso.quality.DefaultDataQuality#getScope() scope}
     *     {@linkplain org.apache.sis.metadata.iso.quality.DefaultScope#getLevel() level} is set to
     *     {@link org.opengis.metadata.maintenance.ScopeCode#ATTRIBUTE}.
     *   </li><li>
     *     At most one {@linkplain org.apache.sis.metadata.iso.quality.DefaultDomainConsistency domain consistency}
     *     element is added to the {@linkplain org.apache.sis.metadata.iso.quality.DefaultDataQuality#getReports()
     *     reports} list (implementations are free to omit that element if they have nothing to report).
     *     If a report is provided, then it will contain at least the following information:
     *     <ul>
     *       <li>
     *         <p>The {@linkplain #getName() attribute name} as the data quality
     *         {@linkplain org.apache.sis.metadata.iso.quality.DefaultDomainConsistency#getMeasureIdentification()
     *         measure identification}.</p>
     *
     *         <div class="note"><b>Note:</b> strictly speaking, {@code measureIdentification} identifies the
     *         <em>quality measurement</em>, not the “real” measurement itself. However this implementation
     *         uses the same set of identifiers for both for simplicity.</div>
     *       </li><li>
     *         <p>If the attribute {@linkplain #getValue() value} is not an {@linkplain Class#isInstance instance}
     *         of the expected {@linkplain DefaultAttributeType#getValueClass() value class}, or if the number
     *         of occurrences is not inside the multiplicity range, or if any other constraint is violated, then
     *         a {@linkplain org.apache.sis.metadata.iso.quality.DefaultConformanceResult conformance result} is
     *         added for each violation with an
     *         {@linkplain org.apache.sis.metadata.iso.quality.DefaultConformanceResult#getExplanation() explanation}
     *         set to the error message.</p>
     *
     *         <div class="warning"><b>Note:</b> this is a departure from ISO intent, since {@code explanation}
     *         should be a statement about what a successful conformance means. This point may be reformulated
     *         in a future SIS version.</div>
     *       </li>
     *     </ul>
     *   </li>
     * </ul>
     *
     * This attribute is valid if this method does not report any
     * {@linkplain org.apache.sis.metadata.iso.quality.DefaultConformanceResult conformance result} having a
     * {@linkplain org.apache.sis.metadata.iso.quality.DefaultConformanceResult#pass() pass} value of {@code false}.
     *
     * <div class="note"><b>Example:</b> given an attribute named “population” with [1 … 1] multiplicity,
     * if no value has been assigned to that attribute, then this {@code quality()} method will return
     * the following data quality report:
     *
     * {@preformat text
     *   Data quality
     *     ├─Scope
     *     │   └─Level………………………………………………… Attribute
     *     └─Report
     *         ├─Measure identification
     *         │   └─Code………………………………………… population
     *         ├─Evaluation method type…… Direct internal
     *         └─Result
     *             ├─Explanation……………………… Missing value for “population” property.
     *             └─Pass………………………………………… false
     * }
     * </div>
     *
     * @return reports on all constraint violations found.
     *
     * @see AbstractFeature#quality()
     */
    public DataQuality quality() {
        final Validator v = new Validator(ScopeCode.ATTRIBUTE);
        v.validate(type, getValues());
        return v.quality;
    }

    /**
     * Returns a string representation of this attribute.
     * The returned string is for debugging purpose and may change in any future SIS version.
     * The current implementation is like below:
     *
     * {@preformat text
     *     Attribute[“temperature” : Float] = {20.3, 17.8, 21.1}
     *     └─ characteristics: units=°C, accuracy=0.1
     * }
     *
     * @return a string representation of this attribute for debugging purpose.
     */
    @Override
    public String toString() {
        final StringBuilder buffer = FieldType.toString(isDeprecated(type), "Attribute", type.getName(),
                Classes.getShortName(type.getValueClass()), getValues().iterator());
        if (characteristics != null && !characteristics.isEmpty()) {
            buffer.append(System.lineSeparator());
            String separator = "└─ characteristics: ";
            for (final Map.Entry<String,AbstractAttribute<?>> entry : characteristics.entrySet()) {
                buffer.append(separator).append(entry.getKey()).append('=').append(entry.getValue().getValue());
                separator = ", ";
            }
        }
        return buffer.toString();
    }

    /**
     * Returns a copy of this attribute if cloning is supported.
     * The decision to support cloning or not is left to subclasses. If the subclass does not implement
     * the {@link Cloneable} interface, then this method throws a {@link CloneNotSupportedException}.
     * Otherwise the default implementation returns a <em>shallow</em> copy of this {@code Attribute}:
     * the attribute {@linkplain #getValue() value} and {@linkplain #characteristics() characteristics}
     * are <strong>not</strong> cloned.
     * However subclasses may choose to do otherwise.
     *
     * @return a clone of this attribute.
     * @throws CloneNotSupportedException if this attribute, the {@linkplain #getValue() value}
     *         or one of its {@linkplain #characteristics() characteristics} can not be cloned.
     */
    @Override
    @SuppressWarnings("unchecked")
    public AbstractAttribute<V> clone() throws CloneNotSupportedException {
        final AbstractAttribute<V> clone = (AbstractAttribute<V>) super.clone();
        final Map<String,AbstractAttribute<?>> c = clone.characteristics;
        if (c instanceof CharacteristicMap) {
            clone.characteristics = ((CharacteristicMap) c).clone();
        }
        return clone;
    }
}