de.schlichtherle.key
Class AbstractKeyProvider

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

All Implemented Interfaces:

KeyProvider

Direct Known Subclasses:

PromptingKeyProvider, SharedKeyProvider

public abstract class AbstractKeyProvider
extends Object
implements KeyProvider

This abstract class implements the base functionality required to be a "friendly" KeyProvider. Each instance of this class maintains a single key, which can be of any run time type (it is just required to be an Object). A clone of this key is returned on each call to getCreateKey() and getOpenKey(). Cloning is used for all array classes and all classes which properly implement the Cloneable interface. The class remains abstract because there is no meaningful template implementation of the invalidOpenKeyImpl() method.

Other than the key, this class is stateless. Hence, instances may be shared among multiple protected resources, causing them to use the same key. However, this feature may be restricted by subclasses such as PromptingKeyProvider for example.

This class is thread safe.

Since:

TrueZIP 6.4 (renamed from SharedKeyProvider)

Version:

TrueZIP 6.7

Author:

Christian Schlichtherle

See Also:

KeyProvider

Field Summary

Fields inherited from interface de.schlichtherle.key.KeyProvider

MIN_KEY_RETRY_DELAY

Constructor Summary

AbstractKeyProvider()

Method Summary

protected KeyProvider	addToKeyManager(String resourceID) Maps this instance as the key provider for the given resource identifier in the KeyManager.
protected Object	cloneKey() Deprecated. You should not use or override this method. This method will vanish in the next major version release.
Object	getCreateKey() Forwards the call to getCreateKeyImpl().
protected Object	getCreateKeyImpl() Returns the key which should be used to create a new protected resource or entirely replace the contents of an already existing protected resource.
Object	getKey() Deprecated. You should not use this method from this class. It will be moved to a subclass in the next major version release.
Object	getOpenKey() Forwards the call to getOpenKeyImpl() and enforces a three seconds suspension penalty if invalidOpenKey() was called by the same thread before.
protected Object	getOpenKeyImpl() Returns the key which should be used to open an existing protected resource in order to access its contents.
void	invalidOpenKey() This method logs the current time for the current thread, which is later used by getOpenKey() to enforce the suspension penalty and then calls invalidOpenKeyImpl().
protected abstract void	invalidOpenKeyImpl() Sublasses must implement this method.
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() This hook may be overridden to reset this key provider instance.
protected void	resetKey() Deprecated. You should not use or override this method. This method will vanish in the next major version release.
void	setKey(Object key) Deprecated. You should not use this method from this class. It will be moved to a subclass in the next major version release.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractKeyProvider

public AbstractKeyProvider()

Method Detail

getKey

public Object getKey()

Deprecated. You should not use this method from this class. It will be moved to a subclass in the next major version release.

Returns the single key maintained by this key provider. Client applications should not call this method directly, but rather call getOpenKey() or getCreateKey(). It is intended to be used by subclasses and user interface classes only.

setKey

public void setKey(Object key)

Deprecated. You should not use this method from this class. It will be moved to a subclass in the next major version release.

Sets the single key maintained by this key provider. Client applications should not call this method directly. It is intended to be used by subclasses and user interface classes only.

getCreateKey

public Object getCreateKey()
                    throws UnknownKeyException

Forwards the call to getCreateKeyImpl().

Specified by:

getCreateKey in interface KeyProvider

Returns:

A clone of the return value of getCreateKeyImpl. In case of an array, a shallow copy of the array is returned.

Throws:

UnknownKeyException - If getCreateKeyImpl throws this or the returned key is null.

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

See Also:

KeyProvider.getCreateKey()

getCreateKeyImpl

protected Object getCreateKeyImpl()
                           throws UnknownKeyException

Returns the key which should be used to create a new protected resource or entirely replace the contents of an already existing protected resource.

Returns:

A template for the key to use or null.

Throws:

UnknownKeyException - If the required key is unknown. At the subclasses discretion, this may mean that prompting for the key has been disabled or cancelled by the user.

See Also:

KeyProvider.getCreateKey()

getOpenKey

public final Object getOpenKey()
                        throws UnknownKeyException

Forwards the call to getOpenKeyImpl() and enforces a three seconds suspension penalty if invalidOpenKey() was called by the same thread before. Because this method is final, this qualifies the implementation in this class as a "friendly" KeyProvider implementation, even when subclassed.

Specified by:

getOpenKey in interface KeyProvider

Returns:

A clone of the return value of getOpenKeyImpl. In case of an array, a shallow copy of the array is returned.

Throws:

UnknownKeyException - If getOpenKeyImpl throws this or the returned key is null.

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

See Also:

KeyProvider.getOpenKey()

getOpenKeyImpl

protected Object getOpenKeyImpl()
                         throws UnknownKeyException

Returns the key which should be used to open an existing protected resource in order to access its contents.

Returns:

A template for the key to use or null.

Throws:

UnknownKeyException - If the required key is unknown. At the subclasses discretion, this may mean that prompting for the key has been disabled or cancelled by the user.

See Also:

KeyProvider.getCreateKey()

invalidOpenKey

public final void invalidOpenKey()

This method logs the current time for the current thread, which is later used by getOpenKey() to enforce the suspension penalty and then calls invalidOpenKeyImpl(). Because this method is final, this implementation qualifies as a "friendly" KeyProvider implementation, even when subclassed.

Specified by:

invalidOpenKey in interface KeyProvider

See Also:

KeyProvider.invalidOpenKey()

invalidOpenKeyImpl

protected abstract void invalidOpenKeyImpl()

Sublasses must implement this method.

See Also:

KeyProvider.invalidOpenKey()

reset

public void reset()

This hook may be overridden to reset this key provider instance. The implementation in this class does nothing.

cloneKey

protected Object cloneKey()

Deprecated. You should not use or override this method. This method will vanish in the next major version release.

Returns a clone of the key, which may be null. If the key is an array, a shallow copy of the array is returned. When overriding this method, please consider that the key may be null.

Throws:

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

resetKey

protected void resetKey()

Deprecated. You should not use or override this method. This method will vanish in the next major version release.

Clears the data structure of the key itself and sets the reference to it to null. If the key is an array, the array is filled with zero values before setting the reference to null. When overwriting this method, please consider that the key may be null.

addToKeyManager

protected KeyProvider addToKeyManager(String resourceID)
                               throws NullPointerException,
                                      IllegalStateException

Maps this instance as the key provider for the given resource identifier 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 mapped in the KeyManager.

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:

NullPointerException - If resourceID is null.

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

removeFromKeyManager

protected KeyProvider removeFromKeyManager(String resourceID)
                                    throws NullPointerException,
                                           IllegalStateException

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.

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