de.schlichtherle.key
Class PromptingKeyProvider

java.lang.Object
  de.schlichtherle.key.AbstractKeyProvider
      de.schlichtherle.key.PromptingKeyProvider

All Implemented Interfaces:

KeyProvider

Direct Known Subclasses:

PromptingAesKeyProvider

public class PromptingKeyProvider
extends AbstractKeyProvider

A "friendly" implementation of KeyProvider which prompts the user for a key for its protected resource, enforcing a three seconds suspension penalty if a wrong key was provided. The user is prompted via an instance of the PromptingKeyProviderUI user interface which is determined by the default instance of PromptingKeyManager as returned by KeyManager.getInstance().

Like its base class, this class does not impose a certain run time type of the key. It is actually the user interface implementation which determines the run time type of the key provided by AbstractKeyProvider.getCreateKey() and AbstractKeyProvider.getOpenKey(). Because the user interface implementation is determined by the singleton PromptingKeyManager, it is ultimately at the discretion of the key manager which type of keys are actually provided by this class.

Unlike its base class, instances of this class cannot get shared among multiple protected resources because each instance has a unique resource identifier associated with it. Each try to share a key provider of this class among multiple protected resources with the singleton KeyManager will be prosecuted and sentenced with an IllegalStateException or, at the discretion of this class, some other RuntimeException.

This class is thread safe.

Since:

TrueZIP 6.0

Version:

$Id: PromptingKeyProvider.java 5e709f50671d 2010/11/05 11:52:07 christian $

Author:

Christian Schlichtherle

See Also:

PromptingKeyProviderUI, KeyProvider, PromptingKeyManager

Nested Class Summary

private static class	PromptingKeyProvider.Cancelled
private static class	PromptingKeyProvider.KeyChanged
private static class	PromptingKeyProvider.KeyChangeRequested
private static class	PromptingKeyProvider.KeyInvalidated
private static class	PromptingKeyProvider.KeyProvided
private static class	PromptingKeyProvider.PromptingLock
private static class	PromptingKeyProvider.Reset
private static class	PromptingKeyProvider.State

Field Summary

private PromptingKeyProvider.PromptingLock	lock Used to lock out prompting by multiple threads.
private String	resourceID The resource identifier for the protected resource.
private PromptingKeyProvider.State	state
private PromptingKeyProviderUI	ui The user interface instance which is used to prompt the user for a key.

Fields inherited from interface de.schlichtherle.key.KeyProvider

MIN_KEY_RETRY_DELAY

Constructor Summary

PromptingKeyProvider()

Method Summary

protected KeyProvider	addToKeyManager(String resourceID) Like the super class implementation, but throws an IllegalStateException if this instance is already mapped for another resource identifier.
Object	getCreateKeyImpl() Returns a clone of the key which may be used to create a new protected resource or entirely replace the contents of an already existing protected resource.
protected Object	getOpenKeyImpl() Returns a clone of the key which may be used to open an existing protected resource in order to access its contents.
String	getResourceID() Returns the unique resource identifier of the protected resource for which this key provider is used.
private PromptingKeyProvider.State	getState()
private PromptingKeyProviderUI	getUI()
protected String	getUIClassID() Returns the identifier which is used by the PromptingKeyManager to look up an instance of the PromptingKeyProviderUI user interface class which is then used to prompt the user for a key.
protected void	invalidOpenKeyImpl() Called to indicate that authentication of the key returned by AbstractKeyProvider.getOpenKey() has failed and to request an entirely different key.
protected void	onReset() This hook is run after reset() has been called.
private Object	promptCreateKey() Prompts for a key to create or entirely overwrite a protected resource.
private Object	promptOpenKey(boolean invalid) Prompts for a key to open a protected resource.
protected KeyProvider	removeFromKeyManager(String resourceID) Remove this instance as the key provider for the given resource identifier from the map in the KeyManager.
void	reset() Resets this key provider and finally calls onReset().
(package private) void	resetCancelledPrompt() Resets this key provider if and only if prompting for a key has been cancelled.
private void	resetKey(Object oldKey)
(package private) void	setResourceID(String resourceID)
private void	setState(PromptingKeyProvider.State state)
(package private) void	setUI(PromptingKeyProviderUI ui)

Methods inherited from class de.schlichtherle.key.AbstractKeyProvider

clone, cloneKey, getCreateKey, getKey, getOpenKey, invalidOpenKey, resetKey, setKey

Methods inherited from class java.lang.Object

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

Field Detail

lock

private final PromptingKeyProvider.PromptingLock lock

Used to lock out prompting by multiple threads. Note that the prompting methods in this class must not be synchronized on this instance since this would cause the Swing based default implementation of the key manager to dead lock. This is because the GUI is run from AWT's Event Dispatching Thread, which must call some methods of this instance while another thread is waiting for the key manager to return from prompting. Instead, the prompting methods use this object to lock out concurrent prompting by multiple threads.

resourceID

private String resourceID

The resource identifier for the protected resource.

ui

private PromptingKeyProviderUI ui

The user interface instance which is used to prompt the user for a key.

state

private PromptingKeyProvider.State state

Constructor Detail

PromptingKeyProvider

public PromptingKeyProvider()

Method Detail

getResourceID

public String getResourceID()

Returns the unique resource identifier of the protected resource for which this key provider is used.

setResourceID

final void setResourceID(String resourceID)

getUIClassID

protected String getUIClassID()

Returns the identifier which is used by the PromptingKeyManager to look up an instance of the PromptingKeyProviderUI user interface class which is then used to prompt the user for a key. The implementation in this class returns the fully qualified name of this class.

Subclasses which want to use a custom user interface should overwrite this method to return the fully qualified name of their respective class as the identifier and provide a custom PromptingKeyManager which has registered a PromptingKeyProviderUI class for this identifier.

getUI

private final PromptingKeyProviderUI getUI()

setUI

final void setUI(PromptingKeyProviderUI ui)

getState

private final PromptingKeyProvider.State getState()

setState

private final void setState(PromptingKeyProvider.State state)

getCreateKeyImpl

public final Object getCreateKeyImpl()
                              throws UnknownKeyException

Returns a clone of the key which may be used to create a new protected resource or entirely replace the contents of an already existing protected resource. Returns the key itself if cloning it fails for some reason. If the key is an array, a shallow copy of the array is returned.

If required or explicitly requested by the user, the user is prompted for this key.

Overrides:

getCreateKeyImpl in class AbstractKeyProvider

Returns:

A template for the key to use or null.

Throws:

UnknownKeyException - If the user has cancelled prompting or prompting has been disabled by the PromptingKeyManager.

RuntimeException - If cloning the key results in a runtime exception.

See Also:

KeyProvider.getCreateKey()

promptCreateKey

private Object promptCreateKey()
                        throws UnknownKeyException

Prompts for a key to create or entirely overwrite a protected resource.

Throws:

UnknownKeyException

getOpenKeyImpl

protected final Object getOpenKeyImpl()
                               throws UnknownKeyException

Returns a clone of the key which may be used to open an existing protected resource in order to access its contents. Returns the key itself if cloning it fails for some reason. If the key is an array, a shallow copy of the array is returned.

If required, the user is prompted for this key.

This method enforces a three seconds suspension penalty if AbstractKeyProvider.invalidOpenKey() was called by the same thread before in order to qualify as a "friendly" implementation.

Overrides:

getOpenKeyImpl in class AbstractKeyProvider

Returns:

A template for the key to use or null.

Throws:

UnknownKeyException - If the user has cancelled prompting or prompting has been disabled by the PromptingKeyManager.

RuntimeException - If cloning the key results in a runtime exception.

See Also:

KeyProvider.getOpenKey()

promptOpenKey

private Object promptOpenKey(boolean invalid)
                      throws UnknownKeyException

Prompts for a key to open a protected resource.

Throws:

UnknownKeyException

resetKey

private void resetKey(Object oldKey)

invalidOpenKeyImpl

protected final void invalidOpenKeyImpl()

Called to indicate that authentication of the key returned by AbstractKeyProvider.getOpenKey() has failed and to request an entirely different key. The user is prompted for a new key on the next call to AbstractKeyProvider.getOpenKey(). Note that the user may actually not be prompted at the next call to AbstractKeyProvider.getOpenKey() again if prompting has been disabled by the PromptingKeyManager or this provider is in a state where calling this method does not make any sense.

Specified by:

invalidOpenKeyImpl in class AbstractKeyProvider

See Also:

KeyProvider.invalidOpenKey()

resetCancelledPrompt

final void resetCancelledPrompt()

Resets this key provider if and only if prompting for a key has been cancelled. It is safe to call this method while another thread is actually prompting for a key.

reset

public final void reset()

Resets this key provider and finally calls onReset().

Overrides:

reset in class AbstractKeyProvider

onReset

protected void onReset()

This hook is run after reset() has been called. This method is called from the constructor in the class AbstractKeyProvider. The implementation in this class does nothing. May be overwritten by subclasses.

addToKeyManager

protected KeyProvider addToKeyManager(String resourceID)
                               throws NullPointerException,
                                      IllegalStateException

Like the super class implementation, but throws an IllegalStateException if this instance is already mapped for another resource identifier.

Overrides:

addToKeyManager in class AbstractKeyProvider

Parameters:

resourceID - The resource identifier to map this instance for.

Returns:

The key provider previously mapped for the given resource identifier or null if no key provider was mapped.

Throws:

IllegalStateException - If this instance is already mapped for another resource identifier or mapping is prohibited by a constraint in a subclass. In the latter case, please refer to the subclass documentation for more information.

NullPointerException - If resourceID is null.

removeFromKeyManager

protected KeyProvider removeFromKeyManager(String resourceID)
                                    throws NullPointerException,
                                           IllegalStateException

Description copied from class: AbstractKeyProvider

Remove this instance as the key provider for the given resource identifier from the map in the KeyManager.

The key manager will use this method whenever it adds a key provider which is actually an instance of this class. This allows subclasses to add additional behaviour or constraints whenever an instance is unmapped in the KeyManager.

Overrides:

removeFromKeyManager in class AbstractKeyProvider

Parameters:

resourceID - The resource identifier to unmap this instance from.

Returns:

The key provider previously mapped for the given resource identifier.

Throws:

NullPointerException - If resourceID is null.

IllegalStateException - If unmapping this instance is prohibited by a constraint in a subclass. Please refer to the respective subclass documentation for more information about its constraint(s).