HTTPClient
Class AuthorizationInfo

java.lang.Object
  HTTPClient.AuthorizationInfo

All Implemented Interfaces:

Cloneable

public class AuthorizationInfo

extends Object

implements Cloneable

Holds the information for an authorization response.

There are 7 fields which make up this class: host, port, scheme, realm, cookie, params, and extra_info. The host and port select which server the info will be sent to. The realm is server specified string which groups various URLs under a given server together and which is used to select the correct info when a server issues an auth challenge; for schemes which don't use a realm (such as "NTLM", "PEM", and "Kerberos") the realm must be the empty string (""). The scheme is the authorization scheme used (such as "Basic" or "Digest").

There are basically two formats used for the Authorization header, the one used by the "Basic" scheme and derivatives, and the one used by the "Digest" scheme and derivatives. The first form contains just the the scheme and a "cookie":

    Authorization: Basic aGVsbG86d29ybGQ=

The second form contains the scheme followed by a number of parameters in the form of name=value pairs:

    Authorization: Digest username="hello", realm="test", nonce="42", ...

The two fields "cookie" and "params" correspond to these two forms. toString() is used by the AuthorizationModule when generating the Authorization header and will format the info accordingly. Note that "cookie" and "params" are mutually exclusive: if the cookie field is non-null then toString() will generate the first form; otherwise it will generate the second form.

In some schemes "extra" information needs to be kept which doesn't appear directly in the Authorization header. An example of this are the A1 and A2 strings in the Digest scheme. Since all elements in the params field will appear in the Authorization header this field can't be used for storing such info. This is what the extra_info field is for. It is an arbitrary object which can be manipulated by the corresponding setExtraInfo() and getExtraInfo() methods, but which will not be printed by toString().

The addXXXAuthorization(), removeXXXAuthorization(), and getAuthorization() methods manipulate and query an internal list of AuthorizationInfo instances. There can be only one instance per host, port, scheme, and realm combination (see equals()).

Since:

V0.1

Constructor Summary

(package private)	AuthorizationInfo(AuthorizationInfo templ) Creates a new copy of the given AuthorizationInfo.
(package private)	AuthorizationInfo(String host, int port) Creates an new info structure for the specified host and port.
	AuthorizationInfo(String host, int port, String scheme, String realm, NVPair[] params, Object info) Creates a new info structure for the specified host and port with the specified scheme, realm, params.
	AuthorizationInfo(String host, int port, String scheme, String realm, String cookie) Creates a new info structure for the specified host and port with the specified scheme, realm and cookie.

Method Summary

static void	addAuthorization(AuthorizationInfo auth_info) Adds an authorization entry to the list using the default context.
static void	addAuthorization(AuthorizationInfo auth_info, Object context) Adds an authorization entry to the list.
static void	addAuthorization(String host, int port, String scheme, String realm, String cookie, NVPair[] params, Object info) Adds an authorization entry to the list using the default context.
static void	addAuthorization(String host, int port, String scheme, String realm, String cookie, NVPair[] params, Object info, Object context) Adds an authorization entry to the list.
static void	addBasicAuthorization(String host, int port, String realm, String user, String passwd) Adds an authorization entry for the "Basic" authorization scheme to the list using the default context.
static void	addBasicAuthorization(String host, int port, String realm, String user, String passwd, Object context) Adds an authorization entry for the "Basic" authorization scheme to the list.
static void	addDigestAuthorization(String host, int port, String realm, String user, String passwd) Adds an authorization entry for the "Digest" authorization scheme to the list using the default context.
static void	addDigestAuthorization(String host, int port, String realm, String user, String passwd, Object context) Adds an authorization entry for the "Digest" authorization scheme to the list.
void	addPath(String resource) Adds the path from the given resource to our path list.
Object	clone()
boolean	equals(Object obj) Two AuthorizationInfos are considered equal if their host, port, scheme and realm match.
(package private) static AuthorizationInfo	findBest(RoRequest req) Tries to find the candidate in the current list of auth info for the given request.
static AuthorizationHandler	getAuthHandler() Get's the current authorization handler.
(package private) static AuthorizationInfo	getAuthorization(AuthorizationInfo auth_info, RoRequest req, RoResponse resp, boolean query_auth_h) Searches for the authorization info using the host, port, scheme and realm from the given info struct.
static AuthorizationInfo	getAuthorization(String host, int port, String scheme, String realm) Searches for the authorization info using the given host, port, scheme and realm.
static AuthorizationInfo	getAuthorization(String host, int port, String scheme, String realm, Object context) Searches for the authorization info in the given context using the given host, port, scheme and realm.
(package private) static AuthorizationInfo	getAuthorization(String host, int port, String scheme, String realm, RoRequest req, RoResponse resp, boolean query_auth_h) Searches for the authorization info given a host, port, scheme and realm.
String	getCookie() Get the cookie
Object	getExtraInfo() Get the extra info.
String	getHost() Get the host.
NVPair[]	getParams() Get the authentication parameters.
int	getPort() Get the port.
String	getRealm() Get the realm.
String	getScheme() Get the scheme.
int	hashCode() Produces a hash code based on host, scheme and realm.
(package private) static AuthorizationInfo[]	parseAuthString(String challenge, RoRequest req, RoResponse resp) Parses the authentication challenge(s) into an array of new info structures for the specified host and port.
(package private) static AuthorizationInfo	queryAuthHandler(AuthorizationInfo auth_info, RoRequest req, RoResponse resp) Queries the AuthHandler for authorization info.
static void	removeAuthorization(AuthorizationInfo auth_info) Removes an authorization entry from the list using the default context.
static void	removeAuthorization(AuthorizationInfo auth_info, Object context) Removes an authorization entry from the list.
static void	removeAuthorization(String host, int port, String scheme, String realm) Removes an authorization entry from the list using the default context.
static void	removeAuthorization(String host, int port, String scheme, String realm, Object context) Removes an authorization entry from the list.
static AuthorizationHandler	setAuthHandler(AuthorizationHandler handler) Set's the authorization handler.
void	setCookie(String cookie) Set the cookie
void	setExtraInfo(Object info) Set the extra info.
void	setParams(NVPair[] params) Set the authentication parameters.
String	toString() Constructs a string containing the authorization info.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AuthorizationInfo

AuthorizationInfo(String host,
                  int port)

Creates an new info structure for the specified host and port.

Parameters:

host - the host

port - the port

AuthorizationInfo

public AuthorizationInfo(String host,
                         int port,
                         String scheme,
                         String realm,
                         NVPair[] params,
                         Object info)

Creates a new info structure for the specified host and port with the specified scheme, realm, params. The cookie is set to null.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

params - the parameters as an array of name/value pairs, or null

info - arbitrary extra info, or null

AuthorizationInfo

public AuthorizationInfo(String host,
                         int port,
                         String scheme,
                         String realm,
                         String cookie)

Creates a new info structure for the specified host and port with the specified scheme, realm and cookie. The params is set to a zero-length array, and the extra_info is set to null.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

cookie - for the "Basic" scheme this is the base64-encoded username/password; for the "NTLM" scheme this is the base64-encoded username/password message.

AuthorizationInfo

AuthorizationInfo(AuthorizationInfo templ)

Creates a new copy of the given AuthorizationInfo.

Parameters:

templ - the info to copy

Method Detail

setAuthHandler

public static AuthorizationHandler setAuthHandler(AuthorizationHandler handler)

Set's the authorization handler. This handler is called whenever the server requests authorization and no entry for the requested scheme and realm can be found in the list. The handler must implement the AuthorizationHandler interface.

If no handler is set then a default handler is used. This handler currently only handles the "Basic" and "Digest" schemes and brings up a popup which prompts for the username and password.

The default handler can be disabled by setting the auth handler to null.

Parameters:

handler - the new authorization handler

Returns:

the old authorization handler

See Also:

AuthorizationHandler

getAuthHandler

public static AuthorizationHandler getAuthHandler()

Get's the current authorization handler.

Returns:

the current authorization handler, or null if none is set.

See Also:

AuthorizationHandler

getAuthorization

public static AuthorizationInfo getAuthorization(String host,
                                                 int port,
                                                 String scheme,
                                                 String realm)

Searches for the authorization info using the given host, port, scheme and realm. The context is the default context.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

Returns:

a pointer to the authorization data or null if not found

getAuthorization

public static AuthorizationInfo getAuthorization(String host,
                                                 int port,
                                                 String scheme,
                                                 String realm,
                                                 Object context)

Searches for the authorization info in the given context using the given host, port, scheme and realm.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

context - the context this info is associated with

Returns:

a pointer to the authorization data or null if not found

queryAuthHandler

static AuthorizationInfo queryAuthHandler(AuthorizationInfo auth_info,
                                          RoRequest req,
                                          RoResponse resp)
                                   throws AuthSchemeNotImplException,
                                          IOException

Queries the AuthHandler for authorization info. It also adds this info to the list.

Parameters:

auth_info - any info needed by the AuthHandler; at a minimum the host, scheme and realm should be set.

req - the request which initiated this query

resp - the full response

Returns:

a structure containing the requested info, or null if either no AuthHandler is set or the user canceled the request.

Throws:

AuthSchemeNotImplException - if this is thrown by the AuthHandler.

IOException

getAuthorization

static AuthorizationInfo getAuthorization(AuthorizationInfo auth_info,
                                          RoRequest req,
                                          RoResponse resp,
                                          boolean query_auth_h)
                                   throws AuthSchemeNotImplException,
                                          IOException

Searches for the authorization info using the host, port, scheme and realm from the given info struct. If not found it queries the AuthHandler (if set).

Parameters:

auth_info - the AuthorizationInfo

req - the request which initiated this query

resp - the full response

query_auth_h - if true, query the auth-handler if no info found.

Returns:

a pointer to the authorization data or null if not found

Throws:

AuthSchemeNotImplException - If thrown by the AuthHandler.

IOException

getAuthorization

static AuthorizationInfo getAuthorization(String host,
                                          int port,
                                          String scheme,
                                          String realm,
                                          RoRequest req,
                                          RoResponse resp,
                                          boolean query_auth_h)
                                   throws AuthSchemeNotImplException,
                                          IOException

Searches for the authorization info given a host, port, scheme and realm. Queries the AuthHandler if not found in list.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

req - the request which initiated this query

resp - the full response

query_auth_h - if true, query the auth-handler if no info found.

Returns:

a pointer to the authorization data or null if not found

Throws:

AuthSchemeNotImplException - If thrown by the AuthHandler.

IOException

addAuthorization

public static void addAuthorization(AuthorizationInfo auth_info)

Adds an authorization entry to the list using the default context. If an entry for the specified scheme and realm already exists then its cookie and params are replaced with the new data.

Parameters:

auth_info - the AuthorizationInfo to add

addAuthorization

public static void addAuthorization(AuthorizationInfo auth_info,
                                    Object context)

Adds an authorization entry to the list. If an entry for the specified scheme and realm already exists then its cookie and params are replaced with the new data.

Parameters:

auth_info - the AuthorizationInfo to add

context - the context to associate this info with

addAuthorization

public static void addAuthorization(String host,
                                    int port,
                                    String scheme,
                                    String realm,
                                    String cookie,
                                    NVPair[] params,
                                    Object info)

Adds an authorization entry to the list using the default context. If an entry for the specified scheme and realm already exists then its cookie and params are replaced with the new data.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

cookie - the cookie

params - an array of name/value pairs of parameters

info - arbitrary extra auth info

addAuthorization

public static void addAuthorization(String host,
                                    int port,
                                    String scheme,
                                    String realm,
                                    String cookie,
                                    NVPair[] params,
                                    Object info,
                                    Object context)

Adds an authorization entry to the list. If an entry for the specified scheme and realm already exists then its cookie and params are replaced with the new data.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

cookie - the cookie

params - an array of name/value pairs of parameters

info - arbitrary extra auth info

context - the context to associate this info with

addBasicAuthorization

public static void addBasicAuthorization(String host,
                                         int port,
                                         String realm,
                                         String user,
                                         String passwd)

Adds an authorization entry for the "Basic" authorization scheme to the list using the default context. If an entry already exists for the "Basic" scheme and the specified realm then it is overwritten.

Parameters:

host - the host

port - the port

realm - the realm

user - the username

passwd - the password

addBasicAuthorization

public static void addBasicAuthorization(String host,
                                         int port,
                                         String realm,
                                         String user,
                                         String passwd,
                                         Object context)

Adds an authorization entry for the "Basic" authorization scheme to the list. If an entry already exists for the "Basic" scheme and the specified realm then it is overwritten.

Parameters:

host - the host

port - the port

realm - the realm

user - the username

passwd - the password

context - the context to associate this info with

addDigestAuthorization

public static void addDigestAuthorization(String host,
                                          int port,
                                          String realm,
                                          String user,
                                          String passwd)

Adds an authorization entry for the "Digest" authorization scheme to the list using the default context. If an entry already exists for the "Digest" scheme and the specified realm then it is overwritten.

Parameters:

host - the host

port - the port

realm - the realm

user - the username

passwd - the password

addDigestAuthorization

public static void addDigestAuthorization(String host,
                                          int port,
                                          String realm,
                                          String user,
                                          String passwd,
                                          Object context)

Adds an authorization entry for the "Digest" authorization scheme to the list. If an entry already exists for the "Digest" scheme and the specified realm then it is overwritten.

Parameters:

host - the host

port - the port

realm - the realm

user - the username

passwd - the password

context - the context to associate this info with

removeAuthorization

public static void removeAuthorization(AuthorizationInfo auth_info)

Removes an authorization entry from the list using the default context. If no entry for the specified host, port, scheme and realm exists then this does nothing.

Parameters:

auth_info - the AuthorizationInfo to remove

removeAuthorization

public static void removeAuthorization(AuthorizationInfo auth_info,
                                       Object context)

Removes an authorization entry from the list. If no entry for the specified host, port, scheme and realm exists then this does nothing.

Parameters:

auth_info - the AuthorizationInfo to remove

context - the context this info is associated with

removeAuthorization

public static void removeAuthorization(String host,
                                       int port,
                                       String scheme,
                                       String realm)

Removes an authorization entry from the list using the default context. If no entry for the specified host, port, scheme and realm exists then this does nothing.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

removeAuthorization

public static void removeAuthorization(String host,
                                       int port,
                                       String scheme,
                                       String realm,
                                       Object context)

Removes an authorization entry from the list. If no entry for the specified host, port, scheme and realm exists then this does nothing.

Parameters:

host - the host

port - the port

scheme - the scheme

realm - the realm

context - the context this info is associated with

findBest

static AuthorizationInfo findBest(RoRequest req)

Tries to find the candidate in the current list of auth info for the given request. The paths associated with each auth info are examined, and the one with either the nearest direct parent or child is chosen. This is used for preemptively sending auth info.

Parameters:

req - the Request

Returns:

an AuthorizationInfo containing the info for the best match, or null if none found.

addPath

public void addPath(String resource)

Adds the path from the given resource to our path list. The path list is used for deciding when to preemptively send auth info.

Parameters:

resource - the resource from which to extract the path

parseAuthString

static AuthorizationInfo[] parseAuthString(String challenge,
                                           RoRequest req,
                                           RoResponse resp)
                                    throws ProtocolException

Parses the authentication challenge(s) into an array of new info structures for the specified host and port.

Parameters:

challenge - a string containing authentication info. This must have the same format as value part of a WWW-authenticate response header field, and may contain multiple authentication challenges.

req - the original request.

Throws:

ProtocolException - if any error during the parsing occurs.

getHost

public final String getHost()

Get the host.

Returns:

a string containing the host name.

getPort

public final int getPort()

Get the port.

Returns:

an int containing the port number.

getScheme

public final String getScheme()

Get the scheme.

Returns:

a string containing the scheme.

getRealm

public final String getRealm()

Get the realm.

Returns:

a string containing the realm.

getCookie

public final String getCookie()

Get the cookie

Returns:

the cookie String

Since:

V0.3-1

setCookie

public final void setCookie(String cookie)

Set the cookie

Parameters:

cookie - the new cookie

Since:

V0.3-1

getParams

public final NVPair[] getParams()

Get the authentication parameters.

Returns:

an array of name/value pairs.

setParams

public final void setParams(NVPair[] params)

Set the authentication parameters.

getExtraInfo

public final Object getExtraInfo()

Get the extra info.

Returns:

the extra_info object

setExtraInfo

public final void setExtraInfo(Object info)

Set the extra info.

Parameters:

info - the extra info

toString

public String toString()

Constructs a string containing the authorization info. The format is that of the http Authorization header.

Returns:

a String containing all info.

hashCode

public int hashCode()

Produces a hash code based on host, scheme and realm. Port is not included for simplicity (and because it probably won't make much difference). Used in the AuthorizationInfo.AuthList hash table.

Returns:

the hash code

equals

public boolean equals(Object obj)

Two AuthorizationInfos are considered equal if their host, port, scheme and realm match. Used in the AuthorizationInfo.AuthList hash table.

Parameters:

obj - another AuthorizationInfo against which this one is to be compared.

Returns:

true if they match in the above mentioned fields; false otherwise.

clone

public Object clone()

Returns:

a clone of this AuthorizationInfo using a deep copy