/*
 * Copyright 2019 The Android Open Source Project
 *
 * Licensed 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 android.app.timezonedetector;

import android.annotation.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.os.Parcel;
import android.os.Parcelable;
import android.os.ShellCommand;
import android.text.TextUtils;

import java.io.PrintWriter;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Objects;

/**
 * A time zone suggestion from an identified telephony source, e.g. from MCC and NITZ information
 * associated with a specific radio.
 *
 * <p>{@code slotIndex} identifies the suggestion source. This enables detection logic to identify
 * suggestions from the same source when there are several in use.
 *
 * <p>{@code zoneId}. When not {@code null}, {@code zoneId} contains the suggested time zone ID,
 * e.g. "America/Los_Angeles". Suggestion metadata like {@code matchType} and {@code quality} can be
 * used to judge quality / certainty of the suggestion. {@code zoneId} can be {@code null} to
 * indicate that the telephony source has entered an "un-opinionated" state and any previous
 * suggestion from the same source is being withdrawn.
 *
 * <p>{@code countryIsoCode}. When not {@code null}, {@code countryIsoCode} contains the country of
 * the suggested time zone ID, e.g. "us".
 *
 * <p>{@code matchType} must be set to {@link #MATCH_TYPE_NA} when {@code zoneId} is {@code null},
 * and one of the other {@code MATCH_TYPE_} values when it is not {@code null}.
 *
 * <p>{@code quality} must be set to {@link #QUALITY_NA} when {@code zoneId} is {@code null}, and
 * one of the other {@code QUALITY_} values when it is not {@code null}.
 *
 * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
 * record why the suggestion exists, e.g. what triggered it to be made and what heuristic was used
 * to determine the time zone or its absence. This information exists only to aid in debugging and
 * therefore is used by {@link #toString()}, but it is not for use in detection logic and is not
 * considered in {@link #hashCode()} or {@link #equals(Object)}.
 *
 * @hide
 */
public final class TelephonyTimeZoneSuggestion implements Parcelable {

    /** @hide */
    @NonNull
    public static final Creator<TelephonyTimeZoneSuggestion> CREATOR =
            new Creator<>() {
                public TelephonyTimeZoneSuggestion createFromParcel(Parcel in) {
                    return TelephonyTimeZoneSuggestion.createFromParcel(in);
                }

                public TelephonyTimeZoneSuggestion[] newArray(int size) {
                    return new TelephonyTimeZoneSuggestion[size];
                }
            };

    /**
     * Creates an empty time zone suggestion, i.e. one that will cancel previous suggestions with
     * the same {@code slotIndex}.
     */
    @NonNull
    public static TelephonyTimeZoneSuggestion createEmptySuggestion(
            int slotIndex, @NonNull String debugInfo) {
        return new Builder(slotIndex).addDebugInfo(debugInfo).build();
    }

    /** @hide */
    @IntDef({
        MATCH_TYPE_NA,
        MATCH_TYPE_NETWORK_COUNTRY_ONLY,
        MATCH_TYPE_NETWORK_COUNTRY_AND_OFFSET,
        MATCH_TYPE_EMULATOR_ZONE_ID,
        MATCH_TYPE_TEST_NETWORK_OFFSET_ONLY
    })
    @Retention(RetentionPolicy.SOURCE)
    public @interface MatchType {}

    /** Used when match type is not applicable. */
    public static final int MATCH_TYPE_NA = 0;

    /** Only the network country is known. */
    public static final int MATCH_TYPE_NETWORK_COUNTRY_ONLY = 2;

    /** Both the network county and offset were known. */
    public static final int MATCH_TYPE_NETWORK_COUNTRY_AND_OFFSET = 3;

    /**
     * The device is running in an emulator and an NITZ signal was simulated containing an Android
     * extension with an explicit Olson ID.
     */
    public static final int MATCH_TYPE_EMULATOR_ZONE_ID = 4;

    /**
     * The phone is most likely running in a test network not associated with a country (this is
     * distinct from the country just not being known yet). Historically, Android has just picked an
     * arbitrary time zone with the correct offset when on a test network.
     */
    public static final int MATCH_TYPE_TEST_NETWORK_OFFSET_ONLY = 5;

    /** @hide */
    @IntDef({
        QUALITY_NA,
        QUALITY_SINGLE_ZONE,
        QUALITY_MULTIPLE_ZONES_WITH_SAME_OFFSET,
        QUALITY_MULTIPLE_ZONES_WITH_DIFFERENT_OFFSETS
    })
    @Retention(RetentionPolicy.SOURCE)
    public @interface Quality {}

    /** Used when quality is not applicable. */
    public static final int QUALITY_NA = 0;

    /** There is only one answer */
    public static final int QUALITY_SINGLE_ZONE = 1;

    /**
     * There are multiple answers, but they all shared the same offset / DST state at the time the
     * suggestion was created. i.e. it might be the wrong zone but the user won't notice immediately
     * if it is wrong.
     */
    public static final int QUALITY_MULTIPLE_ZONES_WITH_SAME_OFFSET = 2;

    /** There are multiple answers with different offsets. The one given is just one possible. */
    public static final int QUALITY_MULTIPLE_ZONES_WITH_DIFFERENT_OFFSETS = 3;

    private final int mSlotIndex;
    @Nullable private final String mZoneId;
    @Nullable private final String mCountryIsoCode;
    @MatchType private final int mMatchType;
    @Quality private final int mQuality;
    @Nullable private List<String> mDebugInfo;
    @Nullable private final TelephonySignal mTelephonySignal;

    private TelephonyTimeZoneSuggestion(Builder builder) {
        mSlotIndex = builder.mSlotIndex;
        mZoneId = builder.mZoneId;
        mCountryIsoCode = builder.mCountryIsoCode;
        mMatchType = builder.mMatchType;
        mQuality = builder.mQuality;
        mDebugInfo = builder.mDebugInfo != null ? new ArrayList<>(builder.mDebugInfo) : null;
        mTelephonySignal = builder.mTelephonySignal;
    }

    @SuppressWarnings("unchecked")
    private static TelephonyTimeZoneSuggestion createFromParcel(Parcel in) {
        // Use the Builder so we get validation during build().
        int slotIndex = in.readInt();
        TelephonyTimeZoneSuggestion suggestion =
                new Builder(slotIndex)
                        .setZoneId(in.readString())
                        .setCountryIsoCode(in.readString())
                        .setMatchType(in.readInt())
                        .setQuality(in.readInt())
                        .setTelephonySignal(
                                in.readParcelable(
                                        TelephonySignal.class.getClassLoader(),
                                        TelephonySignal.class))
                        .build();
        List<String> debugInfo =
                in.readArrayList(
                        TelephonyTimeZoneSuggestion.class.getClassLoader(), java.lang.String.class);
        if (debugInfo != null) {
            suggestion.addDebugInfo(debugInfo);
        }
        return suggestion;
    }

    @Override
    public void writeToParcel(@NonNull Parcel dest, int flags) {
        dest.writeInt(mSlotIndex);
        dest.writeString(mZoneId);
        dest.writeString(mCountryIsoCode);
        dest.writeInt(mMatchType);
        dest.writeInt(mQuality);
        dest.writeParcelable(mTelephonySignal, flags);
        dest.writeList(mDebugInfo);
    }

    @Override
    public int describeContents() {
        return 0;
    }

    /**
     * Returns an identifier for the source of this suggestion.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code slotIndex}.
     */
    public int getSlotIndex() {
        return mSlotIndex;
    }

    /**
     * Returns the suggested time zone Olson ID, e.g. "America/Los_Angeles". {@code null} means that
     * the caller is no longer sure what the current time zone is.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code zoneId}.
     */
    @Nullable
    public String getZoneId() {
        return mZoneId;
    }

    /**
     * Returns the country where the time zone Olson ID was found, e.g. "gb". {@code null} means
     * that the caller is no longer sure what the current country is.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code countryIsoCode}.
     */
    @Nullable
    public String getCountryIsoCode() {
        return mCountryIsoCode;
    }

    /**
     * Returns information about how the suggestion was determined which could be used to rank
     * suggestions when several are available from different sources.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code matchType}.
     */
    @MatchType
    public int getMatchType() {
        return mMatchType;
    }

    /**
     * Returns information about the likelihood of the suggested zone being correct.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code quality}.
     */
    @Quality
    public int getQuality() {
        return mQuality;
    }

    /**
     * Returns debug metadata for the suggestion.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code debugInfo}.
     */
    @NonNull
    public List<String> getDebugInfo() {
        return mDebugInfo == null
                ? Collections.emptyList()
                : Collections.unmodifiableList(mDebugInfo);
    }

    /** Returns the {@link TelephonySignal} associated with this suggestion, or {@code null}. */
    @Nullable
    public TelephonySignal getTelephonySignal() {
        return mTelephonySignal;
    }

    /**
     * Associates information with the instance that can be useful for debugging / logging.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code debugInfo}.
     */
    public void addDebugInfo(@NonNull String debugInfo) {
        if (mDebugInfo == null) {
            mDebugInfo = new ArrayList<>();
        }
        mDebugInfo.add(debugInfo);
    }

    /**
     * Associates information with the instance that can be useful for debugging / logging.
     *
     * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code debugInfo}.
     */
    public void addDebugInfo(@NonNull List<String> debugInfo) {
        if (mDebugInfo == null) {
            mDebugInfo = new ArrayList<>(debugInfo.size());
        }
        mDebugInfo.addAll(debugInfo);
    }

    @Override
    public boolean equals(@Nullable Object o) {
        if (this == o) {
            return true;
        }
        if (o == null || getClass() != o.getClass()) {
            return false;
        }
        TelephonyTimeZoneSuggestion that = (TelephonyTimeZoneSuggestion) o;
        return mSlotIndex == that.mSlotIndex
                && mMatchType == that.mMatchType
                && mQuality == that.mQuality
                && Objects.equals(mZoneId, that.mZoneId)
                && Objects.equals(mCountryIsoCode, that.mCountryIsoCode)
                && Objects.equals(mTelephonySignal, that.mTelephonySignal);
    }

    @Override
    public int hashCode() {
        return Objects.hash(
                mSlotIndex, mZoneId, mCountryIsoCode, mMatchType, mQuality, mTelephonySignal);
    }

    @Override
    public String toString() {
        return "TelephonyTimeZoneSuggestion{"
                + "mSlotIndex="
                + mSlotIndex
                + ", mZoneId='"
                + mZoneId
                + '\''
                + ", mCountryIsoCode='"
                + mCountryIsoCode
                + '\''
                + ", mMatchType="
                + mMatchType
                + ", mQuality="
                + mQuality
                + ", mDebugInfo="
                + mDebugInfo
                + ", mTelephonySignal="
                + mTelephonySignal
                + '}';
    }

    /**
     * Builds {@link TelephonyTimeZoneSuggestion} instances.
     *
     * @hide
     */
    public static final class Builder {
        private final int mSlotIndex;
        @Nullable private String mZoneId;
        @Nullable private String mCountryIsoCode;
        @MatchType private int mMatchType;
        @Quality private int mQuality;
        @Nullable private List<String> mDebugInfo;
        @Nullable private TelephonySignal mTelephonySignal;

        /**
         * Creates a builder with the specified {@code slotIndex}.
         *
         * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code slotIndex}.
         */
        public Builder(int slotIndex) {
            mSlotIndex = slotIndex;
        }

        /**
         * Returns the builder for call chaining.
         *
         * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code zoneId}.
         */
        @NonNull
        public Builder setZoneId(@Nullable String zoneId) {
            mZoneId = zoneId;
            return this;
        }

        /**
         * Returns the builder for call chaining.
         *
         * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code
         * countryIsoCode}.
         */
        @Nullable
        public Builder setCountryIsoCode(@Nullable String countryIsoCode) {
            mCountryIsoCode = countryIsoCode;
            return this;
        }

        /**
         * Returns the builder for call chaining.
         *
         * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code matchType}.
         */
        @NonNull
        public Builder setMatchType(@MatchType int matchType) {
            mMatchType = matchType;
            return this;
        }

        /**
         * Returns the builder for call chaining.
         *
         * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code quality}.
         */
        @NonNull
        public Builder setQuality(@Quality int quality) {
            mQuality = quality;
            return this;
        }

        /**
         * Returns the builder for call chaining.
         *
         * <p>See {@link TelephonyTimeZoneSuggestion} for more information about {@code debugInfo}.
         */
        @NonNull
        public Builder addDebugInfo(@NonNull String debugInfo) {
            if (mDebugInfo == null) {
                mDebugInfo = new ArrayList<>();
            }
            mDebugInfo.add(debugInfo);
            return this;
        }

        /**
         * Sets the {@link TelephonySignal} for this suggestion. Returns the builder for call
         * chaining.
         */
        @NonNull
        public Builder setTelephonySignal(@Nullable TelephonySignal telephonySignal) {
            mTelephonySignal = telephonySignal;
            return this;
        }

        /**
         * Performs basic structural validation of this instance. e.g. Are all the fields populated
         * that must be? Are the enum ints set to valid values?
         */
        void validate() {
            int quality = mQuality;
            int matchType = mMatchType;
            if (mZoneId == null) {
                if (quality != QUALITY_NA || matchType != MATCH_TYPE_NA) {
                    throw new RuntimeException(
                            "Invalid quality or match type for null zone ID."
                                    + " quality="
                                    + quality
                                    + ", matchType="
                                    + matchType);
                }
            } else {
                boolean qualityValid =
                        (quality == QUALITY_SINGLE_ZONE
                                || quality == QUALITY_MULTIPLE_ZONES_WITH_SAME_OFFSET
                                || quality == QUALITY_MULTIPLE_ZONES_WITH_DIFFERENT_OFFSETS);
                boolean matchTypeValid =
                        (matchType == MATCH_TYPE_NETWORK_COUNTRY_ONLY
                                || matchType == MATCH_TYPE_NETWORK_COUNTRY_AND_OFFSET
                                || matchType == MATCH_TYPE_EMULATOR_ZONE_ID
                                || matchType == MATCH_TYPE_TEST_NETWORK_OFFSET_ONLY);
                if (!qualityValid || !matchTypeValid) {
                    throw new RuntimeException(
                            "Invalid quality or match type with zone ID."
                                    + " quality="
                                    + quality
                                    + ", matchType="
                                    + matchType);
                }
            }
        }

        /** Returns the {@link TelephonyTimeZoneSuggestion}. */
        @NonNull
        public TelephonyTimeZoneSuggestion build() {
            validate();
            return new TelephonyTimeZoneSuggestion(this);
        }
    }

    /** @hide */
    public static TelephonyTimeZoneSuggestion parseCommandLineArg(@NonNull ShellCommand cmd)
            throws IllegalArgumentException {
        Integer slotIndex = null;
        String zoneId = null;
        String countryIsoCode = null;
        Integer quality = null;
        Integer matchType = null;
        String opt;
        while ((opt = cmd.getNextArg()) != null) {
            switch (opt) {
                case "--slot_index" -> slotIndex = Integer.parseInt(cmd.getNextArgRequired());
                case "--zone_id" -> zoneId = cmd.getNextArgRequired();
                case "--country-iso-code" -> countryIsoCode = cmd.getNextArgRequired();
                case "--quality" -> quality = parseQualityCommandLineArg(cmd.getNextArgRequired());
                case "--match_type" ->
                        matchType = parseMatchTypeCommandLineArg(cmd.getNextArgRequired());
                // TelephonySignal ignored
                default -> throw new IllegalArgumentException("Unknown option: " + opt);
            }
        }

        if (slotIndex == null) {
            throw new IllegalArgumentException("No slotIndex specified.");
        }

        Builder builder = new Builder(slotIndex);
        if (!(TextUtils.isEmpty(zoneId) || "_".equals(zoneId))) {
            builder.setZoneId(zoneId);
        }
        if (!(TextUtils.isEmpty(countryIsoCode) || "_".equals(countryIsoCode))) {
            builder.setCountryIsoCode(countryIsoCode);
        }
        if (quality != null) {
            builder.setQuality(quality);
        }
        if (matchType != null) {
            builder.setMatchType(matchType);
        }
        builder.addDebugInfo("Command line injection");
        return builder.build();
    }

    private static int parseQualityCommandLineArg(@NonNull String arg) {
        return switch (arg) {
            case "single" -> QUALITY_SINGLE_ZONE;
            case "multiple_same" -> QUALITY_MULTIPLE_ZONES_WITH_SAME_OFFSET;
            case "multiple_different" -> QUALITY_MULTIPLE_ZONES_WITH_DIFFERENT_OFFSETS;
            default -> throw new IllegalArgumentException("Unrecognized quality: " + arg);
        };
    }

    private static int parseMatchTypeCommandLineArg(@NonNull String arg) {
        return switch (arg) {
            case "emulator" -> MATCH_TYPE_EMULATOR_ZONE_ID;
            case "country_with_offset" -> MATCH_TYPE_NETWORK_COUNTRY_AND_OFFSET;
            case "country" -> MATCH_TYPE_NETWORK_COUNTRY_ONLY;
            case "test_network" -> MATCH_TYPE_TEST_NETWORK_OFFSET_ONLY;
            default -> throw new IllegalArgumentException("Unrecognized match_type: " + arg);
        };
    }

    /** @hide */
    public static void printCommandLineOpts(@NonNull PrintWriter pw) {
        pw.println("Telephony suggestion options:");
        pw.println("  --slot_index <number>");
        pw.println("  To withdraw a previous suggestion:");
        pw.println("    [--zone_id \"_\"]");
        pw.println("  To make a new suggestion:");
        pw.println("    --zone_id <Olson ID>");
        pw.println("    --quality <single|multiple_same|multiple_different>");
        pw.println("    --match_type <emulator|country_with_offset|country|test_network>");
        pw.println();
        pw.println("Note: TelephonySignal data is not directly configurable via command line.");
        pw.println("See " + TelephonyTimeZoneSuggestion.class.getName() + " for more information");
    }
}
