Package org.forgerock.secrets

Class ValidSecretsReference<S extends Secret,E extends Exception>

java.lang.Object

org.forgerock.secrets.ValidSecretsReference<S,E>

Type Parameters:

S - the type of secrets that this reference stores.

E - the type of exception that can be thrown when fetching secrets.

public final class ValidSecretsReference<S extends Secret,E extends Exception>
extends Object

A long-lived reference to a number of secrets. The secrets will be transparently refreshed at "getAsync()" time whenever one of the cached secrets is either closed or expired.

A secrets reference is thread-safe.

See Also:

• Creating a ValidSecretsReference for valid secrets from a SecretsProvider.
• Creating a ValidSecretsReference for valid or named secrets.

Method Summary

Modifier and Type	Method	Description
List<S>	get()	Gets the current secrets, refreshing them if necessary.
Promise<List<S>,E>	getAsync()	Gets the secrets asynchronously, refreshing them if necessary.
static <T extends Secret> ValidSecretsReference<T,NeverThrowsException>	valid(SecretsProvider secretsProvider, Purpose<T> purpose, Clock clock)	Creates a reference to the valid secrets for the given purpose using the given secrets provider.
static <T extends Secret> ValidSecretsReference<T,NeverThrowsException>	validOrNamed(SecretsProvider secretsProvider, Purpose<T> purpose, String name, Clock clock)	This creates a reference to either the named secret or all valid secrets for the purpose.

Methods inherited from class java.lang.Object

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

Method Details

get

public List<S> get()
            throws E,
NoSuchSecretException

Gets the current secrets, refreshing them if necessary. This will block until the secrets are available.

Returns:

the secrets for the configured purpose.

Throws:

E - if no secrets can be obtained.

NoSuchSecretException

getAsync

public Promise<List<S>,E> getAsync()

Gets the secrets asynchronously, refreshing them if necessary.

Returns:

a promise for the current secrets.

valid

public static <T extends Secret>
ValidSecretsReference<T,NeverThrowsException> valid(SecretsProvider secretsProvider,
 Purpose<T> purpose,
 Clock clock)

Creates a reference to the valid secrets for the given purpose using the given secrets provider. The reference will cache the valid secrets according to the lease expiry time. When the secrets expire the new valid secrets will be retrieved (which may be different to the previous value).

Type Parameters:

T - the type of secret.

Parameters:

secretsProvider - the secrets provider.

purpose - the purpose.

clock - the clock to use to detect expiry.

Returns:

a reference to the given valid secrets that will automatically update.

validOrNamed

public static <T extends Secret>
ValidSecretsReference<T,NeverThrowsException> validOrNamed(SecretsProvider secretsProvider,
 Purpose<T> purpose,
 String name,
 Clock clock)

This creates a reference to either the named secret or all valid secrets for the purpose. If the given id is not null, then this returns a reference to the single named secret that corresponds to that stable id (or valid secrets for the given purpose if no such secret exists), otherwise it returns a reference to all valid secrets for the given purpose. This is a convenience method for a frequent case where you want to process an incoming message (e.g., to decrypt or verify it) and the message may or may not have a secret/key identifier.

Type Parameters:

T - the type of secret.

Parameters:

secretsProvider - the secrets provider.

purpose - the purpose.

name - the stableId of the secret, or null if not known.

clock - the clock to use to detect expiry.

Returns:

a reference to the given valid secrets that will automatically update.