1 /*
2  * Copyright 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.webkit;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.annotation.SystemApi;
22 import android.net.Network;
23 
24 /**
25  * Class to evaluate PAC scripts.
26  * @hide
27  */
28 
29 @SystemApi
30 public interface PacProcessor {
31 
32     /**
33      * Returns the default PacProcessor instance.
34      *
35      * <p> There can only be one default {@link PacProcessor} instance.
36      * This method will create a new instance if one did not already exist, or
37      * if the previous instance was released with {@link #release}.
38      *
39      * @return the default PacProcessor instance.
40      */
41     @NonNull
getInstance()42     static PacProcessor getInstance() {
43         return WebViewFactory.getProvider().getPacProcessor();
44     }
45 
46     /**
47      * Create a new PacProcessor instance.
48      *
49      * <p> The created instance needs to be released manually once it is no longer needed
50      * by calling {@link #release} to prevent memory leaks.
51      *
52      * <p> The created instance is not tied to any particular {@link Network}.
53      * To associate {@link PacProcessor} with a {@link Network} use {@link #setNetwork} method.
54      */
55     @NonNull
createInstance()56     static PacProcessor createInstance() {
57         return WebViewFactory.getProvider().createPacProcessor();
58     }
59 
60     /**
61      * Set PAC script to use.
62      *
63      * @param script PAC script.
64      * @return true if PAC script is successfully set.
65      */
setProxyScript(@onNull String script)66     boolean setProxyScript(@NonNull String script);
67 
68     /**
69      * Gets a list of proxy servers to use.
70      * @param url The URL being accessed.
71      * @return a PAC-style semicolon-separated list of valid proxy servers.
72      *         For example: "PROXY xxx.xxx.xxx.xxx:xx; SOCKS yyy.yyy.yyy:yy".
73      */
74     @Nullable
findProxyForUrl(@onNull String url)75     String findProxyForUrl(@NonNull String url);
76 
77     /**
78      * Stops support for this {@link PacProcessor} and release its resources.
79      * No methods of this class must be called after calling this method.
80      *
81      * <p> Released instances will not be reused; a subsequent call to
82      * {@link #getInstance} and {@link #getInstanceForNetwork}
83      * for the same network will create a new instance.
84      */
release()85     default void release() {
86         throw new UnsupportedOperationException("Not implemented");
87     }
88 
89     /**
90      * Associate {@link PacProcessor} instance with the {@link Network}.
91      * Once this method returns host resolution is done on the set {@link Network}.
92 
93      * @param network a {@link Network} which this {@link PacProcessor}
94      * will use for host/address resolution. If {@code null} reset
95      * {@link PacProcessor} instance so it is not associated with any {@link Network}.
96      */
setNetwork(@ullable Network network)97     default void setNetwork(@Nullable Network network) {
98         throw new UnsupportedOperationException("Not implemented");
99     }
100 
101     /**
102      * Returns a {@link Network} associated with this {@link PacProcessor}.
103      *
104      * @return an associated {@link Network} or {@code null} if a network is unspecified.
105      */
106     @Nullable
getNetwork()107     default Network getNetwork() {
108         throw new UnsupportedOperationException("Not implemented");
109     }
110 }
111