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:

TrueZIP 6.7

Author:

Christian Schlichtherle

See Also:

PromptingKeyProviderUI, KeyProvider, PromptingKeyManager

Field Summary

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.
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.
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().

Methods inherited from class de.schlichtherle.key.AbstractKeyProvider

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

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.

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.

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()

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()

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()

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).