de.schlichtherle.key
Interface PromptingKeyProviderUI

All Known Implementing Classes:

PromptingAesKeyProviderUI, PromptingAesKeyProviderUI, PromptingKeyProviderUI, PromptingKeyProviderUI

public interface PromptingKeyProviderUI

Used by PromptingKeyProviders for the actual prompting of the user for a key (a password for example) which is required to access a protected resource. This interface is not depending on any particular user interface techology, so prompting could be implemented using Swing, the console, a web page or any other user interface technology.

Implementations of this interface are instantiated and maintained by the PromptingKeyManager and are shared between different PromptingKeyProvider instances. Hence, implementations of this interface must be thread safe and should have no side effects!

Since:

TrueZIP 6.0

Version:

TrueZIP 6.7

Author:

Christian Schlichtherle

Method Summary

void	promptCreateKey(PromptingKeyProvider provider) Prompts the user for the key which may be used to create a new protected resource or entirely replace the contents of an already existing protected resource.
boolean	promptInvalidOpenKey(PromptingKeyProvider provider) Prompts the user for the key which may be used to open an existing protected resource in order to access its contents.
boolean	promptUnknownOpenKey(PromptingKeyProvider provider) Prompts the user for the key which may be used to open an existing protected resource in order to access its contents.

Method Detail

promptCreateKey

void promptCreateKey(PromptingKeyProvider provider)

Prompts the user for the key which may be used to create a new protected resource or entirely replace the contents of an already existing protected resource.

Upon return, the implementation is expected to update the common key in provider. Upon return, if provider.getKey() returns null, prompting for the key is assumed to have been cancelled by the user. In this case, the current and each subsequent call to KeyProvider.getOpenKey() or KeyProvider.getCreateKey() by the client results in an UnknownKeyException and the user is not prompted anymore until the provider is reset by the KeyManager. Otherwise, the key is used as the common key, a clone of which is provided to the client upon request.

Hint: If the user cancels the dialog, it is recommended to leave the provider's key property simply unmodified. This causes the old key to be reused and allows the client to continue its operation as if the user would not have requested to change the key.

Since TrueZIP 6.4, an implementation may also throw a RuntimeException with any kind of UnknownKeyException as its cause. This will trigger the calling method in the PromptingKeyProvider class to unwrap and pass on the cause without changing its state. This may be useful if prompting was interrupted by a call to Thread.interrupt() while waiting on the Event Dispatch Thread. In this case, another try to prompt the user should have the chance to succeed instead of being cancelled without actually prompting the user again. To trigger this behaviour, the implementation should simply throw any kind of RuntimeException with a KeyPromptingInterruptedException as its cause.

Parameters:

provider - The default key provider to store the result in.

Throws:

RuntimeException - with an UnknownKeyException as its cause if the implementation does not want the key provider's state to be changed.

promptUnknownOpenKey

boolean promptUnknownOpenKey(PromptingKeyProvider provider)

Prompts the user for the key which may be used to open an existing protected resource in order to access its contents.

Upon return, the implementation is expected to update the common key in provider. Upon return, if provider.getKey() returns null, prompting for the key is assumed to have been cancelled by the user. In this case, the current and each subsequent call to KeyProvider.getOpenKey() or KeyProvider.getCreateKey() by the client results in an UnknownKeyException and the user is not prompted anymore until the provider is reset by the KeyManager. Otherwise, the key is used as the common key, a clone of which is provided to the client upon request.

Since TrueZIP 6.4, an implementation may also throw a RuntimeException with any kind of UnknownKeyException as its cause. This will trigger the calling method in the PromptingKeyProvider class to unwrap and pass on the cause without changing its state. This may be useful if prompting was interrupted by a call to Thread.interrupt() while waiting on the Event Dispatch Thread. In this case, another try to prompt the user should have the chance to succeed instead of being cancelled without actually prompting the user again. To trigger this behaviour, the implementation should simply throw any kind of RuntimeException with a KeyPromptingInterruptedException as its cause.

Parameters:

provider - The key provider to store the result in.

Returns:

true if the user has requested to change the provided key.

Throws:

RuntimeException - with an UnknownKeyException as its cause if the implementation does not want the key provider's state to be changed.

promptInvalidOpenKey

boolean promptInvalidOpenKey(PromptingKeyProvider provider)

Prompts the user for the key which may be used to open an existing protected resource in order to access its contents. This is called if the key returned by a previous call to promptUnknownOpenKey(de.schlichtherle.key.PromptingKeyProvider) is invalid.

Upon return, the implementation is expected to update the common key in provider. Upon return, if provider.getKey() returns null, prompting for the key is assumed to have been cancelled by the user. In this case, the current and each subsequent call to KeyProvider.getOpenKey() or KeyProvider.getCreateKey() by the client results in an UnknownKeyException and the user is not prompted anymore until the provider is reset by the KeyManager. Otherwise, the key is used as the common key, a clone of which is provided to the client upon request.

Since TrueZIP 6.4, an implementation may also throw a RuntimeException with any kind of UnknownKeyException as its cause. This will trigger the calling method in the PromptingKeyProvider class to unwrap and pass on the cause without changing its state. This may be useful if prompting was interrupted by a call to Thread.interrupt() while waiting on the Event Dispatch Thread. In this case, another try to prompt the user should have the chance to succeed instead of being cancelled without actually prompting the user again. To trigger this behaviour, the implementation should simply throw any kind of RuntimeException with a KeyPromptingInterruptedException as its cause.

Parameters:

provider - The key provider to store the result in.

Returns:

true if the user has requested to change the provided key.

Throws:

RuntimeException - with an UnknownKeyException as its cause if the implementation does not want the key provider's state to be changed.