1 /*
2  * Copyright 2023 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 androidx.webkit;
18 
19 import androidx.annotation.RequiresFeature;
20 import androidx.annotation.UiThread;
21 import androidx.webkit.internal.ApiFeature;
22 import androidx.webkit.internal.ProfileStoreImpl;
23 import androidx.webkit.internal.WebViewFeatureInternal;
24 
25 import org.jspecify.annotations.NonNull;
26 import org.jspecify.annotations.Nullable;
27 
28 import java.util.List;
29 
30 /**
31  * Manages any creation, deletion for {@link Profile}.
32  *
33  * <p>Example usage:
34  * <pre class="prettyprint">
35  *    ProfileStore profileStore = ProfileStore.getInstance();
36  * <p>
37  *    // Use this store instance to manage Profiles.
38  *    Profile createdProfile = profileStore.getOrCreateProfile("test_profile");
39  *    createdProfile.getGeolocationPermissions().clear("example");
40  *    //...
41  *    profileStore.deleteProfile("profile_test");
42  * <p>
43  * </pre>
44  */
45 @UiThread
46 public interface ProfileStore {
47 
48     /**
49      * Returns the production instance of ProfileStore.
50      *
51      * @return ProfileStore instance to use for managing profiles.
52      */
53     @RequiresFeature(name = WebViewFeature.MULTI_PROFILE,
54             enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getInstance()55     static @NonNull ProfileStore getInstance() {
56         ApiFeature.NoFramework feature = WebViewFeatureInternal.MULTI_PROFILE;
57         if (feature.isSupportedByWebView()) {
58             return ProfileStoreImpl.getInstance();
59         } else {
60             throw WebViewFeatureInternal.getUnsupportedOperationException();
61         }
62     }
63 
64     /**
65      * Returns a profile with the given name, creating if needed.
66      * <p>
67      * Returns the associated Profile with this name, if there's no match with this name it
68      * will create a new Profile instance.
69      *
70      * @param name name of the profile to retrieve.
71      * @return instance of {@link Profile} matching this name.
72      */
73     @RequiresFeature(name = WebViewFeature.MULTI_PROFILE,
74             enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getOrCreateProfile(@onNull String name)75     @NonNull Profile getOrCreateProfile(@NonNull String name);
76 
77     /**
78      * Returns a profile with the given name, if it exists.
79      * <p>
80      * Returns the associated Profile with this name, if there's no Profile with this name or the
81      * Profile was deleted by {@link ProfileStore#deleteProfile(String)} it will return null.
82      *
83      * @param name the name of the profile to retrieve.
84      * @return instance of {@link Profile} matching this name, null otherwise if there's no match.
85      */
86     @RequiresFeature(name = WebViewFeature.MULTI_PROFILE,
87             enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getProfile(@onNull String name)88     @Nullable Profile getProfile(@NonNull String name);
89 
90     /**
91      * Returns the names of all available profiles.
92      * <p>
93      * Default profile name will be included in this list.
94      *
95      * @return profile names as a list.
96      */
97     @RequiresFeature(name = WebViewFeature.MULTI_PROFILE,
98             enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getAllProfileNames()99     @NonNull List<String> getAllProfileNames();
100 
101     /**
102      * Deletes the profile data associated with the name.
103      * <p>
104      * If this method returns true, the {@link Profile} object associated with the name will no
105      * longer be usable by the application. Returning false means that this profile doesn't exist.
106      * <p>
107      * Some data may be deleted async and is not guaranteed to be cleared from disk by the time
108      * this method returns.
109      *
110      * @param name the profile name to be deleted.
111      * @return {@code true} if profile exists and its data is to be deleted, otherwise {@code
112      * false}.
113      * @throws IllegalStateException if there are living WebViews associated with that profile.
114      * @throws IllegalStateException if you are trying to delete a Profile that was loaded in the
115      * memory using {@link ProfileStore#getOrCreateProfile(String)}} or
116      * {@link ProfileStore#getProfile(String)}.
117      * @throws IllegalArgumentException if you are trying to delete the default Profile.
118      */
119     @RequiresFeature(name = WebViewFeature.MULTI_PROFILE,
120             enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
deleteProfile(@onNull String name)121     boolean deleteProfile(@NonNull String name);
122 }
123