de.schlichtherle.truezip.key
Interface PromptingKeyProvider.UI<K extends SafeKey<K>>

All Known Implementing Classes:

AesCipherParametersUI, AesCipherParametersUI

Enclosing class:

PromptingKeyProvider<K extends SafeKey<K>>

@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public static interface PromptingKeyProvider.UI<K extends SafeKey<K>>

Used 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 maintained by a PromptingKeyManager and injected into the PromptingKeyProvider before SafeKeyProvider.getCreateKey() or SafeKeyProvider.getOpenKey(boolean) is called.

Implementations of this interface must be thread safe and should have no side effects!

promptCreateKey

void promptCreateKey(PromptingKeyProvider<? super K> provider)
                     throws UnknownKeyException

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 should have updated the key property of the given provider.

If the implementation has called PromptingKeyProvider.setKey(K) with a non-null parameter, then a clone of this object will be used as the key of the given provider.

Otherwise, prompting for a key is permanently disabled and each subsequent call to SafeKeyProvider.getCreateKey() or SafeKeyProvider.getOpenKey(boolean) results in a KeyPromptingCancelledException until PromptingKeyProvider.resetCancelledKey() or PromptingKeyProvider.resetUnconditionally() gets called.

Parameters:

provider - The key provider to store the result in.

Throws:

UnknownKeyException - if key prompting fails for any reason.

promptOpenKey

void promptOpenKey(PromptingKeyProvider<? super K> provider,
                   boolean invalid)
                   throws UnknownKeyException

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 should have updated the key property of the given provider.

If the implementation has called PromptingKeyProvider.setKey(K) with a non-null parameter, then a clone of this object will be used as the key of the given provider.

Otherwise, if the implementation has called PromptingKeyProvider.setKey(K) with a null parameter or throws a KeyPromptingCancelledException, then prompting for the key is permanently disabled and each subsequent call to SafeKeyProvider.getCreateKey() or SafeKeyProvider.getOpenKey(boolean) results in a KeyPromptingCancelledException until PromptingKeyProvider.resetCancelledKey() or PromptingKeyProvider.resetUnconditionally() gets called.

Otherwise, the state of the key provider is not changed and this method gets called again.

Parameters:

provider - The key provider to store the result in.

invalid - true iff a previous call to this method resulted in an invalid key.

Throws:

KeyPromptingCancelledException - if key prompting has been cancelled by the user.

UnknownKeyException - if key prompting fails for any other reason.