001package Torello.Browser.BrowserAPI; 002 003// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 004// Java-HTML Imports 005// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 006 007import Torello.Browser.*; 008import Torello.Browser.helper.*; 009import Torello.Browser.JavaScriptAPI.*; 010import Torello.JSON.*; 011 012import Torello.Java.ReadOnly.ReadOnlyList; 013import Torello.Java.ReadOnly.ReadOnlyArrayList; 014 015import Torello.JavaDoc.Annotations.StaticFunctional; 016import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg; 017 018import Torello.Browser.BrowserAPI.NestedHelpers.Commands.Extensions$$Commands; 019 020 021// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 022// JDK Imports 023// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 024 025import javax.json.JsonObject; 026import javax.json.JsonValue; 027 028/** 029 * <SPAN CLASS=COPIEDJDK><B>Defines commands and events for browser extensions.</B></SPAN> 030 * <EMBED CLASS='external-html' DATA-FILE-ID=CDP.CODE_GEN_NOTE> 031 */ 032@StaticFunctional@JDHeaderBackgroundImg(EmbedTagFileID="CDP.WOOD_PLANK_NOTE") 033public class Extensions 034{ 035 // No Pubic Constructors 036 private Extensions() { } 037 038 039 // ******************************************************************************************** 040 // ******************************************************************************************** 041 // Enumerated String Constants Lists 042 // ******************************************************************************************** 043 // ******************************************************************************************** 044 045 046 /** 047 * Storage areas. 048 * <BR /><BR /><B CLASS=StrEnumType>String-Enumeration Type</B> 049 */ 050 public static final ReadOnlyList<String> StorageArea = new ReadOnlyArrayList<> 051 (String.class, "local", "managed", "session", "sync"); 052 053 054 055 056 057 // ******************************************************************************************** 058 // ******************************************************************************************** 059 // Commands 060 // ******************************************************************************************** 061 // ******************************************************************************************** 062 063 064 /** 065 * Clears extension storage in the given <CODE>storageArea</CODE>. 066 * 067 * @param id ID of extension. 068 * 069 * @param storageArea StorageArea to remove data from. 070 * 071 * @return An instance of <CODE>{@link Script}<Void></CODE> 072 * 073 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 074 * browser receives the invocation-request. 075 * 076 * <BR /><BR /><DIV CLASS=JDHint> 077 * This Browser-Function <I>does not have</I> a return-value. You may choose to 078 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 079 * the Browser Function has run to completion. 080 * </DIV> 081 */ 082 public static Script<Void> clearStorageItems(String id, String storageArea) 083 { 084 // Convert all Method Parameters into a JSON Request-Object (as a String) 085 final String requestJSON = WriteJSON.get( 086 Extensions$$Commands.clearStorageItems$$, "Extensions.clearStorageItems", 087 id, storageArea 088 ); 089 090 return Script.NO_RET(Domains.Extensions, "clearStorageItems", requestJSON); 091 } 092 093 /** 094 * Gets data from extension storage in the given <CODE>storageArea</CODE>. If <CODE>keys</CODE> is 095 * specified, these are used to filter the result. 096 * 097 * @param id ID of extension. 098 * 099 * @param storageArea StorageArea to retrieve data from. 100 * 101 * @param keys Keys to retrieve. 102 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 103 * 104 * @return An instance of <CODE>{@link Script}<JsonValue></CODE> 105 * 106 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 107 * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise} 108 * <CODE><JsonValue></CODE> will be returned 109 * 110 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 111 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 112 * be retrieved.</I> 113 * 114 * <BR /><BR /><DIV CLASS=JDHint> 115 * This Browser Function's {@code Promise} returns: 116 * <CODE>JsonValue (<B>data</B>)</CODE> 117 * </DIV> 118 */ 119 public static Script<JsonValue> getStorageItems(String id, String storageArea, String[] keys) 120 { 121 // Convert all Method Parameters into a JSON Request-Object (as a String) 122 final String requestJSON = WriteJSON.get( 123 Extensions$$Commands.getStorageItems$$, "Extensions.getStorageItems", 124 id, storageArea, keys 125 ); 126 127 return new Script<>( 128 Domains.Extensions, "getStorageItems", requestJSON, 129 jo -> jo.get("data"), 130 JsonValue.class 131 ); 132 } 133 134 /** 135 * Installs an unpacked extension from the filesystem similar to 136 * --load-extension CLI flags. Returns extension ID once the extension 137 * has been installed. Available if the client is connected using the 138 * --remote-debugging-pipe flag and the --enable-unsafe-extension-debugging 139 * flag is set. 140 * 141 * @param path Absolute file path. 142 * 143 * @return An instance of <CODE>{@link Script}<String></CODE> 144 * 145 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 146 * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise} 147 * <CODE><String></CODE> will be returned 148 * 149 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 150 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 151 * be retrieved.</I> 152 * 153 * <BR /><BR /><DIV CLASS=JDHint> 154 * This Browser Function's {@code Promise} returns: 155 * <CODE>String (<B>id</B>)</CODE> 156 * <BR /> 157 * Extension id. 158 * </DIV> 159 */ 160 public static Script<String> loadUnpacked(String path) 161 { 162 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 163 final String requestJSON = WriteJSON.get 164 (CDPTypes.STRING, "path", false, "Extensions.loadUnpacked", path); 165 166 return new Script<>( 167 Domains.Extensions, "loadUnpacked", requestJSON, 168 jo -> ReadJSON.getString(jo, "id", true, false), 169 String.class 170 ); 171 } 172 173 /** 174 * Removes <CODE>keys</CODE> from extension storage in the given <CODE>storageArea</CODE>. 175 * 176 * @param id ID of extension. 177 * 178 * @param storageArea StorageArea to remove data from. 179 * 180 * @param keys Keys to remove. 181 * 182 * @return An instance of <CODE>{@link Script}<Void></CODE> 183 * 184 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 185 * browser receives the invocation-request. 186 * 187 * <BR /><BR /><DIV CLASS=JDHint> 188 * This Browser-Function <I>does not have</I> a return-value. You may choose to 189 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 190 * the Browser Function has run to completion. 191 * </DIV> 192 */ 193 public static Script<Void> removeStorageItems(String id, String storageArea, String[] keys) 194 { 195 // Convert all Method Parameters into a JSON Request-Object (as a String) 196 final String requestJSON = WriteJSON.get( 197 Extensions$$Commands.removeStorageItems$$, "Extensions.removeStorageItems", 198 id, storageArea, keys 199 ); 200 201 return Script.NO_RET(Domains.Extensions, "removeStorageItems", requestJSON); 202 } 203 204 /** 205 * Sets <CODE>values</CODE> in extension storage in the given <CODE>storageArea</CODE>. The provided <CODE>values</CODE> 206 * will be merged with existing values in the storage area. 207 * 208 * @param id ID of extension. 209 * 210 * @param storageArea StorageArea to set data in. 211 * 212 * @param values Values to set. 213 * 214 * @return An instance of <CODE>{@link Script}<Void></CODE> 215 * 216 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 217 * browser receives the invocation-request. 218 * 219 * <BR /><BR /><DIV CLASS=JDHint> 220 * This Browser-Function <I>does not have</I> a return-value. You may choose to 221 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 222 * the Browser Function has run to completion. 223 * </DIV> 224 */ 225 public static Script<Void> setStorageItems(String id, String storageArea, JsonValue values) 226 { 227 // Convert all Method Parameters into a JSON Request-Object (as a String) 228 final String requestJSON = WriteJSON.get( 229 Extensions$$Commands.setStorageItems$$, "Extensions.setStorageItems", 230 id, storageArea, values 231 ); 232 233 return Script.NO_RET(Domains.Extensions, "setStorageItems", requestJSON); 234 } 235 236 /** 237 * Uninstalls an unpacked extension (others not supported) from the profile. 238 * Available if the client is connected using the --remote-debugging-pipe flag 239 * and the --enable-unsafe-extension-debugging. 240 * 241 * @param id Extension id. 242 * 243 * @return An instance of <CODE>{@link Script}<Void></CODE> 244 * 245 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 246 * browser receives the invocation-request. 247 * 248 * <BR /><BR /><DIV CLASS=JDHint> 249 * This Browser-Function <I>does not have</I> a return-value. You may choose to 250 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 251 * the Browser Function has run to completion. 252 * </DIV> 253 */ 254 public static Script<Void> uninstall(String id) 255 { 256 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 257 final String requestJSON = WriteJSON.get 258 (CDPTypes.STRING, "id", false, "Extensions.uninstall", id); 259 260 return Script.NO_RET(Domains.Extensions, "uninstall", requestJSON); 261 } 262 263 264}