1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195 | package Torello.Browser;
import static Torello.Java.C.BYELLOW;
import static Torello.Java.C.RESET;
import Torello.JSON.ReadJSON;
import Torello.JavaDoc.Annotations.LinkJavaSource;
import NeoVisionaries.WebSockets.WebSocketException;
import java.util.Objects;
import java.io.IOException;
import javax.json.JsonObject;
/**
* A Connection to a Browser, rather than an individual Page within the Browser.
*
* <BR /><BR />
* Represents a snapshot of metadata returned from Chrome’s
* <B STYLE='color:red;'>{@code /json/version}</B> End-Point. This
* includes protocol versioning, V8 details, and the root
* {@link NeoVisionaries.WebSockets.WebSocket WebSocket} {@code URL} for establishing DevTools
* sessions.
*
* <BR /><BR />
* Although this class offers a public constructor, the recommended way to build an instance is via
* the {@code static} method: <B>{@link #getBrowserConn getBrowserConn}</B>. This instance
* contains a few informational fields that were scraped from the Json-Response to the above
* mentioned Chrome response object.
*
* <BR /><BR /><B CLASS=JDDescLabel2>A {@link WebSocketSender} Instance:</B>
*
* <BR />
* To begin sending CDP commands, it is mandatory to obtain an instance of the
* <B>{@link WebSocketSender}</B> class which has been connected to a Web Browser. This instance
* should be passed as the sender to any of the available API methods offered by the Domain Classes
* in the packages
* <B><CODE><A HREF='BrowserAPI/package-summary.html'>BrowserAPI</A></CODE></B>
* and or the classes in
* <B><CODE><A HREF='JavaScriptAPI/package-summary.html'>JavaScriptAPI</A></CODE></B>.
* You should review the methods exported by each of the domains and classes within those packages,
* and note that the <B>{@link Script}</B> objects returned by them expose an
* <B>{@link Script#exec(WebSocketSender)}</B> method.
*
* <BR /><BR />
* Obtaining the <B>{@link WebSocketSender}</B> instance can be achieved by invoking
* <B>{@link BrowserConn#createSender(ConnRecord) BrowserConn.createSender}</B>,
* a method offered by this class. This method initializes a <B>{@link WebSocketSender}</B> which
* is connected to the associated <B>{@link #webSocketDebuggerUrl}</B>. That sender can be used to
* make invocations into all CDP Domains.
*
* <BR /><BR />
* The individual fields exported by this class are documented below, and within their respective
* documentation. This class, itself, is largely a structured data holder with minimal logic.
* Mostly, it parses the Json which is returned by the Web-Browser endpoint
* <B STYLE='color:red;'>{@code /json/version}</B>.
*
* <EMBED CLASS='external-html' DATA-FILE-ID=PCBC_CHECKLIST>
*/
@Torello.JavaDoc.Annotations.CSSLinks(FileNames="BrowserAndPageConn.css")
public class BrowserConn implements java.io.Serializable, Comparable<BrowserConn>, Cloneable
{
/** <EMBED CLASS=external-html DATA-FILE-ID=SVUID> */
protected static final long serialVersionUID = 1;
// ********************************************************************************************
// ********************************************************************************************
// PUBLIC FIELDS
// ********************************************************************************************
// ********************************************************************************************
/** <EMBED CLASS='external-html' DATA-FILE-ID=BC_BROWSER> */
public final String browser;
/** <EMBED CLASS='external-html' DATA-FILE-ID=BC_PROT_VER> */
public final String protocolVersion;
/** <EMBED CLASS='external-html' DATA-FILE-ID=BC_USER_AGENT> */
public final String userAgent;
/** <EMBED CLASS='external-html' DATA-FILE-ID=BC_V8_VERSION> */
public final String v8Version;
/** <EMBED CLASS='external-html' DATA-FILE-ID=BC_WEBKIT_VER> */
public final String webkitVersion;
/** <EMBED CLASS='external-html' DATA-FILE-ID=BC_WS_DEBUG_URL> */
public final String webSocketDebuggerUrl;
// ********************************************************************************************
// ********************************************************************************************
// Constructors
// ********************************************************************************************
// ********************************************************************************************
/**
* Constructs an instance of this type.
* @throws NullPointerException if {@code 'webSocketDebuggerUrl'} is passed null.
*/
public BrowserConn(
final String browser,
final String protocolVersion,
final String userAgent,
final String v8Version,
final String webkitVersion,
final String webSocketDebuggerUrl
)
{
Objects.requireNonNull(webSocketDebuggerUrl, "webSocketDebuggerUrl is null");
this.browser = browser;
this.protocolVersion = protocolVersion;
this.userAgent = userAgent;
this.v8Version = v8Version;
this.webkitVersion = webkitVersion;
this.webSocketDebuggerUrl = webSocketDebuggerUrl;
}
/**
* <EMBED CLASS='external-html' DATA-FILE-ID=PAGE_CONN>
*
* @param jo The exact {@link JsonObject} that was generated by querying the HTTP End-Point
* <B STYLE='color:red;'>{@code /json/version}</B>.
*
* @see ReadJSON#getString(JsonObject, String, boolean, boolean)
*/
public BrowserConn(final JsonObject jo)
{
this.browser = ReadJSON.getString(jo, "Browser", false, true);
this.protocolVersion = ReadJSON.getString(jo, "Protocol-Version", false, true);
this.userAgent = ReadJSON.getString(jo, "User-Agent", false, true);
this.v8Version = ReadJSON.getString(jo, "V8-Version", true, false);
this.webkitVersion = ReadJSON.getString(jo, "WebKit-Version", true, false);
this.webSocketDebuggerUrl =
ReadJSON.getString(jo, "webSocketDebuggerUrl", false, true);
}
// ********************************************************************************************
// ********************************************************************************************
// Build Methods
// ********************************************************************************************
// ********************************************************************************************
/**
* Creates a {@link WebSocketSender} connected to the {@link #webSocketDebuggerUrl} for this
* tab. This URL is the endpoint that speaks the Chrome DevTools Protocol (CDP).
*
* @param connRec Messaging settings for this connection
*/
public WebSocketSender createSender(final ConnRecord connRec)
throws IOException, WebSocketException
{ return new WebSocketSender(this.webSocketDebuggerUrl, connRec); }
/**
* Retrieves the WebSocketDebugger URL for the main browser instance.
* This queries {@code /json/version} and parses the result into an instance.
*
* @param port The DevTools port Chrome is listening on (default is 9222 if {@code null}).
* @param quiet If {@code false}, debug output is printed to the console.
* @return A {@code BrowserConn} instance representing the browser-level connection.
*/
@LinkJavaSource(handle="BCBuilder")
public static BrowserConn getBrowserConn(Integer port, boolean quiet)
{ return BCBuilder.getBrowserConn(port, quiet); }
// ********************************************************************************************
// ********************************************************************************************
// java.lang.Object Methods
// ********************************************************************************************
// ********************************************************************************************
@LinkJavaSource(handle="BCHelper", name="toString")
public String toString() { return BCHelper.toString(this); }
@LinkJavaSource(handle="BCHelper", name="hashCode")
public int hashCode() { return BCHelper.hashCode(this); }
@LinkJavaSource(handle="BCHelper", name="equals")
public boolean equals(Object o) { return BCHelper.equals(this, o); }
@LinkJavaSource(handle="BCHelper", name="clone")
public BrowserConn clone() { return BCHelper.clone(this); }
public int compareTo(BrowserConn other)
{ return this.webSocketDebuggerUrl.compareTo(other.webSocketDebuggerUrl); }
}
|