public interface RequestAuthorizer

Supplies the Authorization header of the requests an application sends to its own service, and renews it when the service refuses it.

An authorizer is given to one request with ConnectionRequest.setAuthorizer(RequestAuthorizer) or RequestBuilder.authorizer(RequestAuthorizer), or to every request under a base URL with NetworkManager.setAuthorizer(String, RequestAuthorizer):

NetworkManager.getInstance().setAuthorizer("https://api.example.com", authorizer);

OidcRequestAuthorizer is the implementation for a service that accepts OAuth 2.0 access tokens.

What happens to a request

1. As the request is queued, getAuthorization(ConnectionRequest) is asked for a header value, which travels with the request. A request that already carries an Authorization header keeps its own: one the caller set always wins, and so does a default header of NetworkManager.
2. If the service answers 401, nothing is delivered yet. The request is held and refreshAuthorization(ConnectionRequest, String) is asked for a new credential.
3. If that succeeds the request is sent once more with the new header, and its answer – whatever it is, another 401 included – is delivered as usual. There is one renewal per request, so a service that keeps refusing cannot make this loop.
4. If it fails, the request is sent again as it first was, and the service’s 401 goes through the request’s ordinary error handling exactly as it would have without an authorizer.

Code that waits for the request – NetworkManager.addToQueueAndWait(ConnectionRequest), the blocking methods of RequestBuilder, NetworkManager.addToQueueAsync(ConnectionRequest) – keeps waiting through all of it and sees only the final answer.

An authorizer that knows when its credential expires can skip the refused request altogether: see Proactive.

Threads

Every method of an authorizer is called on the event dispatch thread and on no other, so an implementation keeps its credential in plain fields and needs no lock. A network thread never calls one: it sends the header value that was put on the request, on the EDT, when the request was queued or released after a renewal. A request queued from another thread is passed to the EDT first, and so is a 401, which a network thread is the one to see.

The header is therefore the one current when the request was queued. If the credential is renewed while the request waits in the queue, the service refuses the old one and the request is sent again with the new one, as step 2 describes.

getAuthorization(ConnectionRequest) must answer from memory. It must not wait for another request: the EDT would wait on the queue it is filling. Renewing is therefore a separate step, which the authorizer starts and answers later.