/*
 * Copyright 2018 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 androidx.webkit;

import androidx.annotation.NonNull;
import androidx.annotation.RequiresFeature;
import androidx.annotation.RestrictTo;
import androidx.webkit.internal.ProxyControllerImpl;

import java.util.concurrent.Executor;

/**
 * Manages setting and clearing a process-specific override for the Android system-wide proxy
 * settings that govern network requests made by {@link android.webkit.WebView}.
 * <p>
 * WebView may make network requests in order to fetch content that is not otherwise read from
 * the file system or provided directly by application code. In this case by default the
 * system-wide Android network proxy settings are used to redirect requests to appropriate proxy
 * servers.
 * <p>
 * In the rare case that it is necessary for an application to explicitly specify its proxy
 * configuration, this API may be used to explicitly specify the proxy rules that govern WebView
 * initiated network requests.
 *
 * <p>
 * Example usage:
 * <pre class="prettyprint">
 * ProxyConfig proxyConfig = new ProxyConfig.Builder().addProxyRule("myproxy.com")
 *                                                    .addBypassRule("www.excluded.*")
 *                                                    .build();
 * Executor executor = ...
 * Runnable listener = ...
 * ProxyController.getInstance().setProxyOverride(proxyConfig, executor, listener);
 * ...
 * ProxyController.getInstance().clearProxyOverride(executor, listener);
 * </pre>
 */
public abstract class ProxyController {
    /**
     * @hide Don't allow apps to sub-class this class.
     */
    @RestrictTo(RestrictTo.Scope.LIBRARY)
    public ProxyController() {}

    /**
     * Returns the {@link ProxyController} instance.
     *
     * <p>
     * This method should only be called if {@link WebViewFeature#isFeatureSupported(String)}
     * returns {@code true} for {@link WebViewFeature#PROXY_OVERRIDE}.
     */
    @RequiresFeature(name = WebViewFeature.PROXY_OVERRIDE,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    @NonNull
    public static ProxyController getInstance() {
        if (!WebViewFeature.isFeatureSupported(WebViewFeature.PROXY_OVERRIDE)) {
            throw new UnsupportedOperationException("Proxy override not supported");
        }
        return LAZY_HOLDER.INSTANCE;
    }

    private static class LAZY_HOLDER {
        static final ProxyController INSTANCE = new ProxyControllerImpl();
    }

    /**
     * Sets {@link ProxyConfig} which will be used by all WebViews in the app. URLs that match
     * patterns in the bypass list will not be directed to any proxy. Instead, the request will be
     * made directly to the origin specified by the URL. Network connections are not guaranteed to
     * immediately use the new proxy setting; wait for the listener before loading a page. This
     * listener will be called in the provided executor.
     *
     * <p class="note"><b>Note:</b> calling setProxyOverride will cause any existing system wide
     * setting to be ignored.
     *
     * @param proxyConfig Proxy config to be applied
     * @param executor Executor for the listener to be executed in
     * @param listener Listener called when the proxy setting change has been applied
     *
     * @throws IllegalArgumentException If the proxyConfig is invalid
     */
    public abstract void setProxyOverride(@NonNull ProxyConfig proxyConfig,
            @NonNull Executor executor, @NonNull Runnable listener);

    /**
     * Clears the proxy settings. Network connections are not guaranteed to immediately use the
     * new proxy setting; wait for the listener before loading a page. This listener will be called
     * in the provided executor.
     *
     * @param executor Executor for the listener to be executed in
     * @param listener Listener called when the proxy setting change has been applied
     */
    public abstract void clearProxyOverride(@NonNull Executor executor,
            @NonNull Runnable listener);
}