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

All Known Implementing Classes:

AesCipherParametersView, AesCipherParametersView

Enclosing class:

PromptingKeyProvider<K extends SafeKey<K>>

@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public static interface PromptingKeyProvider.View<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.getWriteKey() or SafeKeyProvider.getReadKey(boolean) is called.

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

promptWriteKey

void promptWriteKey(PromptingKeyProvider.Controller<K> controller)
                    throws UnknownKeyException

Prompts the user for the key for (over)writing the contents of a new or existing protected resource. Upon return, the implementation should have updated the key property of the given controller.

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

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

Parameters:

controller - The key controller for storing the result.

Throws:

UnknownKeyException - if key prompting fails for any reason.

promptReadKey

void promptReadKey(PromptingKeyProvider.Controller<K> controller,
                   boolean invalid)
                   throws UnknownKeyException

Prompts the user for the key for reading the contents of an existing protected resource. Upon return, the implementation should have updated the key property of the given controller.

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

Otherwise, if the implementation has called PromptingKeyProvider.Controller.setKey(K) with a null parameter or throws a KeyPromptingCancelledException, then prompting for the key is permanently disabled and each subsequent call to SafeKeyProvider.getWriteKey() or SafeKeyProvider.getReadKey(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:

controller - The key controller for storing the result.

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.