HTTPClient
Interface AuthorizationHandler

All Known Implementing Classes:

DefaultAuthHandler, SuppliedUPAuthHandler

public interface AuthorizationHandler

This is the interface that an Authorization handler must implement. You can implement your own auth handler to add support for auth schemes other than the ones handled by the default handler, to use a different UI for soliciting usernames and passwords, or for using an altogether different way of getting the necessary auth info.

See Also:

AuthorizationInfo.setAuthHandler(HTTPClient.AuthorizationHandler)

Method Summary

AuthorizationInfo	fixupAuthInfo(AuthorizationInfo info, RoRequest req, AuthorizationInfo challenge, RoResponse resp) This method is called whenever auth info is chosen from the list of known info in the AuthorizationInfo class to be sent with a request.
AuthorizationInfo	getAuthorization(AuthorizationInfo challenge, RoRequest req, RoResponse resp) This method is called whenever a 401 or 407 response is received and no candidate info is found in the list of known auth info.
void	handleAuthHeaders(Response resp, RoRequest req, AuthorizationInfo prev, AuthorizationInfo prxy) Sometimes even non-401 responses will contain headers pertaining to authorization (such as the "Authentication-Info" header).
void	handleAuthTrailers(Response resp, RoRequest req, AuthorizationInfo prev, AuthorizationInfo prxy) This method is similar to handleAuthHeaders except that it is called if any headers in the trailer were sent.

Method Detail

getAuthorization

public AuthorizationInfo getAuthorization(AuthorizationInfo challenge,
                                          RoRequest req,
                                          RoResponse resp)
                                   throws AuthSchemeNotImplException,
                                          java.io.IOException

This method is called whenever a 401 or 407 response is received and no candidate info is found in the list of known auth info. Usually this method will query the user for the necessary info.

If the returned info is not null it will be added to the list of known info. If the info is valid for more than one (host, port, realm, scheme) tuple then this method must add the corresponding auth infos itself.

This method must check req.allow_ui and only attempt user interaction if it's true.

Parameters:

challenge - the parsed challenge from the server; the host, port, scheme, realm and params are set to the values given by the server in the challenge.

req - the request which provoked this response.

resp - the full response.

Returns:

the authorization info to use when retrying the request, or null if the request is not to be retried. The necessary info includes the host, port, scheme and realm as given in the challenge parameter, plus either the basic cookie or any necessary params.

Throws:

AuthSchemeNotImplException - if the authorization scheme in the challenge cannot be handled.

java.io.IOException - if an exception occurs while processing the challenge

fixupAuthInfo

public AuthorizationInfo fixupAuthInfo(AuthorizationInfo info,
                                       RoRequest req,
                                       AuthorizationInfo challenge,
                                       RoResponse resp)
                                throws AuthSchemeNotImplException,
                                       java.io.IOException

This method is called whenever auth info is chosen from the list of known info in the AuthorizationInfo class to be sent with a request. This happens when either auth info is being preemptively sent or if a 401 response is retrieved and a matching info is found in the list of known info. The intent of this method is to allow the handler to fix up the info being sent based on the actual request (e.g. in digest authentication the digest-uri, nonce and response-digest usually need to be recalculated).

Parameters:

info - the authorization info retrieved from the list of known info.

req - the request this info is targeted for.

challenge - the authorization challenge received from the server if this is in response to a 401, or null if we are preemptively sending the info.

resp - the full 401 response received, or null if we are preemptively sending the info.

Returns:

the authorization info to be sent with the request, or null if none is to be sent.

Throws:

AuthSchemeNotImplException - if the authorization scheme in the info cannot be handled.

java.io.IOException - if an exception occurs while fixing up the info

handleAuthHeaders

public void handleAuthHeaders(Response resp,
                              RoRequest req,
                              AuthorizationInfo prev,
                              AuthorizationInfo prxy)
                       throws java.io.IOException

Sometimes even non-401 responses will contain headers pertaining to authorization (such as the "Authentication-Info" header). Therefore this method is invoked for each response received, even if it is not a 401 or 407 response. In case of a 401 or 407 response the methods fixupAuthInfo() and getAuthorization() are invoked after this method.

Parameters:

resp - the full Response

req - the Request which provoked this response

prev - the previous auth info sent, or null if none was sent

prxy - the previous proxy auth info sent, or null if none was sent

Throws:

java.io.IOException - if an exception occurs during the reading of the headers.

handleAuthTrailers

public void handleAuthTrailers(Response resp,
                               RoRequest req,
                               AuthorizationInfo prev,
                               AuthorizationInfo prxy)
                        throws java.io.IOException

This method is similar to handleAuthHeaders except that it is called if any headers in the trailer were sent. This also implies that it is invoked after any fixupAuthInfo() or getAuthorization() invocation.

Parameters:

resp - the full Response

req - the Request which provoked this response

prev - the previous auth info sent, or null if none was sent

prxy - the previous proxy auth info sent, or null if none was sent

Throws:

java.io.IOException - if an exception occurs during the reading of the trailers.

See Also:

handleAuthHeaders(HTTPClient.Response, HTTPClient.RoRequest, HTTPClient.AuthorizationInfo, HTTPClient.AuthorizationInfo)