RequestBuilder, JSON & XML

RequestBuilder lives in com.google.gwt.http.client. The module com.google.gwt.http.HTTP is inherited by com.google.gwt.user.User, so a normal application already has it; a library module that only inherits com.google.gwt.core.Core must inherit it explicitly.

Source: GWT Developer Guide — Server communication: Making HTTP requests

The Bookshelf catalogue is published by a servlet as JSON at /api/books?start=0&length=2. This is the complete request, with the response read in the callback.

Measured output of the callback:

Source: GWT Developer Guide — Server communication: Making HTTP requests

Three things in that example are easy to get wrong, and the rest of this section is about them.

GET, POST, PUT, DELETE and HEAD are constants of RequestBuilder. The release notes of 2.0.1 list the fix "RequestBuilder restricted to GET and POST", so the older statement that only those two work is obsolete. For a method without a constant, such as PATCH, the class has a second constructor that takes the method as a String, but it is protected: write a small subclass of RequestBuilder and call super("PATCH", url). The 2.13.1 source documents the constructor but the Developer Guide does not mention it, and the lab did not exercise it, so check your server’s handling of the method in a test before relying on it.

Pass the request body to sendRequest(String requestData, RequestCallback callback), or call setRequestData(String) and setCallback(RequestCallback) and then send(); sendRequest does not remember the data or callback it was given, while send() uses the stored ones. A body is a String: serialise JSON or XML yourself, and see below for the encoders.

RequestBuilder takes a URL that is already encoded. The URL class has the encoders: URL.encode(String) for a whole URL (it leaves the reserved characters of URL syntax alone), URL.encodeQueryString(String) for the value of a query parameter, and URL.encodePathSegment(String) for a path segment. UrlBuilder assembles a URL from parts and encodes each one.

Concatenating user input into a URL without encoding it is the client-side half of query injection (an & in the author name adds a parameter). The server must still validate every parameter, because anyone can send any URL to it without your client.

Source: GWT Developer Guide — Server communication: Making HTTP requests

setHeader(name, value) sets one request header and replaces an earlier value of the same name; both arguments must be non-empty. There is one trap in the source of setHeaders: if you set no header at all, GWT adds Content-Type: text/plain; charset=utf-8; if you set at least one header, it adds nothing, and the browser chooses the content type from the body, which for a String is text/plain;charset=UTF-8. So a POST with a JSON body needs Content-Type: application/json set explicitly the moment you add any other header, such as a CSRF token. The lab made this visible: with only the token header set, the Bookshelf servlet, which insists on JSON, answered 415 and said what it had seen (full listing in the CSRF section below).

The browser keeps some headers for itself (the "forbidden request-header" list of the Fetch standard: Host, Content-Length, Cookie, Origin and others), so do not expect setHeader to control them. Custom headers on a cross-origin request turn it into a preflighted request, as measured in the CORS section.

setTimeoutMillis(int) sets a timer; 0 (the default) means no timeout, and a negative value throws IllegalArgumentException("Timeouts cannot be negative"). When the timer fires, GWT aborts the XMLHttpRequest and calls onError with a RequestTimeoutException, whose message and getters are:

(The lab asked the server to wait 1500 ms with a 300 ms timeout.) The request is aborted in the browser, but the server may keep working on it; a non-idempotent request that timed out may still have been applied, so do not blindly repeat it. RequestTimeoutException.getRequest() and getTimeoutMillis() give the details.

The lab asked for a 404 and a 500. Both arrived in onResponseReceived:

Notice the second line: the error body of a servlet container is HTML, not your JSON. Check getStatusCode() (and ideally the Content-Type) before parsing, as the wrapper in the worked example does. Response has SC_* constants for the usual codes, so write Response.SC_OK rather than 200, and remember that success is the whole 2xx range (a 201 Created or 204 No Content is not SC_OK).

When the browser produces no HTTP response at all (the server is down, DNS fails, the connection is reset, or a cross-origin request is blocked), the XMLHttpRequest still reaches its DONE state with status 0 and an empty statusText. GWT delivers that to onResponseReceived, not to onError, with an empty body. This is the single most surprising behaviour of the class, and the Developer Guide’s comment in the sample (the onError branch is "could be timeout, SOP violation, etc.") does not match it. Measured with a request to another origin that sends no CORS headers:

So the success test in a real application is "status in 200..299", and status 0 is a distinct, user-visible case: "cannot reach the server or the request was blocked". The browser console says which, but the page cannot read it: for security reasons JavaScript is deliberately not told why a cross-origin request failed.

sendRequest can throw instead of calling back. RequestException covers failures to start; the subclass RequestPermissionException is thrown when XMLHttpRequest.open itself fails, which is what a URL that the browser cannot parse does:

The message mentions the same-origin policy because GWT cannot tell the cases apart. Handle both channels: a catch around sendRequest and the two callback methods.

sendRequest returns a Request. isPending() is true while the browser is working on it; cancel() clears the state-change handler, aborts the XMLHttpRequest and stops the timeout timer, without calling either callback. Use it when the user navigates away from the screen that asked, or to drop a stale search. Measured: the lab started a request that the server would answer after 500 ms, cancelled it, and waited 900 ms.

The server may still process a cancelled request, so cancelling is a client-side courtesy and not a way to undo a state-changing call.

setUser(String) and setPassword(String) pass HTTP basic credentials to XMLHttpRequest.open; putting a password in client code means every visitor can read it, so they are only useful with credentials typed by the user at run time. Cookies of the same origin are always sent. For a cross-origin request, setIncludeCredentials(true) sets withCredentials so that the browser also sends cookies and accepts Set-Cookie; it needs the server’s Access-Control-Allow-Credentials: true and a specific (not *) Access-Control-Allow-Origin. (The 2.5.1 release notes call this method withCredentials(); the method in 2.13.1 is setIncludeCredentials.)

The same-origin policy blocks a script from reading a response from another scheme, host or port. CORS (Cross-Origin Resource Sharing) is the opt-in: the server answers with Access-Control-Allow-Origin, and for requests that are not "simple" the browser first sends an OPTIONS preflight. Nothing in RequestBuilder is CORS-specific, because the browser does all of it. The lab ran three cross-origin calls from the page on port 8933 to a server on port 8943:

CORS is configured on the server (see CORS for the headers, and REST APIs with Spring Boot for the Spring side). Never answer Access-Control-Allow-Origin: * together with credentials, and never reflect the request’s Origin header without checking it against a list. Two simpler designs avoid CORS altogether: serve the API from the same origin as the page (a reverse proxy in front of both), or call your own server, which fetches the remote data (the "proxy on your own server" of the Cross-site Requests tutorial).

Source: MDN — Cross-Origin Resource Sharing (CORS)

Most applications wrap RequestBuilder once, so that callers see one AsyncCallback like the one GWT-RPC uses and never touch status codes. This is the Bookshelf wrapper; it keeps the "status 0" case distinct and lets parse errors reach the same onFailure.

Measured with Parser being text -> (BookPageDto) NativeJson.parse(text):

The callback.onSuccess call is outside the try on purpose: an exception thrown by the caller’s success code must not be reported as a parse failure. Exceptions that escape a callback are not caught by RequestBuilder: the browser event handler is wrapped with GWT’s $entry (visible in the XMLHttpRequest source), so they reach the handler installed with GWT.setUncaughtExceptionHandler.

Source: GWT Developer Guide — Server communication: Making HTTP requests

com.google.gwt.core.client.JsonUtils is a class of static helpers.

The Developer Guide (and, copied from it, much third-party material) describes safeEval as "evaluates a JSON expression" with the comment "JSON String that you trust", which suggests eval. In the 2.13.1 source it is JSON.parse inside a try, which is the safe choice; the stale wording is repeated as an outdated item at the end.

com.google.gwt.json.client.JSONParser produces a tree of JSONValue objects: JSONObject, JSONArray, JSONString, JSONNumber, JSONBoolean and JSONNull. Each JSONValue has isObject(), isArray(), isString(), isNumber(), isBoolean() and isNull(), which return the typed view or null when the value is of another kind, so a chain of them is also your validation.

null input throws NullPointerException, an empty string IllegalArgumentException("empty argument"), and bad syntax a JSONException whose message starts with Error parsing JSON: (the lab lines are in the pitfalls table).

JSONNumber holds a double, as JavaScript does: a 64-bit integer above 2^53 loses precision, and a database bigint key should travel as a JSON string. JSONObject.get(key) returns null for an absent key; calling a method on it throws NullPointerException, so the chain above is only safe for a payload whose shape you have validated.

The real cost of the tree is not speed but code: every field access is a method call, a null test and an unboxing. It pays when the structure varies (a generic viewer, a debugging tool), and in a pinch for one or two fields of a payload you otherwise ignore.

Source: Javadoc — JSONParser

An overlay type is a Java class that extends JavaScriptObject and whose methods are JSNI one-liners reading properties of the JavaScript object underneath. It is what the Retrieving JSON tutorial teaches, and the JSNI & Overlay Types page describes the rules in detail: a protected no-argument constructor, final methods, no instance fields.

The compiler turns the getters into direct property reads (the overlay’s methods can be inlined, as the tutorial notes), so there is no per-object copy and no parser in the output beyond JSON.parse. JsArray<T>, JsArrayString, JsArrayInteger, JsArrayNumber and JsArrayBoolean wrap arrays. The drawbacks are the reason the tutorials' style is now legacy: it relies on JSNI, which the JsInterop page replaces; it is a GWT-only mechanism rather than part of the portable JsInterop specification; and nothing checks that the JSON really has a title.

Source: GWT Tutorial — Retrieving JSON: Manipulating JSON data in the client-side code

In new code, bind the JSON shape with a native JsInterop type. A native type has no implementation in Java: the compiler emits plain property accesses, so a DTO costs nothing at run time, and the JSON object itself is bound the same way.

Elemental2 ships the same binding (elemental2.core.Global.JSON, covered with fetch on the DOM & Elemental2 page), so a project that already depends on it can write Global.JSON.parse(text) and skip the hand-written NativeJson. Writing the three-line binding avoids a dependency for one function.

Three properties of this approach decide how you use it.

Source: GWT Developer Guide — JavaScript: JsInterop (the JsInterop page of this section explains native types)

When you want ordinary Java beans (getters and setters, List properties, no JavaScript types), the AutoBean framework generates the implementation and AutoBeanCodex converts to and from a JSON payload. It is the JSON layer that RequestFactory is built on, and it also runs on a plain JVM, so the same interfaces can be unit-tested on the server side. The RequestFactory & AutoBeans page covers the framework itself; here is its codec used on a RequestBuilder response.

The module is com.google.web.bindery.autobean.AutoBean; the factory is created with GWT.create on the client and AutoBeanFactorySource.create on a JVM (which needs gwt-user and gwt-dev on the class path). @AutoBean.PropertyName("book_title") maps a JSON name that is not a Java identifier, and it is asymmetric: put it on the getter and on the setter. Probed on a JVM with a bean that had it only on the getter, encode and decode worked but calling the unannotated setter threw java.lang.IllegalArgumentException: jsonTitle; with both annotated the payload was {"book_title":"X","id":"42"}. The same probe showed how the decoder treats an imperfect payload: a JSON property that is not in the interface is ignored, a missing int becomes 0, a missing List becomes null, and a long is accepted as a number ("id":42) or as a string ("id":"12345678901234567"). A syntactically invalid payload threw java.lang.RuntimeException: Could not parse payload on the JVM; the client-side message was not probed.

Look at the second output line: AutoBeanCodex encoded the long id as the string "99" (the 2.13.1 ValueCodex writes Long as a string and reads either a number or a string), and int as a number. That protects 64-bit ids from the double precision loss, and it is a contract detail your non-GWT server must honour; if the server sends and expects numbers, use int, double or String in the interface instead. Date is written as the millisecond value, as a string.

Source: GWT Developer Guide — AutoBeans

Build the body with a JSON encoder, never by string concatenation: a title containing a quote or a backslash breaks the document, and a title containing ","admin":true,"x":" changes its meaning.

Send it with an explicit Content-Type: application/json; charset=utf-8 (see Headers above, and the CSRF example below), and have the server reject other types, which is also a CSRF defence.

Source: GWT Developer Guide — Working with JSON

com.google.gwt.jsonp.client.JsonpRequestBuilder (module com.google.gwt.jsonp.Jsonp) hides the bookkeeping that the 2009 article spends most of its length on: unique callback names, the global registry, script tags that must be removed again. In the lab module JsonpRequestBuilder resolved even without an explicit <inherits> (the ClientBundle Resources module inherits Jsonp for external resources), but do not rely on that; inherit com.google.gwt.jsonp.Jsonp where you use it.

The parameters are annotated @IsTrustedResourceUri, so the SafeHtml checks described on the SafeHtml & XSS page flag a URL that was built from user input. JsonpRequest.cancel() removes a pending request (not with preset ids). Measured, with a servlet on the same origin and a plain Java server on another port:

Source: GWT Tutorial — Cross-site Requests: Request the data from the remote server

The server must wrap the JSON in a call to a function whose name comes from the request. That name is attacker-controlled text that you write into a script, so it is a code-injection point. The lab servlet accepts only a dotted identifier, prefixes the body with /**/ (a common hardening against content-sniffing abuse of JSONP endpoints), and sets X-Content-Type-Options: nosniff.

The Cross-site Requests tutorial’s PHP script does echo $callback; for the unchecked callback parameter, and the Retrieving JSON tutorial’s servlet prints the stock symbols into the JSON without escaping them. Both are useful for learning the mechanism and are injection holes in production: do not copy them.

When the request is rejected, the client is not told why. A <script> whose load fails fires no usable error to GWT, so a JSONP failure shows up as the timeout (the lab asked for a callback name the servlet refuses, with an 800 ms timeout):

Pass setFailureCallbackParam if the service supports an error callback, and always set a short setTimeout (the default is ten seconds).

Source: GWT Tutorial — Cross-site Requests: Request the data from the remote server

The security consequences follow from the first line of "trust":

New code should prefer CORS, or a same-origin API behind a reverse proxy, and JSONP should survive only for services that offer nothing else.

Source: GWT — Security for GWT Applications: JSON and XSRF

XMLParser.parse is documented to throw when the text is not well-formed, and the Developer Guide’s example wraps it in catch (DOMException e). In the 2.13.1 source the browser implementation (XMLParserImplStandard) calls DOMParser.parseFromString and raises an error only when the root element is a parsererror in the Mozilla namespace. Chrome reports a parse failure by returning a document that contains an XHTML-namespaced parsererror element, so the check does not fire. Measured with <catalog><book></catalog>:

So after XMLParser.parse on text that did not come from your own validated code, test for the error element yourself.

(Keep the catch (DOMException) too: other implementations and some inputs do throw.)

Source: GWT Developer Guide — Working with XML: Parsing XML

XMLParser.createDocument() gives an empty Document; build it with createElement, createTextNode and setAttribute, attach with appendChild, and serialise with toString(). The serialiser escapes the markup characters, which is the reason to build XML with the DOM and not with string concatenation.

Source: GWT — Developer Guide: Working with XML

The browser’s DOMParser does not fetch external entities or DTDs for the page’s benefit, so the client side has no XXE exposure comparable to a server-side parser; the server that consumes the XML your client posts still needs a hardened parser. The client-side risk is the same as for JSON: the values you read are untrusted text. Show them with setText or a Label, never setHTML, and use SafeHtml when markup is unavoidable. XML is also larger than JSON for the same data; unless a service forces it on you, prefer JSON.

The lab is a private copy of the Bookshelf Maven project with one extra GWT module and a handful of servlets.

The servlet mappings are plain web.xml entries:

Source: GWT — Tutorial: Cross-site requests

Open http://localhost:8933/lab/page. The lab module needs the second origin only for the cross-origin cases (a 30-line com.sun.net.httpserver program on port 8943 that serves JSONP, a JSON endpoint without CORS headers, and two endpoints with CORS headers). For development, the same module runs in Super Dev Mode with mvn gwt:codeserver as described on the Development Mode & Debugging page; the lab used the production build because it is what a real deployment serves.

The complete log of the final run (51 lines, abbreviated here to the sequence of scenarios):

The Bookshelf wrapper is what the presenters call; nothing outside it looks at a status code.

Source: GWT Developer Guide — Server communication: Making HTTP requests