com.ptc.windchill.cadx.common.preference
Class URLUtilities

java.lang.Object
  com.ptc.windchill.cadx.common.preference.URLUtilities

All Implemented Interfaces:

URLAuthenticationListener

public final class URLUtilities

extends Object

implements URLAuthenticationListener

Purpose: URLUtilities is a utility class for opening Web Server-based data streams from applets and / or applications. Its four main methods are newInputStream(String), newInputStream(URL), newReader(String) and newReader(URL). This provides the developer with access to input streams or readers (as desired) from either a URL or a String representation of a URL.

The utility setup methods in this class allow the developer to control the open behaviors. The developer can choose to allow the class to cache all userIDs and passwords for future use (setDefaultUseCache and setUseCache). The devloper can choose to allow a popup dialog to be used whenever an HTTP 401 error occurs (setDefaultAllowUserInteraction and setAllowUserInteraction). The difference between setX and setDefaultX is that setX will only apply to the next use of any of the main methods. Before terminating, the default settings are restored to the class instance. The final utility setup method is setPersistCache. This allows the developer to have the cache stored for future use. Note that cache persistence is not yet implemented so this method has no effect.

It is intended that this class be used with a particular user's session (as in a servlet or an application), so it does not implement anything as static to insure separate URLUtilities instances can be generated for each desired session. In an application, it would be expected that the developer would instantiate only one copy of this class to insure that the user only authenticates to a given host:port combination only one time. Note, that if cache persistence is implemented and used, it is possible that no authentication would be needed at all.

When used with application code, this class will allow authentication dialogs to be presented to the user. When used with server-side behavior, like a servlet, the developer can suppress the dialog and instead, use the connection utility methods to set the authorization string for the connection. These connection utility methods include setUserID(String), setPassword(String) and setAuthorization(String). The developer can either use setAuthorization to copy existing credentials to the web server or generate new ones via setUserID and setPassword. Note that the use of either setUserID or setPassword will destroy the current credentials set via setAuthorization. Note also, that the use of any of these routines will cancel the use of cached information for that particular main method call. Note that this class is marked final to insure that no one extends it for the specific purpose of retrieving the set of cached passwords.

Field Summary

protected URL	absoluteBase
private boolean	allowUserInteraction
private String	authorization
private Hashtable	connectionCache
private boolean	defaultAllowUserInteraction
private boolean	defaultUseCache
private URLAuthenticateDialog	dlg
private static int	maxTries
private String	password
private boolean	persistCache
protected URL	relativeBase
private boolean	useCache
private String	userID

Constructor Summary

URLUtilities()
URLUtilities constructor comment.

Method Summary

private void	checkCache(URL url) Purpose: retrieves the ID and password for a given host:port combination from the cache.
private void	cleanup() Purpose: resets internal values after each use of a newXXX method call.
private String	generateCacheKey(URL url) Purpose: Generates a cacheID string based on the URL's host and port number.
URL	getAbsoluteBase() Purpose:
boolean	getAllowUserInteraction() Purpose: Returns the current main method setting for whether the popup dialogs are allowed (true) or not (false).
boolean	getDefaultAllowUserInteraction() Purpose: Shows the default value for user interactions.
boolean	getDefaultUseCache() Purpose: Shows the default for the use of the class' internal cache.
boolean	getPersistCache() Purpose: Shows whether this class will update a local copy of the cache (true) or not (false).
URL	getRelativeBase() Purpose:
boolean	getUseCache() Purpose: Shows whether caching is in effect (true) or not (false) for the next newXXX call.
private void	loadCache() Purpose: Creates a cache when needed.
static void	main(String[] args) Starts the application.
InputStream	newInputStream(String urlName) Purpose: Creates a new InputStream object for the URL represented by the urlName String argument.
InputStream	newInputStream(URL url) Purpose: Creates an InputStream object from a URL.
Reader	newReader(String urlName) Purpose: Creates a new Reader object from the URL represented by the string argument.
Reader	newReader(URL url) Purpose: Creates a new Reader object from the URL specified.
void	setAllowUserInteraction(boolean newValue) Purpose: Sets the User Interaction behavior.
void	setAuthorization(String newValue) Purpose: This routine will set a specific Basic authentication string for the next newXXX call.
void	setDefaultAllowUserInteraction(boolean newValue) Purpose: When set to true, all future uses of newXXX will allow (true) or disallow (false) the use of any dialogs to acquire authentication information from the user.
void	setDefaultUseCache(boolean newValue) Purpose: Sets the default caching behavior for this class.
void	setDocumentBase(String newValue) Purpose:
void	setDocumentBase(URL newValue) Purpose:
void	setPassword(String newValue) Purpose: Sets the password for the upcoming newXXX method call.
void	setPersistCache(boolean newValue) Purpose: Enables or disables the use of cache persistence.
void	setUseCache(boolean newValue) Purpose: Enables or disables the use of the ID / password cache for the next newXXX method call.
void	setUserID(String newValue) Purpose: Sets the user ID for the upcoming newXXX method call.
private void	updateAuthorization() Purpose: Creates the Basic Authentication string from the already existing userID and password fields.
private void	updateCache(URL url) Purpose: Updates the cache if it is permitted by the setting in getUseCache().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

userID

private String userID

password

private String password

authorization

private String authorization

dlg

private URLAuthenticateDialog dlg

maxTries

private static final int maxTries

See Also:

Constant Field Values

allowUserInteraction

private boolean allowUserInteraction

defaultAllowUserInteraction

private boolean defaultAllowUserInteraction

useCache

private boolean useCache

defaultUseCache

private boolean defaultUseCache

persistCache

private boolean persistCache

connectionCache

private Hashtable connectionCache

absoluteBase

protected URL absoluteBase

relativeBase

protected URL relativeBase

Constructor Detail

URLUtilities

public URLUtilities()

URLUtilities constructor comment.

Method Detail

checkCache

private void checkCache(URL url)

Purpose: retrieves the ID and password for a given host:port combination from the cache. This routine does not actually check the cache unless getUseCache() is true, and all of authorization, userID and password are null. If there is no cache in existence, it will call loadCache() to have it created and / or read in from the file system.

Parameters:

url - java.net.URL

cleanup

private void cleanup()

Purpose: resets internal values after each use of a newXXX method call.

generateCacheKey

private String generateCacheKey(URL url)

Purpose: Generates a cacheID string based on the URL's host and port number. The string is returned in the form [host]:[port].

Parameters:

url - java.net.URL

Returns:

java.lang.String

getAbsoluteBase

public URL getAbsoluteBase()

Purpose:

Returns:

java.lang.String

getAllowUserInteraction

public boolean getAllowUserInteraction()

Purpose: Returns the current main method setting for whether the popup dialogs are allowed (true) or not (false). This is in effect only until the next call to newXXX. After that, it will revert to the value of getDefaultAllowUserInteraction().

Returns:

boolean

getDefaultAllowUserInteraction

public boolean getDefaultAllowUserInteraction()

Purpose: Shows the default value for user interactions. True means popups are allowed when 401 errors occur at the web server. This value is the default value for all newXXX calls. It must be overriden by setAllowUserInteractions(boolean) prior to making a newXXX call.

Returns:

boolean

getDefaultUseCache

public boolean getDefaultUseCache()

Purpose: Shows the default for the use of the class' internal cache. True means caching will be used. False means it will not. In order to change this setting for a particular newXXX call, use setUseCache(boolean).

Returns:

boolean

getPersistCache

public boolean getPersistCache()

Purpose: Shows whether this class will update a local copy of the cache (true) or not (false).

This currently does nothing. No cache persistence has been implemented.

Returns:

boolean

getRelativeBase

public URL getRelativeBase()

Purpose:

Returns:

java.lang.String

getUseCache

public boolean getUseCache()

Purpose: Shows whether caching is in effect (true) or not (false) for the next newXXX call. This value is in effect only until the next call to newXXX. After that, it will revert to the value of getDefaultUseCache().

Returns:

boolean

loadCache

private void loadCache()

Purpose: Creates a cache when needed. If persistence is enabled, this method will eventually read the cache data back in from the file system.

main

public static void main(String[] args)

Starts the application.

Parameters:

args - an array of command-line arguments

newInputStream

public InputStream newInputStream(String urlName)
                           throws MalformedURLException,
                                  IOException

Purpose: Creates a new InputStream object for the URL represented by the urlName String argument. This method merely attempts conversion of the string argument to a URL and calls newInputStream(URL).

Parameters:

urlName - java.lang.String

Returns:

InputStream

Throws:

MalformedURLException - when the string does not represent a valid URL

IOException - on any error from the web server. Note that the exception will include the response code as well as the response message from the web server in the exception data.

See Also:

newInputStream(String urlName)

newInputStream

public InputStream newInputStream(URL url)
                           throws IOException,
                                  UnauthenticatedURLException

Purpose: Creates an InputStream object from a URL. This routine wraps a normal URLConnection open with the ability to feed user IDs and passwords or web server Basic authorization strings to the open attempt. It also has the optional ability to detect Access Denied (401) errors from the web server and produce an authentication dialog and thereby create the Basic authorization string for the open attempt. When the authentication dialog is used, up to three tries may be given the user before throwing an IOException indicating the 401 error from the web server. If getUseCache() is true, the userID and password are looked up from an internal cache, using the host name and port being connected to by the URL as the key. Note that caching is only performed as long as setAuthorization, setUserID and setPassword are not used prior to the use of this method call.

This is the primary main method call. newInputStream(String), newReader(URL) and newReader(String) are convenience wrappers around this method call.

Parameters:

url - java.net.URL

Returns:

java.io.InputStream

Throws:

IOException - on any error from the web server. Note that the exception will include the response code as well as the response message from the web server in the exception data.

UnauthenticatedURLException

newReader

public Reader newReader(String urlName)
                 throws MalformedURLException,
                        IOException

Purpose: Creates a new Reader object from the URL represented by the string argument. It actually wraps newReader(URL) which in turn, wraps newInputStream(URL) to perform the work.

Parameters:

urlName - java.lang.String

Returns:

java.io.Reader

Throws:

MalformedURLException - when the string does not represent a valid URL

IOException - on any error from the web server. Note that the exception will include the response code as well as the response message from the web server in the exception data.

See Also:

newInputStream(String urlName)

newReader

public Reader newReader(URL url)
                 throws IOException

Purpose: Creates a new Reader object from the URL specified. This actually wraps newInputStream(URL) to perform the work

Parameters:

url - java.net.URL

Returns:

java.io.Reader

Throws:

IOException - on any error from the web server. Note that the exception will include the response code as well as the response message from the web server in the exception data.

See Also:

newInputStream(String urlName)

setAllowUserInteraction

public void setAllowUserInteraction(boolean newValue)

Purpose: Sets the User Interaction behavior. When true, popup dialogs will be permitted when the newXXX method call results in 401 errors from the web server. When false, no popup dialogs will be permitted and IOExceptions indicating the 401 error will be throw by newXXX calls. Note that this method call only applies to the very next newXXX call. After that call is complete, the next newXXX method call will use the value of getDefaultAllowUserInteraction() unless again overridden by this method call.

Parameters:

newValue - boolean

setAuthorization

public void setAuthorization(String newValue)

Purpose: This routine will set a specific Basic authentication string for the next newXXX call. Note that use of this method overrides any previous setUserID or setPassword calls and will prevent any use of the cached authentication information.

Parameters:

newValue - java.lang.String

setDefaultAllowUserInteraction

public void setDefaultAllowUserInteraction(boolean newValue)

Purpose: When set to true, all future uses of newXXX will allow (true) or disallow (false) the use of any dialogs to acquire authentication information from the user. It is expected that servlet use of this class will set this to false to keep the web server from popping up dialogs instead of the user workstation. Application use of this class will set this to true to allow the user to enter the needed authentication information.

Parameters:

newValue - boolean

setDefaultUseCache

public void setDefaultUseCache(boolean newValue)

Purpose: Sets the default caching behavior for this class. True will utilize the class' internal ID and password caching mechanism. False will disable it. Note that after each newXXX method call, this value is given for the following newXXX method call unless overridden by a specific setUseCache call.

Parameters:

newValue - boolean

setDocumentBase

public void setDocumentBase(String newValue)

Purpose:

Parameters:

newValue - java.lang.String

setDocumentBase

public void setDocumentBase(URL newValue)

Purpose:

Parameters:

newValue - java.lang.String

setPassword

public void setPassword(String newValue)

Purpose: Sets the password for the upcoming newXXX method call. Note that use of this call will prevent the use of any cached data during the next newXXX method call. Note also, that this method call must be repeated prior to each and every newXXX method call - the password information will be cleared after each newXXX call.

Specified by:

setPassword in interface URLAuthenticationListener

Parameters:

newValue - java.lang.String

setPersistCache

public void setPersistCache(boolean newValue)

Purpose: Enables or disables the use of cache persistence. If true, the cache will be restored from a save area and rewritten to the save area whenever it changes.

Note that this currently has no effect as the actual read / write of the cache is not yet implemented.

Parameters:

newValue - boolean

setUseCache

public void setUseCache(boolean newValue)

Purpose: Enables or disables the use of the ID / password cache for the next newXXX method call. Note that after each newXXX call this setting reverts to the same value as getDefaultUseCache().

Parameters:

newValue - boolean

setUserID

public void setUserID(String newValue)

Purpose: Sets the user ID for the upcoming newXXX method call. Note that use of this call will prevent the use of any cached data during the next newXXX method call. Note also, that this method call must be repeated prior to each and every newXXX method call - the user ID information will be cleared after each newXXX call.

Specified by:

setUserID in interface URLAuthenticationListener

Parameters:

newValue - java.lang.String

updateAuthorization

private void updateAuthorization()

Purpose: Creates the Basic Authentication string from the already existing userID and password fields.

updateCache

private void updateCache(URL url)

Purpose: Updates the cache if it is permitted by the setting in getUseCache(). Once implemented, it will also cause the persistent copy of the cache to be written upon a cache data change.