/*
 * 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.measure;

import java.util.Map;
import java.util.Objects;
import java.io.Serializable;
import java.io.ObjectStreamException;
import javax.measure.Unit;
import javax.measure.Quantity;
import javax.measure.Dimension;
import javax.measure.UnitConverter;
import javax.measure.UnconvertibleException;
import javax.measure.IncommensurableException;
import javax.measure.spi.QuantityFactory;
import org.apache.sis.util.Characters;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.ObjectConverters;
import org.apache.sis.util.ComparisonMode;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.internal.converter.SurjectiveConverter;
import org.apache.sis.math.Fraction;


/**
 * Implementation of base, alternate and derived units (see {@link AbstractUnit} for a description of unit kinds).
 * A {@code SystemUnit} is a base or alternate unit if associated to a base {@link UnitDimension}, or is a derived
 * units otherwise. No other type is allowed since {@code SystemUnit} is always a combination of fundamental units
 * without scale factor or offset.
 *
 * @author  Martin Desruisseaux (MPO, Geomatys)
 * @version 1.0
 *
 * @param <Q>  the kind of quantity to be measured using this units.
 *
 * @since 0.8
 * @module
 */
final class SystemUnit<Q extends Quantity<Q>> extends AbstractUnit<Q> implements QuantityFactory<Q> {
    /**
     * For cross-version compatibility.
     */
    private static final long serialVersionUID = 4097466138698631914L;

    /**
     * The non-empty symbol for {@link Units#UNITY}.
     */
    static final String ONE = "1";

    /**
     * The type of quantity that uses this unit, or {@code null} if unknown.
     */
    final Class<Q> quantity;

    /**
     * The dimension of this unit of measurement. Can not be null.
     */
    final UnitDimension dimension;

    /**
     * The factory to use for creating quantities, or {@code null} if none.
     * This field does not need to be serialized because {@link AbstractUnit#readResolve()}
     * replaces deserialized instances by corresponding {@link Units} hard-coded instances.
     */
    final transient ScalarFactory<Q> factory;

    /**
     * Units for the same quantity but with scale factors that are not the SI one.
     * This is initialized by {@link Units} only and shall not change anymore after.
     * All units in this array shall use an instance of {@link LinearConverter}.
     *
     * @see #related(int)
     */
    private transient ConventionalUnit<Q>[] related;

    /**
     * Creates a new unit having the given symbol and EPSG code.
     *
     * @param  quantity   the type of quantity that uses this unit, or {@code null} if unknown.
     * @param  dimension  the unit dimension.
     * @param  symbol     the unit symbol, or {@code null} if this unit has no specific symbol.
     * @param  scope      {@link UnitRegistry#SI}, {@link UnitRegistry#ACCEPTED}, other constants or 0 if unknown.
     * @param  epsg       the EPSG code, or 0 if this unit has no EPSG code.
     * @param  factory    the factory to use for creating quantities, or {@code null} if none.
     */
    SystemUnit(final Class<Q> quantity, final UnitDimension dimension, final String symbol,
            final byte scope, final short epsg, final ScalarFactory<Q> factory)
    {
        super(symbol, scope, epsg);
        this.quantity  = quantity;
        this.dimension = dimension;
        this.factory   = factory;
    }

    /**
     * Returns a unit of the given dimension with default name and symbol.
     * This method is invoked for creating the result of arithmetic operations.
     * If there is no predefined unit for the given dimension, then the new unit may be allocated a symbol derived from
     * this unit's symbol. A new symbol is created only if this unit symbol and the {@code other} unit symbol are simple
     * (for example "m" but not "m²", or "N" but not "N/m").
     *
     * @param  operation  symbol to write after the symbol of this unit for generating the new unit symbol, or 0
     *                    for not inferring new symbol. Ignored if the condition documented in javadoc does not hold.
     * @param  other      other units to append after the operation symbol, or {@code null} if none or should be ignored.
     *                    Ignored if the condition documented in javadoc does not hold.
     */
    private SystemUnit<?> create(final UnitDimension newDimension, final char operation, final Unit<?> other) {
        /*
         * Check if we are computing the inverse of the other unit. We are computing inverse
         * if this unit is unity ("1") and is used as the numerator of a division. The unity
         * symbol is an empty string but we will format it as "1".
         */
        String ts = getSymbol();
        final boolean inverse = (ts != null && ts.isEmpty() && operation == DIVIDE);
        /*
         * Check if the SystemUnit to create is known to Units, provided that no dimensionless units
         * is involved. If a dimensionless unit is involved, we will try to build a symbol before to
         * check if the unit is known to Units. The reason is that there is many dimensionless units
         * with different symbols (rad, sr, psu, …).
         */
        final boolean deferred = newDimension.isDimensionless() || (!inverse && dimension.isDimensionless()) ||
                (other != null && UnitDimension.isDimensionless(other.getDimension()));
        if (!deferred) {
            final SystemUnit<?> result = Units.get(newDimension);
            if (result != null) return result;
        }
        /*
         * Try to create a unit symbol as the concatenation of the symbols of the two units,
         * with the operation symbol between them. If we can not, 'symbol' will stay null.
         */
        String symbol = null;
        if (operation != 0) {
            symbol = inferSymbol(operation, other);
        }
        /*
         * Performs now the check that we did not performed at the
         * beginning of this method if any component was unitless.
         * The difference is that we take unit symbol in account.
         */
        if (deferred) {
            final SystemUnit<?> result = Units.get(newDimension);
            if (result != null && result.sameSymbol(symbol)) {
                return result;
            }
        }
        if (newDimension == dimension && sameSymbol(symbol)) {
            return this;
        }
        return new SystemUnit<>(null, newDimension, symbol, (byte) 0, (short) 0, null);
    }

    /**
     * Returns {@code true} if the given symbol is null or equals to the symbol of this unit.
     */
    private boolean sameSymbol(final String symbol) {
        return (symbol == null) || symbol.equals(getSymbol());
    }

    /**
     * Returns the dimension of this unit.
     * Two units {@code u1} and {@code u2} are {@linkplain #isCompatible(Unit) compatible}
     * if and only if {@code u1.getDimension().equals(u2.getDimension())}.
     *
     * @return the dimension of this unit.
     *
     * @see #isCompatible(Unit)
     */
    @Override
    public Dimension getDimension() {
        return dimension;
    }

    /**
     * Returns the unscaled system unit from which this unit is derived.
     * Since this unit is already a base, alternate or derived unit, this method returns {@code true}.
     *
     * @return {@code this}
     */
    @Override
    public SystemUnit<Q> getSystemUnit() {
        return this;
    }

    /**
     * Returns the base units and their exponent whose product is this unit,
     * or {@code null} if this unit is a base unit (not a product of existing units).
     *
     * @return the base units and their exponent making up this unit.
     */
    @Override
    public Map<SystemUnit<?>, Integer> getBaseUnits() {
        final Map<UnitDimension,Integer> dim = dimension.getBaseDimensions();
        if (dim == null) {
            return null;            // This unit is associated to a base dimension.
        }
        return ObjectConverters.derivedKeys(dim, DimToUnit.INSTANCE, Integer.class);
    }

    /**
     * Returns the base units used by Apache SIS implementations.
     * Contrarily to {@link #getBaseUnits()}, this method never returns {@code null}.
     */
    @Override
    final Map<SystemUnit<?>, Fraction> getBaseSystemUnits() {
        return ObjectConverters.derivedKeys(dimension.components, DimToUnit.INSTANCE, Fraction.class);
    }

    /**
     * The converter for replacing the keys in the {@link SystemUnit#getBaseUnits()} map from {@link UnitDimension}
     * instances to {@link SystemUnit} instances. We apply conversions on the fly instead than extracting the data in
     * a new map once for all because the copy may fail if an entry contains a rational instead than an integer power.
     * With on-the-fly conversions, the operation will not fail if the user never ask for that particular value.
     */
    private static final class DimToUnit extends SurjectiveConverter<UnitDimension, SystemUnit<?>> implements Serializable {
        /**
         * For cross-version compatibility.
         */
        private static final long serialVersionUID = 7545067577687885675L;

        /**
         * The unique instance used by {@link SystemUnit#getBaseUnits()}.
         */
        static final DimToUnit INSTANCE = new DimToUnit();

        /**
         * Constructor for the singleton {@link #INSTANCE}.
         */
        private DimToUnit() {
        }

        /**
         * Returns the type of key values in the map returned by {@link UnitDimension#getBaseDimensions()}.
         */
        @Override
        public Class<UnitDimension> getSourceClass() {
            return UnitDimension.class;
        }

        /**
         * Returns the type of key values in the map to be returned by {@link SystemUnit#getBaseUnits()}.
         */
        @Override
        @SuppressWarnings("unchecked")
        public Class<SystemUnit<?>> getTargetClass() {
            return (Class) SystemUnit.class;
        }

        /**
         * Returns the unit associated to the given dimension, or {@code null} if none.
         */
        @Override
        public SystemUnit<?> apply(final UnitDimension dim) {
            return Units.get(dim);
        }

        /**
         * Invoked on deserialization for replacing the deserialized instance by the unique instance.
         */
        Object readResolve() throws ObjectStreamException {
            return INSTANCE;
        }
    }

    /**
     * Casts this unit to a parameterized unit of specified nature or throw a {@code ClassCastException}
     * if the dimension of the specified quantity and this unit's dimension do not match.
     *
     * @param  <T>   the type of the quantity measured by the unit.
     * @param  type  the quantity class identifying the nature of the unit.
     * @return this unit parameterized with the specified type.
     * @throws ClassCastException if the dimension of this unit is different from the specified quantity dimension.
     */
    @Override
    @SuppressWarnings("unchecked")
    public <T extends Quantity<T>> Unit<T> asType(final Class<T> type) throws ClassCastException {
        ArgumentChecks.ensureNonNull("type", type);
        if (type == quantity) {
            if (getSymbol() == null) {
                // If this unit has no symbol, opportunistically supply a symbol if we find it.
                final SystemUnit<T> unit = Units.get(type);
                if (unit != null) {
                    return unit;
                }
            }
            return (Unit<T>) this;
        }
        /*
         * Verifies what are the expected dimensions of the given type by searching for the corresponding unit.
         * If we find that unit, returns it on the assumption that its symbol is right while the symbol of this
         * unit may no longer be right for the given type.  If we can not find a pre-defined units, then create
         * a new unit with the requested type but no symbol since we do not know yet what the symbol should be
         * for the new quantity.
         */
        SystemUnit<T> unit = Units.get(type);
        if (unit == null) {
            unit = new SystemUnit<>(type, dimension, null, (byte) 0, (short) 0, null);  // Intentionally no symbol.
        }
        if (!dimension.equals(unit.dimension)) {
            throw new ClassCastException(Errors.format(Errors.Keys.IncompatibleUnitDimension_5, new Object[] {
                    this, (quantity != null) ? quantity.getSimpleName() : "?", dimension,
                    type.getSimpleName(), unit.dimension}));
        }
        return unit;
    }

    /**
     * Returns {@code true} if this unit is equals to the given unit ignoring name, symbol and EPSG code.
     * This method should always returns {@code true} if parameterized type has not been compromised with
     * raw types or unchecked casts.
     *
     * @param  other  the other unit, which must be a system unit.
     */
    final boolean equalsIgnoreMetadata(final Unit<Q> other) {
        if (quantity != null && other instanceof SystemUnit<?>) {
            /*
             * For SIS implementation, we just need to compare the quantity class, if known.
             * Two units for the same quantity implies that they are also for the same dimension.
             */
            final Class<?> c = ((SystemUnit<Q>) other).quantity;
            if (c != null) {
                return (quantity == c);
            }
        }
        /*
         * For foreigner implementations, comparing the units dimension is better than nothing.
         * But this check is not as reliable as comparing the quantity classes.
         */
        assert other == other.getSystemUnit() : other;
        return dimension.equals(other.getDimension());
    }

    /**
     * Returns a converter of numeric values from this unit to another unit of same type.
     *
     * @param  unit  the unit of same type to which to convert the numeric values.
     * @return the converter from this unit to {@code that} unit.
     * @throws UnconvertibleException if the converter can not be constructed.
     */
    @Override
    public UnitConverter getConverterTo(final Unit<Q> unit) throws UnconvertibleException {
        ArgumentChecks.ensureNonNull("unit", unit);
        final Unit<Q> step = unit.getSystemUnit();
        if (step != this && !equalsIgnoreMetadata(step)) {
            // Should never occur unless parameterized type has been compromised.
            throw new UnconvertibleException(incompatible(unit));
        }
        if (step == unit) {
            return IdentityConverter.INSTANCE;
        }
        /*
         * At this point we know that the given units is not a system unit. Ask the conversion
         * FROM the given units (before to inverse it) instead than TO the given units because
         * in Apache SIS implementation, the former returns directly ConventionalUnit.toTarget
         * while the later implies a recursive call to this method.
         */
        return unit.getConverterTo(step).inverse();
    }

    /**
     * Returns a converter from this unit to the specified unit of unknown type.
     * This method can be used when the quantity type of the specified unit is unknown at compile-time
     * or when dimensional analysis allows for conversion between units of different type.
     *
     * @param  unit  the unit to which to convert the numeric values.
     * @return the converter from this unit to {@code that} unit.
     * @throws IncommensurableException if this unit is not {@linkplain #isCompatible(Unit) compatible} with {@code that} unit.
     *
     * @see #isCompatible(Unit)
     */
    @Override
    public UnitConverter getConverterToAny(final Unit<?> unit) throws IncommensurableException {
        ArgumentChecks.ensureNonNull("unit", unit);
        final Unit<?> step = unit.getSystemUnit();
        if (step != this && !isCompatible(step)) {
            throw new IncommensurableException(incompatible(unit));
        }
        if (step == unit) {
            return IdentityConverter.INSTANCE;
        }
        // Same remark than in getConverterTo(Unit).
        return unit.getConverterToAny(step).inverse();
    }

    /**
     * Returns a system unit equivalent to this unscaled standard unit but used in expressions
     * to distinguish between quantities of a different nature but of the same dimensions.
     *
     * <p>The most important alternate unit in Apache SIS is {@link Units#RADIAN}, defined as below:</p>
     *
     * {@preformat java
     *   Unit<Angle> RADIAN = ONE.alternate("rad").asType(Angle.class);
     * }
     *
     * @param  symbol  the new symbol for the alternate unit.
     * @return the alternate unit.
     * @throws IllegalArgumentException if the specified symbol is already associated to a different unit.
     */
    @Override
    @SuppressWarnings("unchecked")
    public Unit<Q> alternate(final String symbol) {
        ArgumentChecks.ensureNonEmpty("symbol", symbol);
        final int c = invalidCharForSymbol(symbol, 0, false);
        if (c >= 0) {
            throw new IllegalArgumentException(Errors.format(Errors.Keys.IllegalCharacter_2,
                    "symbol", String.valueOf(Character.toChars(c))));
        }
        if (symbol.equals(getSymbol())) {
            return this;
        }
        final SystemUnit<Q> alt = new SystemUnit<>(quantity, dimension, symbol, (byte) 0, (short) 0, factory);
        if (quantity != null) {
            /*
             * Use the cache only if this unit has a non-null quantity type. Do not use the cache even
             * in read-only mode when 'quantity' is null because we would be unable to guarantee that
             * the parameterized type <Q> is correct.
             */
            final Object existing = UnitRegistry.putIfAbsent(symbol, alt);
            if (existing != null) {
                if (existing instanceof SystemUnit<?>) {
                    final SystemUnit<?> unit = (SystemUnit<?>) existing;
                    if (quantity.equals(unit.quantity) && dimension.equals(unit.dimension)) {
                        return (SystemUnit<Q>) unit;
                    }
                }
                throw new IllegalArgumentException(Errors.format(Errors.Keys.ElementAlreadyPresent_1, symbol));
            }
            /*
             * This method may be invoked for a new quantity, after a call to 'asType(Class)'.
             * Try to register the new unit for that Quantity. But if another unit is already
             * registered for that Quantity, this is not necessarily an error.
             */
            UnitRegistry.putIfAbsent(quantity, alt);
        }
        return alt;
    }

    /**
     * Returns the product of this unit with the one specified.
     *
     * @param  multiplier  the unit multiplier.
     * @return {@code this} × {@code multiplier}
     */
    @Override
    public Unit<?> multiply(final Unit<?> multiplier) {
        ArgumentChecks.ensureNonNull("multiplier", multiplier);
        if (multiplier == this) return pow(2);                      // For formating e.g. "K²" instead than "K⋅K".
        return product(multiplier, false);
    }

    /**
     * Returns the quotient of this unit with the one specified.
     *
     * @param  divisor  the unit divisor.
     * @return {@code this} ∕ {@code divisor}
     */
    @Override
    public Unit<?> divide(final Unit<?> divisor) {
        ArgumentChecks.ensureNonNull("divisor", divisor);
        return product(divisor, true);
    }

    /**
     * Implementation of {@link #multiply(Unit)} and {@link #divide(Unit)} methods.
     *
     * @param  inverse  wether to use the inverse of {@code other}.
     */
    private <T extends Quantity<T>> Unit<?> product(final Unit<T> other, final boolean inverse) {
        final Unit<T> intermediate = other.getSystemUnit();
        final Dimension dim = intermediate.getDimension();
        final UnitDimension newDimension;
        final char operation;
        if (inverse) {
            operation = DIVIDE;
            newDimension = dimension.divide(dim);
        } else {
            operation = MULTIPLY;
            newDimension = dimension.multiply(dim);
        }
        final boolean transformed = (intermediate != other);
        Unit<?> result = create(newDimension, operation, transformed ? null : other);
        if (transformed) {
            UnitConverter c = other.getConverterTo(intermediate);
            if (!c.isLinear()) {
                throw new IllegalArgumentException(Errors.format(Errors.Keys.NonRatioUnit_1, other));
            }
            if (!c.isIdentity()) {
                if (inverse) c = c.inverse();
                result = result.transform(c);
                /*
                 * If the system unit product is an Apache SIS implementation, try to infer a unit symbol
                 * to be given to our customized 'transform' method. Otherwise fallback on standard API.
                 */
                result = inferSymbol(result, operation, other);
            }
        }
        return result;
    }

    /**
     * Returns a unit equals to this unit raised to an exponent.
     *
     * @param  n  the exponent.
     * @return the result of raising this unit to the exponent.
     */
    @Override
    public Unit<?> pow(final int n) {
        switch (n) {
            case 0: return Units.UNITY;
            case 1: return this;
            default: {
                final char p = (n >= 0 && n <= 9) ? Characters.toSuperScript((char) ('0' + n)) : 0;
                return create(dimension.pow(n), p, null);
            }
        }
    }

    /**
     * Returns a unit equals to the given root of this unit.
     *
     * @param  n  the root's order.
     * @return the result of taking the given root of this unit.
     * @throws ArithmeticException if {@code n == 0}.
     */
    @Override
    public Unit<?> root(final int n) {
        return create(dimension.root(n), (char) 0, null);
    }

    /**
     * Returns the unit derived from this unit using the specified converter.
     *
     * @param  operation  the converter from the transformed unit to this unit.
     * @return the unit after the specified transformation.
     */
    @Override
    public Unit<Q> transform(UnitConverter operation) {
        ArgumentChecks.ensureNonNull("operation", operation);
        AbstractUnit<Q> base = this;
        final ConventionalUnit<Q> pseudo = Prefixes.pseudoSystemUnit(this);
        if (pseudo != null) {
            /*
             * Special case for Units.KILOGRAM, to be replaced by Units.GRAM so a prefix can be computed.
             * The kilogram may appear in an expression like "kg/m", which we want to replace by "g/m".
             *
             * Note: we could argue that this block should be UnitFormat's work rather than SystemUnit.
             * We perform this work here because this unit symbol may be different than what UnitFormat
             * would infer, for example because of symbols recorded by sequence of Unit.multiply(Unit)
             * and Unit.divide(Unit) operations.
             */
            operation = operation.concatenate(pseudo.toTarget.inverse());
            base = pseudo;
        }
        return ConventionalUnit.create(base, operation);
    }

    /**
     * Invoked by {@link Units} initializer before to fill the {@link #related} array.
     * We define this method only for isolating the generic array creation.
     */
    @SuppressWarnings({"unchecked", "rawtypes"})
    final void related(final int n) {
        if (related != null) {
            throw new IllegalStateException();
        }
        related = new ConventionalUnit[n];
    }

    /**
     * Returns units for the same quantity but with scale factors that are not the SI one, or {@code null} if none.
     * This method returns a direct reference to the internal field; caller shall not modify.
     */
    @Override
    @SuppressWarnings("ReturnOfCollectionOrArrayField")
    final ConventionalUnit<Q>[] related() {
        return related;
    }

    /**
     * Compares this unit with the given object for equality,
     * optionally ignoring metadata and rounding errors.
     *
     * @param  other  the other object to compare with this unit, or {@code null}.
     * @return {@code true} if the given object is equal to this unit.
     */
    @Override
    public boolean equals(final Object other, final ComparisonMode mode) {
        if (other == this) {
            return true;
        }
        if (super.equals(other, mode)) {
            final SystemUnit<?> that = (SystemUnit<?>) other;
            return Objects.equals(quantity, that.quantity) && dimension.equals(that.dimension);
        }
        return false;
    }

    /**
     * Returns a hash code value for this unit.
     */
    @Override
    public int hashCode() {
        return super.hashCode() + 37 * dimension.hashCode();
    }

    /**
     * Creates a quantity for the given value and unit of measurement.
     */
    @Override
    public Quantity<Q> create(final Number value, final Unit<Q> unit) {
        final double v = AbstractConverter.doubleValue(value);
        if (factory != null) {
            return factory.create(v, unit);
        } else {
            return ScalarFallback.factory(v, unit, quantity);
        }
    }
}
