Request
com.jsmacrosce.jsmacros.core.library.impl.FRequest
Sends HTTP requests and creates WebSocket handlers through the Request script library.
An instance of this class is passed to scripts as the Request variable.
The get(String) and post(String, String) methods send one-call requests;
create(String) returns a configurable HTTP request handler, and createWS(String) creates a WebSocket handler that connects only when asked.
HTTP calls block until a response or connection failure; HTTP error status codes are responses,
not connection failures. Response text is cached after its first read.
js
// the quick form: one call, one response
const response = Request.get("https://example.com/api/status");
print(`status ${response.responseCode}: ${response.text()}`);
// the builder form is for anything the quick form does not cover
const request = Request.create("https://example.com/api/echo")
.addHeader("User-Agent", "JsMacrosCE")
.setConnectTimeout(5000)
.setReadTimeout(5000);
print(`posted, status ${request.post("hello").responseCode}`);
// the quick forms take headers as a java Map rather than as a script object,
// so the map has to be built through JavaUtils
const headers = JavaUtils.createHashMap();
headers.put("Accept", "application/json");
print(`with headers, status ${Request.post("https://example.com/api/echo", "hello", headers).responseCode}`);
// a websocket installs its handlers by writing to public fields, then connects
const socket = Request.createWS("wss://example.com/socket");
socket.onTextMessage = JavaWrapper.methodToJava(function (ws, text) {
print(`from the socket: ${text}`);
});
socket.connect();Accessible in scripts via the global Request variable.
Methods
create
Creates a configurable HTTP request handler for the URL. The request is not sent until a send method is called.
Parameters:
url: the request URL
Returns: a handler for configuring and sending requests to the URL
createWS
Creates a WebSocket handler without connecting it. Callbacks are read when their events occur, so assign them before the events they should handle. The client invokes each callback wrapper for its event; script execution and whether the invocation waits depend on the wrapper's scheduling mode. Calling Websocket.connect() performs the handshake on that call's thread.
const socket = Request.createWS("wss://example.com/socket");
// the handlers are public fields, so they are installed by assignment
socket.onTextMessage = JavaWrapper.methodToJava(function (ws, text) {
print(`received: ${text}`);
ws.sendText(`echo: ${text}`);
});
socket.onError = JavaWrapper.methodToJava(function (ws, error) {
print(`the socket failed: ${error}`);
});
// and connecting is a separate step
socket.connect();
// later
socket.close();Parameters:
url: the websocket address to open
Returns: a handler that has not yet connected
See:
get
Sends a GET request without custom headers. The call blocks until a response or connection failure.
Parameters:
url: the request URL
Returns: the response
Sends a GET request to the URL. The headers are a Java Map, not a script object, so they have to be built through
JavaUtils.createHashMap() rather than written as an object literal. The map is copied, so changing it afterwards does not change the request. Passing null for it is the same as using the no header form. The call blocks until the server answers or the connection fails, and a failed connection is an IOException rather than a response with a bad status. A response that came back with an error status is not a failure here, it is a response with a responseCode to check. // headers are a java Map, so they are built through JavaUtils rather than
// written as a script object
const headers = JavaUtils.createHashMap();
headers.put("Accept", "application/json");
headers.put("User-Agent", "JsMacrosCE");
const response = Request.get("https://example.com/api/status", headers);
if (response.responseCode === 200) {
print(response.text());
} else {
print(`the server said ${response.responseCode}`);
}
// an unreachable host is an exception, not a bad status
try {
Request.get("https://not-a-real-host.invalid/");
} catch (error) {
print(`that one did not get that far: ${error}`);
}Parameters:
url: the URL to send the request toheaders: the request headers as a java Map, ornullfor none
Returns: the response, including its status code
See:
post
Sends a POST request without custom headers. The call blocks until a response or connection failure.
Parameters:
url: the request URLdata: the request body
Returns: the response
Sends a POST request to the URL. The headers are a Java Map rather than a script object, the same as on the GET form, and the data is sent as the request body with no content type set for it, so an endpoint that needs one wants the builder form and its
addHeader. The call blocks until the server answers, and a connection failure is an IOException. // the body is the second argument, and the headers are a java Map
const headers = JavaUtils.createHashMap();
headers.put("Content-Type", "text/plain");
const response = Request.post("https://example.com/api/echo", "hello", headers);
print(`status ${response.responseCode}, echoed back as ${response.text()}`);Parameters:
url: the URL to send the request todata: the request bodyheaders: the request headers as a java Map, ornullfor none
Returns: the response, including its status code