Package org.forgerock.secrets

Class SecretReference<T extends Secret>

java.lang.Object

org.forgerock.secrets.SecretReference<T>

Type Parameters:

T - the type of secret that this reference stores.

public final class SecretReference<T extends Secret>
extends Object

A long-lived reference to an active or named secret. The secret will be transparently refreshed as required by the lease expiry on the secret object.

A secret reference is thread-safe.

See Also:

• Creating a SecretReference from a SecretsProvider.

Constructor Summary

Constructors

Constructor	Description
SecretReference(SecretsProvider provider, Purpose<T> purpose)	Deprecated. Use SecretsProvider.createActiveReference(Purpose) or active(SecretsProvider, Purpose, Clock) instead.
SecretReference(SecretsProvider provider, Purpose<T> purpose, Clock clock)	Deprecated. Use SecretsProvider.createActiveReference(Purpose) or active(SecretsProvider, Purpose, Clock) instead.

Method Summary

Modifier and Type	Method	Description
static <T extends Secret> SecretReference<T>	active(SecretsProvider secretsProvider, Purpose<T> purpose, Clock clock)	Creates a reference to the active secret for the given purpose using the given secrets provider.
static <T extends Secret> SecretReference<T>	constant(T secret)	Create a constant SecretReference for the given secret, that will never expire.
T	get()	Gets the current active secret object, refreshing it if necessary.
Promise<T,NoSuchSecretException>	getAsync()	Gets the current active secret object asynchronously, refreshing it if necessary.
static <T extends Secret> SecretReference<T>	named(SecretsProvider secretsProvider, Purpose<T> purpose, String name, Clock clock)	Creates a reference to a named secret using the given secrets provider.
SecretReference<T>	refresh()	Force the refresh of the secret reference.

Methods inherited from class java.lang.Object

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

Constructor Details

SecretReference

@Deprecated
public SecretReference(SecretsProvider provider,
 Purpose<T> purpose,
 Clock clock)

Deprecated.

Use SecretsProvider.createActiveReference(Purpose) or active(SecretsProvider, Purpose, Clock) instead.

Constructs the secret reference from the given provider and purpose.

Parameters:

provider - the secrets provider to obtain the secret value from.

purpose - the purpose for which a secret is required.

clock - the clock to use when checking if the secret has expired.

See Also:

• Creating a SecretReference from a SecretsProvider.

SecretReference

@Deprecated
public SecretReference(SecretsProvider provider,
 Purpose<T> purpose)

Deprecated.

Use SecretsProvider.createActiveReference(Purpose) or active(SecretsProvider, Purpose, Clock) instead.

Constructs the secret reference from the given provider and purpose using the system clock to check for expiry.

Parameters:

provider - the secrets provider to obtain the secret value from.

purpose - the purpose for which a secret is required.

See Also:

• Creating a SecretReference from a SecretsProvider.

Method Details

get

public T get()
      throws NoSuchSecretException

Gets the current active secret object, refreshing it if necessary. This will block until the secret is available.

Returns:

the active secret for the configured purpose.

Throws:

NoSuchSecretException - if no active secret is available for the configured purpose.

getAsync

public Promise<T,NoSuchSecretException> getAsync()

Gets the current active secret object asynchronously, refreshing it if necessary.

Returns:

a promise for the current active secret.

refresh

public SecretReference<T> refresh()

Force the refresh of the secret reference.

Returns:

itself

constant

public static <T extends Secret> SecretReference<T> constant(T secret)

Create a constant SecretReference for the given secret, that will never expire. This should only be used to support existing use cases that require secrets to be created outside a secrets store. New use cases should make use of the SecretsProvider.useSpecificSecretForPurpose(org.forgerock.secrets.Purpose<S>, S) method.

Type Parameters:

T - The type of the secret.

Parameters:

secret - The secret.

Returns:

The constant reference.

named

public static <T extends Secret> SecretReference<T> named(SecretsProvider secretsProvider,
 Purpose<T> purpose,
 String name,
 Clock clock)

Creates a reference to a named secret using the given secrets provider. The reference will cache the named secret according to the lease expiry time. When the secret is no longer considered valid then the reference will throw NoSuchSecretExceptions.

Type Parameters:

T - the type of secret.

Parameters:

secretsProvider - the secrets provider.

purpose - the purpose.

name - the name of the secret.

clock - the clock to use to detect expiry.

Returns:

a reference to the given named secret that will automatically update.

active

public static <T extends Secret> SecretReference<T> active(SecretsProvider secretsProvider,
 Purpose<T> purpose,
 Clock clock)

Creates a reference to the active secret for the given purpose using the given secrets provider. The reference will cache the active secret according to the lease expiry time. When the secret expires the new active secret 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 active secret that will automatically update.