software.amazon.serverless.ssmcachingclient

Class SsmParameterCachingClient

java.lang.Object

software.amazon.serverless.ssmcachingclient.SsmParameterCachingClient

public class SsmParameterCachingClient
extends Object

The SsmParameterCachingClient is a thread-safe class that provides an in-memory caching layer over SSM Parameter Store. This is useful when using the "standard" SSM Parameter Store (free service), which only supports a small number of transactions per second (TPS).

Security Note: All calls made to SSM Parameter Store decrypt SecureString parameter values and cache them in plain text in the in-memory cache. However, this class does not write decrypted SecureString values to disk.

Using pathPrefix

The client accepts a parameter path prefix, which allows it to make more efficient bulk calls to the SSM Parameter Store API and bulk load all parameters under the given path prefix at once. For example, you might use the following hierarchy for storing parameters for FooService:

     /FooService/Dev/DbTableName
     /FooService/Dev/NotificationTopicArn
     /FooService/Prod/DbTableName
     /FooService/Prod/NotificationTopicArn
 

In this example, there are separate parameters for FooService depending on if the environment is Dev or Prod. If SsmParameterCachingClient is passed "/FooService/Dev/" as the pathPrefix, it will make a bulk call to the SSM Parameter Store API to load and cache all parameters that start with "/FooService/Dev/".

Also, the get methods on the client will automatically prepend the pathPrefix so you can initialize the client once with the pathPrefix and then reference the parameters without the prefix from there on out:

 // initialization code
 SsmClient ssm = SsmClient.create();
 SsmParameterCachingClient client = new SsmParameterCachingClient(ssm, Duration.ofSeconds(60), "/FooService/Dev/");

 ...

 // elsewhere in your business logic
 client.getAsString("DbTableName");
 

Using this pattern, only your initialization code needs to know what environment you're running in, and the rest of your business logic can refer to the parameters without the prefix.

For more information on organizing parameters into hierarchies, see the AWS Systems Manager User Guide.

Constructor Summary

Constructors

Constructor and Description
SsmParameterCachingClient(software.amazon.awssdk.services.ssm.SsmClient ssm, Duration ttl) Convenience constructor for creating a new caching client.
SsmParameterCachingClient(software.amazon.awssdk.services.ssm.SsmClient ssm, Duration ttl, String pathPrefix) Convenience constructor for creating a new caching client.
SsmParameterCachingClient(software.amazon.awssdk.services.ssm.SsmClient ssm, Duration ttl, String pathPrefix, boolean allowStaleValues, boolean bulkLoad) Create a new caching client.

Method Summary

Modifier and Type	Method and Description
software.amazon.awssdk.services.ssm.model.Parameter	get(String name) Get a parameter value.
String	getAsString(String name) Get a parameter value as a String.
List<String>	getAsStringList(String name) Get a parameter value as a List of Strings.

Methods inherited from class java.lang.Object

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

Constructor Detail

SsmParameterCachingClient

public SsmParameterCachingClient(software.amazon.awssdk.services.ssm.SsmClient ssm,
                                 Duration ttl,
                                 String pathPrefix,
                                 boolean allowStaleValues,
                                 boolean bulkLoad)

Create a new caching client.

Parameters:

ssm - AWS SSM client.

ttl - The cache time-to-live (TTL), which is the duration before a cached value will be considered stale.

pathPrefix - Parameter path prefix to prepend to all parameter names passed to get methods.

allowStaleValues - If set to true, the client will fall back to returning stale cached values if SSM cannot be reached to refresh the cache.

bulkLoad - If set to true and pathPrefix is non-null, the client will bulk load and cache all parameters for the given pathPrefix once the cache is stale, rather than loading them one at a time.

SsmParameterCachingClient

public SsmParameterCachingClient(software.amazon.awssdk.services.ssm.SsmClient ssm,
                                 Duration ttl,
                                 String pathPrefix)

Convenience constructor for creating a new caching client. Defaults to setting allowStaleValues and bulkLoad to true.

Parameters:

ssm - AWS SSM client.

ttl - The cache time-to-live (TTL), which is the duration before a cached value will be considered stale.

pathPrefix - Parameter path prefix to prepend to all parameter names passed to #get().

SsmParameterCachingClient

public SsmParameterCachingClient(software.amazon.awssdk.services.ssm.SsmClient ssm,
                                 Duration ttl)

Convenience constructor for creating a new caching client. Defaults to setting pathPrefix to null, and allowStaleValues and bulkLoad to true.

Parameters:

ssm - AWS SSM client.

ttl - The cache time-to-live (TTL), which is the duration before a cached value will be considered stale.

Method Detail

get

public software.amazon.awssdk.services.ssm.model.Parameter get(String name)

Get a parameter value.

Parameters:

name - Parameter name to get. If a pathPrefix has been supplied, it is prepended to name.

Returns:

Full Parameter object returned by SSM client.

getAsString

public String getAsString(String name)

Get a parameter value as a String.

Parameters:

name - Parameter name to get. If a pathPrefix has been supplied, it is prepended to name.

Returns:

Parameter value as a string.

getAsStringList

public List<String> getAsStringList(String name)

Get a parameter value as a List of Strings.

Parameters:

name - Parameter name to get. If a pathPrefix has been supplied, it is prepended to name.

Returns:

Parameter value as a list of strings. List is generated by splitting the parameter string using ',' as a delimiter.

Throws:

IllegalArgumentException - if returned parameter is not of type StringList.