/*
 * SPDX-FileCopyrightText: 2025 microG Project Team
 * SPDX-License-Identifier: Apache-2.0
 * Notice: Portions of this file are reproduced from work created and shared by Google and used
 *         according to terms described in the Creative Commons 4.0 Attribution License.
 *         See https://developers.google.com/readme/policies for details.
 */

package com.google.android.gms.common.internal;

import android.os.Handler;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.WorkerThread;
import com.google.android.gms.common.api.CommonStatusCodes;
import com.google.android.gms.common.api.GoogleApiClient;
import com.google.android.gms.common.api.PendingResult;
import com.google.android.gms.common.api.Result;
import com.google.android.gms.common.api.Status;

/**
 * Transforms a {@link Result} by making a subsequent API call.
 *
 * @see PendingResult#then(ResultTransform)
 */
public abstract class ResultTransform<R extends Result, S extends Result> {

    /**
     * Creates a failed result with the given {@link Status}. In the event of an error during {@link #onSuccess(Result)}, call this method and return the failed result.
     * <p>
     * Note: the {@link PendingResult} generated by this method must be returned directly from {@link #onSuccess(Result)}. It is an error to call any methods on this
     * {@link PendingResult}.
     */
    @NonNull
    public final PendingResult<S> createFailedResult(@NonNull Status status) {
        throw new UnsupportedOperationException();
    }

    /**
     * Called when the PendingResult to be transformed returns a failure. Default implementation simply propagates the failure, but subclasses
     * may override for custom failure handling. This method is called on the main thread, unless overridden by {@link GoogleApiClient.Builder#setHandler(Handler)}.
     *
     * @param status The status of the failure.
     * @return The status of the result of the transformation. Must not be success or null.
     */
    @NonNull
    public Status onFailure(@NonNull Status status) {
        return status;
    }

    /**
     * Transforms the result of a successful API call. This method is called on a background thread and should not access UI elements.
     *
     * @param result The successful result to be transformed. Never null. If this result is it will be automatically
     *               released after this transform is applied; it is not necessary to release the result inside
     *               onSuccess. It is an error to set callbacks on this result. Any callbacks set on this result will be
     *               overridden and will not be called.
     * @return The result of the transformation. Normally the result of another API call. To shortcut
     * execution and directly yield a failure, return either:
     * <ul>
     *     <li>{@code null}, which is translated into a {@link Status} with code {@link CommonStatusCodes#ERROR}; or</li>
     *     <li>a specific failure created using {@link #createFailedResult(Status)}.</li>
     * </ul>
     */
    @Nullable
    @WorkerThread
    public abstract PendingResult<S> onSuccess(@NonNull R result);
}
