Managing Tomcat Session State with DynamoDB
Tomcat applications often store session-state data in memory. However, this approach doesn't scale well because once the application grows beyond a single web server, the session state must be shared among servers. A common solution is to set up a dedicated session-state server with MySQL. However, this approach also has drawbacks: you must administer another server, the session-state server is a single pointer of failure, and the MySQL server itself can cause performance problems.
DynamoDB, which is a NoSQL database store from AWS, avoids these drawbacks by providing an effective solution for sharing session state across web servers.
You can download the session manager from the aws/aws-dynamodb-session-tomcat project on GitHub. This project also hosts the session manager source code, so you can contribute to the project by sending us pull requests or opening issues.
To use the DynamoDB session-state provider, you must do the following:
- Configure the Tomcat server to use the provider.
- Set the security credentials of the provider so that it can access AWS.
AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar to the
lib directory of your
AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar is a complete,
standalone JAR that contains all the code and dependencies to run the DynamoDB Tomcat Session Manager.
Edit your server's
context.xml file to specify
com.amazonaws.services.dynamodb.sessionmanager.DynamoDBSessionManager as your session
<?xml version="1.0" encoding="UTF-8"?> <Context> <WatchedResource>WEB-INF/web.xml</WatchedResource> <Manager className="com.amazonaws.services.dynamodb.sessionmanager.DynamoDBSessionManager" createIfNotExist="true" /> </Context>
You can specify AWS security credentials for the session manager in multiple ways. They are loaded in the following order of precedence:
AwsSecretKeyattributes of the
Managerelement explicitly provide credentials.
AwsCredentialsFileattribute on the
Managerelement specifies a properties file from which to load credentials.
If you don't specify credentials through the
DefaultAWSCredentialsProviderChain continues searching for credentials in the following
- Environment variables –
- Java system properties –
- Instance profile credentials delivered through the Amazon EC2 instance metadata service (IMDS)
If you're using the session manager in Elastic Beanstalk, ensure your project has an
.ebextensions directory at the top level of your output artifact structure. Put the following
context.xmlfile, described previously, to configure the session manager
- A configuration file that copies the JAR into Tomcat's
libdirectory and applies the overridden
For more information about customizing Elastic Beanstalk environments, see AWS Elastic Beanstalk Environment Configuration in the Elastic Beanstalk Developer Guide.
If you deploy to Elastic Beanstalk with the AWS Toolkit for Eclipse, you can have the toolkit set up the session manager
for you; use
the New AWS Java Web Project wizard and choose DynamoDB for session management. The AWS Toolkit for Eclipse
configures the required files and puts them in the
.ebextensions directory in the
WebContent directory of your project. If you have problems finding this directory, be sure
you aren't hiding files that begin with a period.
If the Tomcat server is running on an Amazon EC2 instance that is configured to use IAM roles for EC2
instances, you don't need to specify any credentials in the
context.xml file. In this case,
the AWS SDK for Java uses IAM roles credentials obtained through the instance metadata service (IMDS).
When your application starts, it looks for a DynamoDB table named, by default,
Tomcat_SessionState. The table should have a string hash key named "sessionId"
(case-sensitive), no range key, and the desired values for
We recommend that you create this table before running your application for the first time. If you don't
the table, however, the extension creates it during initialization. See the
options in the next section for a list of attributes that configure how the session-state table is
created when it doesn't exist.
TipFor information about working with DynamoDB tables and provisioned throughput, see the DynamoDB Developer Guide.
After the application is configured and the table is created, you can use sessions with any other session provider.
You can use the following configuration attributes in the
Manager element of
- AwsAccessKey – Access key ID to use.
- AwsSecretKey – Secret key to use.
- AwsCredentialsFile – A properties file containing
secretKeyproperties with your AWS security credentials.
- Table – Optional string attribute. The name of the table used to store session data. The default is Tomcat_SessionState.
- RegionId – Optional string attribute. The AWS Region in which to use DynamoDB. For a list of available AWS Regions, see Regions and Endpoints in the Amazon Web Services General Reference.
- Endpoint – Optional string attribute that, if present, overrides any
value set for the
Regionoption. This attribute specifies the regional endpoint of the DynamoDB service to use. For a list of available AWS Regions, see Regions and Endpoints in Amazon Web Services General Reference.
- ReadCapacityUnits – Optional int attribute. The read capacity units to use if the session manager creates the table. The default is 10.
- WriteCapacityUnits – Optional int attribute. The write capacity units to use if the session manager creates the table. The default is 5.
- CreateIfNotExist – Optional Boolean attribute. The
CreateIfNotExistattribute controls whether the session manager autocreates the table if it doesn't exist. The default is true. If this flag is set to false and the table doesn't exist, an exception is thrown during Tomcat startup.
If you encounter issues with the session manager, the first place to look is in
catalina.out. If you have access to the Tomcat installation, you can go directly to this log
file and look for any error messages from the session manager. If you're using Elastic Beanstalk, you can view
the environment logs with the AWS Management Console or the AWS Toolkit for Eclipse.
The session manager doesn't support session locking. Therefore, applications that use many concurrent AJAX calls to manipulate session data may not be appropriate for use with the session manager, due to race conditions on session data writes and saves back to the data store.