Top Description Inners Fields Constructors Methods
java.net

public abstract Class Authenticator

extends Object
Class Inheritance
The class Authenticator represents an object that knows how to obtain authentication for a network connection. Usually, it will do this by prompting the user for information.

Applications use this class by overriding getPasswordAuthentication() in a sub-class. This method will typically use the various getXXX() accessor methods to get information about the entity requesting authentication. It must then acquire a username and password either by interacting with the user or through some other non-interactive means. The credentials are then returned as a PasswordAuthentication return value.

An instance of this concrete sub-class is then registered with the system by calling setDefault(Authenticator). When authentication is required, the system will invoke one of the requestPasswordAuthentication() methods which in turn will call the getPasswordAuthentication() method of the registered object.

All methods that request authentication have a default implementation that fails.

Author
Bill Foote
Since
1.2
See Also
java.net.Authenticator#setDefault(java.net.Authenticator), java.net.Authenticator#getPasswordAuthentication()

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
Authenticator.RequestorType

The type of the entity requesting authentication.

Field Summary

Modifier and TypeField and Description
private Authenticator.RequestorType
requestingAuthType

private String
requestingHost

private int
requestingPort

private String
requestingPrompt

private String
requestingProtocol

private String
requestingScheme

private InetAddress
requestingSite

private URL
requestingURL

private static volatile Authenticator
theAuthenticator

Constructor Summary

AccessConstructor and Description
public
Authenticator()

Constructor for subclasses to call.

Method Summary

Modifier and TypeMethod and Description
public static Authenticator

Returns:

The default authenticator, if set, null otherwise.
getDefault()

Gets the default authenticator.

protected PasswordAuthentication

Returns:

The PasswordAuthentication collected from the user, or null if none is provided.
getPasswordAuthentication()

Called when password authorization is needed.

protected final String

Returns:

the hostname of the connection requiring authentication, or null if it's not available.
getRequestingHost()

Gets the hostname of the site or proxy requesting authentication, or null if not available.

protected final int

Returns:

an int indicating the port for the requested connection.
getRequestingPort()

Gets the port number for the requested connection.

protected final String

Returns:

the prompt string given by the requestor (realm for http requests)
getRequestingPrompt()

Gets the prompt string given by the requestor.

protected final String

Returns:

the protocol, optionally followed by "/version", where version is a version number.
getRequestingProtocol()

Give the protocol that's requesting the connection.

protected final String

Returns:

the scheme of the requestor
getRequestingScheme()

Gets the scheme of the requestor (the HTTP scheme for an HTTP firewall, for example).

protected final InetAddress

Returns:

the InetAddress of the site requesting authorization, or null if it's not available.
getRequestingSite()

Gets the InetAddress of the site requesting authorization, or null if not available.

protected URL

Returns:

the requesting URL
getRequestingURL()

Returns the URL that resulted in this request for authentication.

protected Authenticator.RequestorType

Returns:

the authentication type of the requestor
getRequestorType()

Returns whether the requestor is a Proxy or a Server.

public static PasswordAuthentication

Returns:

The username/password, or null if one can't be gotten.
requestPasswordAuthentication(InetAddress
The InetAddress of the site requesting authorization, or null if not known.
addr, int
the port for the requested connection
port, String
The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())
protocol, String
A prompt string for the user
prompt, String
The authentication scheme
scheme)

Ask the authenticator that has been registered with the system for a password.

public static PasswordAuthentication

Returns:

The username/password, or null if one can't be gotten.
requestPasswordAuthentication(String
The hostname of the site requesting authentication.
host, InetAddress
The InetAddress of the site requesting authentication, or null if not known.
addr, int
the port for the requested connection.
port, String
The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())
protocol, String
A prompt string for the user which identifies the authentication realm.
prompt, String
The authentication scheme
scheme)

Ask the authenticator that has been registered with the system for a password.

public static PasswordAuthentication

Returns:

The username/password, or null if one can't be gotten.
requestPasswordAuthentication(String
The hostname of the site requesting authentication.
host, InetAddress
The InetAddress of the site requesting authorization, or null if not known.
addr, int
the port for the requested connection
port, String
The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())
protocol, String
A prompt string for the user
prompt, String
The authentication scheme
scheme, URL
The requesting URL that caused the authentication
url, Authenticator.RequestorType
The type (server or proxy) of the entity requesting authentication.
reqType)

Ask the authenticator that has been registered with the system for a password.

public static PasswordAuthentication

Returns:

The username/password, or null if one can't be gotten.
requestPasswordAuthentication(Authenticator
the authenticator, or null.
authenticator, String
The hostname of the site requesting authentication.
host, InetAddress
The InetAddress of the site requesting authorization, or null if not known.
addr, int
the port for the requested connection
port, String
The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())
protocol, String
A prompt string for the user
prompt, String
The authentication scheme
scheme, URL
The requesting URL that caused the authentication
url, Authenticator.RequestorType
The type (server or proxy) of the entity requesting authentication.
reqType)

Ask the given authenticator for a password.

public PasswordAuthentication

Returns:

The username/password, or null if one can't be gotten
requestPasswordAuthenticationInstance(String
The hostname of the site requesting authentication.
host, InetAddress
The InetAddress of the site requesting authorization, or null if not known.
addr, int
the port for the requested connection
port, String
The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())
protocol, String
A prompt string for the user
prompt, String
The authentication scheme
scheme, URL
The requesting URL that caused the authentication
url, Authenticator.RequestorType
The type (server or proxy) of the entity requesting authentication.
reqType)

Ask this authenticator for a password.

private void
reset()

public static synchronized void
setDefault(Authenticator
The authenticator to be set. If a is null then any previously set authenticator is removed.
a)

Sets the authenticator that will be used by the networking code when a proxy or an HTTP server asks for authentication.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

requestingAuthTypeback to summary
private Authenticator.RequestorType requestingAuthType
requestingHostback to summary
private String requestingHost
requestingPortback to summary
private int requestingPort
requestingPromptback to summary
private String requestingPrompt
requestingProtocolback to summary
private String requestingProtocol
requestingSchemeback to summary
private String requestingScheme
requestingSiteback to summary
private InetAddress requestingSite
requestingURLback to summary
private URL requestingURL
theAuthenticatorback to summary
private static volatile Authenticator theAuthenticator

Constructor Detail

Authenticatorback to summary
public Authenticator()

Constructor for subclasses to call.

Method Detail

getDefaultback to summary
public static Authenticator getDefault()

Gets the default authenticator. First, if there is a security manager, its checkPermission method is called with a NetPermission("requestPasswordAuthentication") permission. This may result in a java.lang.SecurityException. Then the default authenticator, if set, is returned. Otherwise, null is returned.

Returns:Authenticator

The default authenticator, if set, null otherwise.

Exceptions
SecurityException:
if a security manager exists and its checkPermission method doesn't allow requesting password authentication.
Since
9
See Also
SecurityManager#checkPermission, java.net.NetPermission
getPasswordAuthenticationback to summary
protected PasswordAuthentication getPasswordAuthentication()

Called when password authorization is needed. Subclasses should override the default implementation, which returns null.

Returns:PasswordAuthentication

The PasswordAuthentication collected from the user, or null if none is provided.

getRequestingHostback to summary
protected final String getRequestingHost()

Gets the hostname of the site or proxy requesting authentication, or null if not available.

Returns:String

the hostname of the connection requiring authentication, or null if it's not available.

Since
1.4
getRequestingPortback to summary
protected final int getRequestingPort()

Gets the port number for the requested connection.

Returns:int

an int indicating the port for the requested connection.

getRequestingPromptback to summary
protected final String getRequestingPrompt()

Gets the prompt string given by the requestor.

Returns:String

the prompt string given by the requestor (realm for http requests)

getRequestingProtocolback to summary
protected final String getRequestingProtocol()

Give the protocol that's requesting the connection. Often this will be based on a URL, but in a future JDK it could be, for example, "SOCKS" for a password-protected SOCKS5 firewall.

Returns:String

the protocol, optionally followed by "/version", where version is a version number.

See Also
java.net.URL#getProtocol()
getRequestingSchemeback to summary
protected final String getRequestingScheme()

Gets the scheme of the requestor (the HTTP scheme for an HTTP firewall, for example).

Returns:String

the scheme of the requestor

getRequestingSiteback to summary
protected final InetAddress getRequestingSite()

Gets the InetAddress of the site requesting authorization, or null if not available.

Returns:InetAddress

the InetAddress of the site requesting authorization, or null if it's not available.

getRequestingURLback to summary
protected URL getRequestingURL()

Returns the URL that resulted in this request for authentication.

Returns:URL

the requesting URL

Since
1.5
getRequestorTypeback to summary
protected Authenticator.RequestorType getRequestorType()

Returns whether the requestor is a Proxy or a Server.

Returns:Authenticator.RequestorType

the authentication type of the requestor

Since
1.5
requestPasswordAuthenticationback to summary
public static PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String scheme)

Ask the authenticator that has been registered with the system for a password.

First, if there is a security manager, its checkPermission method is called with a NetPermission("requestPasswordAuthentication") permission. This may result in a java.lang.SecurityException.

Parameters
addr:InetAddress

The InetAddress of the site requesting authorization, or null if not known.

port:int

the port for the requested connection

protocol:String

The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())

prompt:String

A prompt string for the user

scheme:String

The authentication scheme

Returns:PasswordAuthentication

The username/password, or null if one can't be gotten.

Exceptions
SecurityException:
if a security manager exists and its checkPermission method doesn't allow the password authentication request.
See Also
SecurityManager#checkPermission, java.net.NetPermission
requestPasswordAuthenticationback to summary
public static PasswordAuthentication requestPasswordAuthentication(String host, InetAddress addr, int port, String protocol, String prompt, String scheme)

Ask the authenticator that has been registered with the system for a password. This is the preferred method for requesting a password because the hostname can be provided in cases where the InetAddress is not available.

First, if there is a security manager, its checkPermission method is called with a NetPermission("requestPasswordAuthentication") permission. This may result in a java.lang.SecurityException.

Parameters
host:String

The hostname of the site requesting authentication.

addr:InetAddress

The InetAddress of the site requesting authentication, or null if not known.

port:int

the port for the requested connection.

protocol:String

The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())

prompt:String

A prompt string for the user which identifies the authentication realm.

scheme:String

The authentication scheme

Returns:PasswordAuthentication

The username/password, or null if one can't be gotten.

Exceptions
SecurityException:
if a security manager exists and its checkPermission method doesn't allow the password authentication request.
Since
1.4
See Also
SecurityManager#checkPermission, java.net.NetPermission
requestPasswordAuthenticationback to summary
public static PasswordAuthentication requestPasswordAuthentication(String host, InetAddress addr, int port, String protocol, String prompt, String scheme, URL url, Authenticator.RequestorType reqType)

Ask the authenticator that has been registered with the system for a password.

First, if there is a security manager, its checkPermission method is called with a NetPermission("requestPasswordAuthentication") permission. This may result in a java.lang.SecurityException.

Parameters
host:String

The hostname of the site requesting authentication.

addr:InetAddress

The InetAddress of the site requesting authorization, or null if not known.

port:int

the port for the requested connection

protocol:String

The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())

prompt:String

A prompt string for the user

scheme:String

The authentication scheme

url:URL

The requesting URL that caused the authentication

reqType:Authenticator.RequestorType

The type (server or proxy) of the entity requesting authentication.

Returns:PasswordAuthentication

The username/password, or null if one can't be gotten.

Exceptions
SecurityException:
if a security manager exists and its checkPermission method doesn't allow the password authentication request.
Since
1.5
See Also
SecurityManager#checkPermission, java.net.NetPermission
requestPasswordAuthenticationback to summary
public static PasswordAuthentication requestPasswordAuthentication(Authenticator authenticator, String host, InetAddress addr, int port, String protocol, String prompt, String scheme, URL url, Authenticator.RequestorType reqType)

Ask the given authenticator for a password. If the given authenticator is null, the authenticator, if any, that has been registered with the system using setDefault is used.

First, if there is a security manager, its checkPermission method is called with a NetPermission("requestPasswordAuthentication") permission. This may result in a java.lang.SecurityException.

Parameters
authenticator:Authenticator

the authenticator, or null.

host:String

The hostname of the site requesting authentication.

addr:InetAddress

The InetAddress of the site requesting authorization, or null if not known.

port:int

the port for the requested connection

protocol:String

The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())

prompt:String

A prompt string for the user

scheme:String

The authentication scheme

url:URL

The requesting URL that caused the authentication

reqType:Authenticator.RequestorType

The type (server or proxy) of the entity requesting authentication.

Returns:PasswordAuthentication

The username/password, or null if one can't be gotten.

Exceptions
SecurityException:
if a security manager exists and its checkPermission method doesn't allow the password authentication request.
Since
9
See Also
SecurityManager#checkPermission, java.net.NetPermission
requestPasswordAuthenticationInstanceback to summary
public PasswordAuthentication requestPasswordAuthenticationInstance(String host, InetAddress addr, int port, String protocol, String prompt, String scheme, URL url, Authenticator.RequestorType reqType)

Ask this authenticator for a password.

Parameters
host:String

The hostname of the site requesting authentication.

addr:InetAddress

The InetAddress of the site requesting authorization, or null if not known.

port:int

the port for the requested connection

protocol:String

The protocol that's requesting the connection (java.net.Authenticator#getRequestingProtocol())

prompt:String

A prompt string for the user

scheme:String

The authentication scheme

url:URL

The requesting URL that caused the authentication

reqType:Authenticator.RequestorType

The type (server or proxy) of the entity requesting authentication.

Returns:PasswordAuthentication

The username/password, or null if one can't be gotten

Since
9
resetback to summary
private void reset()
setDefaultback to summary
public static synchronized void setDefault(Authenticator a)

Sets the authenticator that will be used by the networking code when a proxy or an HTTP server asks for authentication.

First, if there is a security manager, its checkPermission method is called with a NetPermission("setDefaultAuthenticator") permission. This may result in a java.lang.SecurityException.

Parameters
a:Authenticator

The authenticator to be set. If a is null then any previously set authenticator is removed.

Exceptions
SecurityException:
if a security manager exists and its checkPermission method doesn't allow setting the default authenticator.
See Also
SecurityManager#checkPermission, java.net.NetPermission
java.net back to summary

public final Enum Authenticator.RequestorType

extends Enum<Authenticator.RequestorType>
Class Inheritance
The type of the entity requesting authentication.
Since
1.5

Field Summary

Modifier and TypeField and Description
public static final Authenticator.RequestorType
PROXY

Entity requesting authentication is a HTTP proxy server.

public static final Authenticator.RequestorType
SERVER

Entity requesting authentication is a HTTP origin server.

Constructor Summary

AccessConstructor and Description
private
RequestorType()

Method Summary

Modifier and TypeMethod and Description
public static Authenticator.RequestorType
valueOf(String name)

public static Authenticator.RequestorType[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

PROXYback to summary
public static final Authenticator.RequestorType PROXY

Entity requesting authentication is a HTTP proxy server.

SERVERback to summary
public static final Authenticator.RequestorType SERVER

Entity requesting authentication is a HTTP origin server.

Constructor Detail

RequestorTypeback to summary
private RequestorType()

Method Detail

valueOfback to summary
public static Authenticator.RequestorType valueOf(String name)
valuesback to summary
public static Authenticator.RequestorType[] values()