java.lang.Object
- Torello.Browser.BrowserAPI.PWA

```
public class PWA
extends java.lang.Object
```
This class was built using the Chrome Remote Dev-Tools A.P.I., which is specified by two JSON-RPC Files. These files were obtained from the Chrome Dev Tools Protocol Git Hub Page, which has a "Tip of Tree" (the latest) API-Specification Page Here: JSON-RPC Protocol Specification.

These files were converted into this Java-Browser (CDP) Library. The intention is to have them function in a similar fasion to the Node.js Tool known as 'Puppeteer', Microsoft's 'Playwright' and of course the Main-Stay 'Selenium.' The Java-HTML JAR Library merely implements the Java Types & Commands defined by Google's DevTools Protocol.

🧠 View the Google CDP API:
- browser_protocol.json
- js_protocol.json
- Browser API HTML-Page
- Java-Script API HTML-Page
This domain allows interacting with the browser to control PWAs.

The top-level description and explanation for this class (this comment, at the top this Java-Doc Page) is repeated, verbatim, across all of the domain classes which comprise Google's CDP API.
This class is intended to be used with a Browser Instance
These methods have been tested, to some degree, using Google Chrome. In order to use this class you must start a web-browser instance and make a connection to the browser using a Remote Debugging Port. Google-Corporation is the developer of this API, but any browser which accepts a Remote Debug Port Connection over Web-Sockets.

Google-Chrome was used during the development process of the classes in this particular package. Lately, it has been asserted Microsoft has switched to using the Chrome Browser-Engine for its Microsoft Edge Internal Code-Base. Therefore, there may some functionality available when running the methods in this class with Microsoft-Edge.

Check whether the your Web-Browser will allow itself to be driven by the Web-Socket RDP-Port 9223. See the examples available in package Torello.Browser to undertand how to build a PageConn and BrowserConn Web-Socket Connection, and how to build a WebSocketSender instance in order to execute the methods in this class.

Web-Socket & JSON API:
Every one of the methods that reside in this class are designed to do nothing more than:
1. Accept Parameters from the User, and "Marshall Them" into a Valid JSON-Request
2. Transmit the Marshalled Request-JSON to a Headless Web-Browser over a Web-Socket Connection
3. Receive BOTH that Command-Results AND any Browser Event-Firings from the Web-Socket
4. Parse JSON Method-Results and Browser-Event Firings, and Subsequently Convert them to Standard Java-Types
5. Report these Method-Results and Browser-Events to the User via a User-Registered, Event-Listener (Events) or a Promise Object (Command Responses / Results)
Unlike the bulk of the Java HTML JAR Library, there is very little native Java-Code, and very little testing that may be done on any of the classes & methods in this package. The code inside these classes does nothing more than marshall-and-unmarshall Java-Types into Json-Requests (and vice-versa). The Java-Script & Browser modules inside of a Google-Chrome instance are, theoretically, handling these requests, and returning their results (or events) over the Web-Socket Connection.

It has been asserted (by Google Chrome Developers) that some of these methods are only "partially working" or "experimental".

Asking Chat-GPT for Help:
The LLM otherwise known as "Chat-GPT" does, indeed, have an expert level of knowledge about the "Remote DevTools Protocol". The API that the Chrome DevTools Protocl (CDP) exports is extremely well understood by the LLM, and generally I have found that Chat-GPT understands (by 2 or 3 orders of magnitude) better what my Auto-Generated JSON-Wrappers can do in controlling a Web-Browser than I could ever possibly hope to understand.

Though not available today, there will soon be an automatically downloadable Token-Stream (AI Embeddings) BUTTON available on my Java-Doc Pages that should hopefully make it extremely easy to post my code-base, RAG Style, to Chat-GPT and other LLM's when 'interogating' them. Presently, because my "Get Token Stream Button" does not exist yet on any of my pages, what you can do is copy-and-paste any Method-Signature from any one of these pages and then ask Chat-GPT to explain what that Browser or Java-Script Function is actually doing. It is very likely to give you some pretty neat answers.

I have found that every single one of the Domains, Types & Events which are offered by the CDP Protocol (though not documented very well by Google), are perfectly understood by the A.I. LLM - literally to the point where it does know (much better than I ever could) what my own code base actually does!

Try it out, it's a lot of fun. Note that this package and these classes were originally developed solely to be able to execute the Java-Script that a browser executes when visiting a Web-Site. Complete HTML-Page Content can be scraped (using the HTML Data-Scraping Tools in Java-HTML) off of Web-Sites that have dynamic / Java-Script Generated Content.

Conspicuous Boxed-Types Usage:
You may notice that there are many methods that have parameters which accept, for instance, an Integer, instead of a primitive int. Just to remind the readiner, in Java Programs a Boxed Type is a standard Java-Primitive which has been converted into an Object-Reference. The use of Boxed-Types in this code base is an easy-and-fast-way to allow for the concept of "Optional Parameters" or "Optional Field Value."

Whenever you see a method that accepts an Integer, the reason for this Parameter-Type choice is actually to allow a user to pass 'null' to it. This is a simple way to ELIDE passing any value at all to parameters which Google-Chrome would otherwise assert are "Optional." Whenever you pass 'null' to a Boxed-Types in this class, the Json-Processor will simply eliminate that Object-Property from the command altogether; and the browser will simply not receive any value for that parameter when that command is invoked.

The Java Language Specification does not have an easy or well defined means of accepting optional method parameters; so Boxed-Types and 'null' are utilized here. Note that 'null' may be passed to any Command Method-Parameter that is listed as Optional on the Java-Doc Page description for that parameter.
Hi-Lited Source-Code:
This File's Source Code:
- View Here: Torello/Browser/BrowserAPI/PWA.java
- Open New Browser-Tab: Torello/Browser/BrowserAPI/PWA.java
File Size: 21,382 Bytes Line Count: 520 '\n' Characters Found
Helper: Command Invocation Helpers
- View Here: PWA$$Commands.java
- Open New Browser-Tab: PWA$$Commands.java
File Size: 3,579 Bytes Line Count: 85 '\n' Characters Found
Stateless Class:
This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.
- 1 Constructor(s), 1 declared private, zero-argument constructor
- 7 Method(s), 7 declared static
- 1 Field(s), 1 declared static, 1 declared final

Nested Class Summary

Type Nested Classes: Types / Classes that Are Used & Exported by this Domain

Modifier and Type	Class	Description
`static class`	`PWA.FileHandler`	`[No Description Provided by Google]`
`static class`	`PWA.FileHandlerAccept`	The following types are the replica of https://crsrc.org/c/chrome/browser/web_applications/proto/web_app_os_integration_state.proto;drc=9910d3be894c8f142c977ba1023f30a656bc13fc;l=67

Command-Returns Nested Classes: Domain-Commands with Multiple Return-Values, and a Dedicated Inner-Class
Modifier and Type	Class	Description
`static class`	`PWA.getOsAppState$$RET`	Returns the following OS state for the given manifest id.

Field Summary

Enumerated Strings: Like Java 'enum' Types, but Converted to Read-Only String-Lists

Modifier and Type	Field	Description
`static ReadOnlyList<String>`	`DisplayMode`	If user prefers opening the app in browser or an app window.

Method Summary

PWA Domain Commands

Script Returns	Modifier and Type	Method
`Void`	`static Script<>`	`changeAppUserSettings(String manifestId, Boolean linkCapturing, String displayMode)` Changes user settings of the web app identified by its manifestId.
`PWA.getOsAppState$$RET`	`static Script<>`	`getOsAppState(String manifestId)` Returns the following OS state for the given manifest id.
`Void`	`static Script<>`	`install(String manifestId, String installUrlOrBundleUrl)` Installs the given manifest identity, optionally using the given installUrlOrBundleUrl IWA-specific install description: manifestId corresponds to isolated-app:// + web_package::SignedWebBundleId File installation mode: The installUrlOrBundleUrl can be either file:// or http(s):// pointing to a signed web bundle (.swbn).
`String`	`static Script<>`	`launch(String manifestId, String url)` Launches the installed web app, or an url in the same web app instead of the default start url if it is provided.
`String[]`	`static Script<>`	`launchFilesInApp(String manifestId, String[] files)` Opens one or more local files from an installed web app identified by its manifestId.
`Void`	`static Script<>`	`openCurrentPageInApp(String manifestId)` Opens the current page in its web app identified by the manifest id, needs to be called on a page target.
`Void`	`static Script<>`	`uninstall(String manifestId)` Uninstalls the given manifest_id and closes any opened app windows.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DisplayMode
    
    🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static final ReadOnlyList<java.lang.String> DisplayMode
    
    If user prefers opening the app in browser or an app window.
    
    String-Enumeration Type
- Method Detail
  - changeAppUserSettings
    
    🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<java.lang.Void> changeAppUserSettings (java.lang.String manifestId, java.lang.Boolean linkCapturing, java.lang.String displayMode)
    
    Changes user settings of the web app identified by its manifestId. If the app was not installed, this command returns an error. Unset parameters will be ignored; unrecognized values will cause an error. Unlike the ones defined in the manifest files of the web apps, these settings are provided by the browser and controlled by the users, they impact the way the browser handling the web apps. See the comment of each parameter.
    
    Parameters:
    
    manifestId - -
    
    linkCapturing - If user allows the links clicked on by the user in the app's scope, or extended scope if the manifest has scope extensions and the flags DesktopPWAsLinkCapturingWithScopeExtensions and WebAppEnableScopeExtensions are enabled. Note, the API does not support resetting the linkCapturing to the initial value, uninstalling and installing the web app again will reset it. TODO(crbug.com/339453269): Setting this value on ChromeOS is not supported yet.
    OPTIONAL
    
    displayMode - -
    OPTIONAL
    
    Returns:
    
    An instance of Script<Void>
    
    This Script instance must be executed before the browser receives the invocation-request.
    
    This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.
  - getOsAppState
    
    🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<PWA.getOsAppState$$RET> getOsAppState (java.lang.String manifestId)
    
    Returns the following OS state for the given manifest id.
    
    Parameters:
    
    manifestId - The id from the webapp's manifest file, commonly it's the url of the site installing the webapp. See https://web.dev/learn/pwa/web-app-manifest.
    
    Returns:
    
    An instance of Script<PWA.getOsAppState$$RET>
    
    This script may be executed, using Script.exec, and afterwards, a Promise <PWA.getOsAppState$$RET> will be returned
    
    Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.
    
    This Browser Function's Promise returns:PWA.getOsAppState$$RET A dedicated return type implies that the browser may return more than 1 datum
  - install
    
    🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<java.lang.Void> install (java.lang.String manifestId, java.lang.String installUrlOrBundleUrl)
    
    Installs the given manifest identity, optionally using the given installUrlOrBundleUrl IWA-specific install description: manifestId corresponds to isolated-app:// + web_package::SignedWebBundleId File installation mode: The installUrlOrBundleUrl can be either file:// or http(s):// pointing to a signed web bundle (.swbn). In this case SignedWebBundleId must correspond to The .swbn file's signing key. Dev proxy installation mode: installUrlOrBundleUrl must be http(s):// that serves dev mode IWA. web_package::SignedWebBundleId must be of type dev proxy. The advantage of dev proxy mode is that all changes to IWA automatically will be reflected in the running app without reinstallation. To generate bundle id for proxy mode: 1. Generate 32 random bytes. 2. Add a specific suffix 0x00 at the end. 3. Encode the entire sequence using Base32 without padding. If Chrome is not in IWA dev mode, the installation will fail, regardless of the state of the allowlist.
    
    Parameters:
    
    manifestId - -
    
    installUrlOrBundleUrl - The location of the app or bundle overriding the one derived from the manifestId.
    OPTIONAL
    
    Returns:
    
    An instance of Script<Void>
    
    This Script instance must be executed before the browser receives the invocation-request.
    
    This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.
  - launch
    
    🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<java.lang.String> launch(java.lang.String manifestId, java.lang.String url)
    
    Launches the installed web app, or an url in the same web app instead of the default start url if it is provided. Returns a page Target.TargetID which can be used to attach to via Target.attachToTarget or similar APIs.
    
    Parameters:
    
    manifestId - -
    
    url - -
    OPTIONAL
    
    Returns:
    
    An instance of Script<String>
    
    This script may be executed, using Script.exec, and afterwards, a Promise <String> will be returned
    
    Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.
    
    This Browser Function's Promise returns: String (targetId)
    ID of the tab target created as a result.
  - launchFilesInApp
    
    🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<java.lang.String[]> launchFilesInApp (java.lang.String manifestId, java.lang.String[] files)
    
    Opens one or more local files from an installed web app identified by its manifestId. The web app needs to have file handlers registered to process the files. The API returns one or more page Target.TargetIDs which can be used to attach to via Target.attachToTarget or similar APIs. If some files in the parameters cannot be handled by the web app, they will be ignored. If none of the files can be handled, this API returns an error. If no files are provided as the parameter, this API also returns an error. According to the definition of the file handlers in the manifest file, one Target.TargetID may represent a page handling one or more files. The order of the returned Target.TargetIDs is not guaranteed. TODO(crbug.com/339454034): Check the existences of the input files.
    
    Parameters:
    
    manifestId - -
    
    files - -
    
    Returns:
    
    An instance of Script<String[]>
    
    This script may be executed, using Script.exec, and afterwards, a Promise <String[]> will be returned
    
    Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.
    
    This Browser Function's Promise returns: String[] (targetIds)
    IDs of the tab targets created as the result.
  - openCurrentPageInApp
    
    🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<java.lang.Void> openCurrentPageInApp (java.lang.String manifestId)
    
    Opens the current page in its web app identified by the manifest id, needs to be called on a page target. This function returns immediately without waiting for the app to finish loading.
    
    Parameters:
    
    manifestId - -
    
    Returns:
    
    An instance of Script<Void>
    
    This Script instance must be executed before the browser receives the invocation-request.
    
    This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.
  - uninstall
    
    🡅 ⇈ ⮫ 🗕 🗗 🗖
    public static Script<java.lang.Void> uninstall (java.lang.String manifestId)
    
    Uninstalls the given manifest_id and closes any opened app windows.
    
    Parameters:
    
    manifestId - -
    
    Returns:
    
    An instance of Script<Void>
    
    This Script instance must be executed before the browser receives the invocation-request.
    
    This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

Fields
ReadOnlyList	DisplayMode
Methods
Script	changeAppUserSettings(String manifestId, Boolean linkCapturing, String displayMode)
Script	getOsAppState(String manifestId)
Script	install(String manifestId, String installUrlOrBundleUrl)
Script	launch(String manifestId, String url)
Script	launchFilesInApp(String manifestId, String[] files)
Script	openCurrentPageInApp(String manifestId)
Script	uninstall(String manifestId)

Class PWA

This class is intended to be used with a Browser Instance

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DisplayMode

Method Detail

changeAppUserSettings

getOsAppState

install

launch

launchFilesInApp

openCurrentPageInApp

uninstall