Tomcat Session State Caching
Enable Session State Caching
By default, the Tomcat instance is configured to store all sessions and their data in memory. Under certain circumstances it may be appropriate to persist the sessions and their data to a repository. When this is the case (small amounts of data that should survive the failure of any individual instance), the buildpack can automatically configure Tomcat to do so by binding an appropriate service. In this case, the service is VMware Tanzu GemFire for VMs.
When the session-replication
tag is specified,
the sessions will be stored in the Tanzu GemFire service instance,
thus moving the data out of Tomcat.
An application bound to this service will start running in a Tomcat instance.
A region for storing sessions will be created.
The region will be named gemfire_modules_sessions
.
A 30-minute expiration for sessions will be automatically configured.
For session state caching, use a version 4.3 or more recent Java buildpack.
To enable Tomcat session state caching, do one of these options:
Option 1: When creating your service instance name, specify the
session-replication
tag. For example:$ cf create-service p-cloudcache small-plan my-service-instance -t session-replication
Option 2: Update your service instance, specifying the
session-replication
tag:$ cf update-service new-service-instance -t session-replication
Option 3: When creating the service, include the substring
session-replication
anywhere within the service instance name. An example with the substring ismy-service-instance-session-replication
.
If you need to use a different version of VMware Tanzu GemFire for VMs than is provided by the Java buildpack, follow the instructions in Create a Custom Buildpack.
Note:
A custom buildpack will be needed if your version of the
Cloud Foundry Java buildpack
specifies a geode_store
version that is
more recent than your tile’s version of Tanzu GemFire.
Find the buildpack’s geode_store
version in file /config/tomcat.yml
.
Do not mix Tomcat session state caching (as described here) with Spring Session caching as described in Spring Session Caching. Mixing the two is problematic.
Disable Near Caching Within the App
Near caching is when an app locally caches data. Near caching uses an embedded cache within the app. Web apps that deploy Tomcat with Apache Geode session state caching have near caching by default. To keep an app stateless, you will want to disable near caching.
If you are not using an external repository for configuration, Create a Custom Buildpack to disable near caching.
Create a Custom Buildpack
If your VMware Tanzu GemFire for VMs version is not compatible with the dependencies included in the Java buildpack, you can create a custom buildpack.
Clone the Cloud Foundry Java buildpack repository:
$ git clone git@github.com:cloudfoundry/java-buildpack.git
Change directories to the newly-created repository clone:
$ cd java-buildpack
Check out the desired version or release of the java-buildpack repository on a local branch. Use v4.36 or the most recent version available.
To change the version of VMware Tanzu GemFire for VMs used by the buildpack, edit the
/config/tomcat.yml
configuration file to specify thegeode_store
. Here is the portion of the file to be changed, with the string to change in bold:geode_store: version: 1.13.+ repository_root: https://java-buildpack-tomcat-gemfire-store.s3-us-west-2.amazonaws.com
Change the
geode_store
version to1.12.0
for VMware Tanzu GemFire for VMs version 1.12.Change the
geode_store
version to1.11.0
for VMware Tanzu GemFire for VMs version 1.11.Change the
geode_store
version to0.0.2
for all previous VMware Tanzu GemFire for VMs versions. The complete list ofgeode_store
versions is given in https://java-buildpack-tomcat-gemfire-store.s3-us-west-2.amazonaws.com/index.yml.If you changed the version of VMware Tanzu GemFire for VMs used by the buildpack, you may also need to change the version of the Geode Session State Module used by the buildpack. Edit the following line in the java-buildpack repository file
lib/java_buildpack/container/tomcat/tomcat_geode_store.rb
to specify the appropriate version of Tomcat for your currentgeode_store
version:SESSION_MANAGER_CLASS_NAME = 'org.apache.geode.modules.session.catalina.Tomcat9DeltaSessionManager'
For versions of
geode_store
that are 1.11 or greater, useTomcat9DeltaSessionManager
. For versions ofgeode_store
previous to 1.11 and those withgeode_store
version 0.0.2, useTomcat8DeltaSessionManager
.To disable near caching within the custom buildpack, edit the java-buildpack repository file
lib/java_buildpack/container/tomcat/tomcat_geode_store.rb
such that it disables caching within the app. Change the stringtrue
to instead befalse
. Before the change, here is the portion of the file to be changed, with the string to change highlighted:def add_manager(context) context.add_element 'Manager', 'className' => SESSION_MANAGER_CLASS_NAME, 'enableLocalCache' => 'true', 'regionAttributesId' => REGION_ATTRIBUTES_ID end
After changing the highlighted string from
true
tofalse
, here is the portion of the file with the change highlighted:def add_manager(context) context.add_element 'Manager', 'className' => SESSION_MANAGER_CLASS_NAME, 'enableLocalCache' => 'false', 'regionAttributesId' => REGION_ATTRIBUTES_ID end
Commit the changes to your local branch.
Create your custom Java buildpack on the platform with a command of the form:
cf create-buildpack BUILDPACK-NAME PATH POSITION
where
BUILDPACK-NAME
is the name you choose for your buildpack,PATH
is the location of your local Java buildpack directory, andPOSITION
is the order in which your buildpack will be selected.After building your application, push it such that it uses your buildpack:
cf push -f ./manifest.yml -b BUILDPACK-NAME
where
BUILDPACK-NAME
is the name you chose for your buildpack.Bind your app as described in Bind an App to a Service Instance.
Restage the app to ensure proper configuration:
cf restage APP-NAME
where
APP-NAME
is the name you chose for app.
Use an External Repository for Configuration
The Tomcat container can be customized if you place the custom configuration in a repository. Using an external repository for configuration also facilitates having a single configuration that may be used by a variety of apps.
There are two parts to using an external repository:
- Part 1: Build a repository to hold the configuration, and then push the repository to the space, such that the app will have access.
- Part 2: Change the app such that it uses the external repository.
Part 1 builds the repository:
Make a directory to hold the configuration:
$ mkdir tomcat-config
Make other needed files and directories within the newly created directory:
$ cd tomcat-config $ mkdir public $ mkdir -p tomcat-1.0.0/conf $ touch Staticfile
Edit
Staticfile
to contain:root: public directory: visible
Create a
tomcat-1.0.0/conf/context.xml
file. This example content specifies Tomcat version 9 and disables near caching:<?xml version='1.0' encoding='UTF-8'?> <!-- ~ Copyright 2013-2019 the original author or authors. ~ ~ Licensed under the Apache License, Version 2.0 (the "License"); ~ you may not use this file except in compliance with the License. ~ You may obtain a copy of the License at ~ ~ http://www.apache.org/licenses/LICENSE-2.0 ~ ~ Unless required by applicable law or agreed to in writing, software ~ distributed under the License is distributed on an "AS IS" BASIS, ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. --> <Context> <Resources allowLinking='true'/> <Manager className='org.apache.geode.modules.session.catalina.Tomcat9DeltaSessionManager' enableLocalCache='false' regionAttributesId='PARTITION_REDUNDANT_HEAP_LRU'/> </Context>
You can customize Tomcat further by placing custom configuration files within the
tomcat-1.0.0/conf
directory.Place a compressed TAR format version of the
tomcat-1.0.0
directory into thepublic
directory:$ tar -czf tomcat-1.0.0.tar.gz tomcat-1.0.0/ $ cp tomcat-1.0.0.tar.gz public/
With a current working directory of
tomcat-config
, usecf push
to place the configuration into the VMware Tanzu Application Service for VMs space that will host the app:$ cf push tomcat-config
Issue the command
$ cf apps
to acquire the URL of the
tomcat-config
app. Prepend the listed URL withhttp://
to have the URL that will identify the location of the configuration needed by the app.For example, your complete URL will look something like
http://tomcat-config.apps.yellow-green.cf-app.com
.Within the
tomcat-config
directory, editpublic/index.yml
to have URL-specific contents. Using the example URL as a guide, the contents of thispublic/index.yml
file will contain:--- 1.0.0: http://tomcat-config.apps.yellow-green.cf-app.com/tomcat-1.0.0.tar.gz
Push the configuration a second time with its completed configuration:
cf push tomcat-config
Part 2 modifies the app to configure the use of the external repository:
Edit the
manifest.yml
file by appending this URL-specific configuration to theapplications
section of themanifest.yml
file:env: JBP_CONFIG_TOMCAT: "{ tomcat: { external_configuration_enabled: true }, external_configuration: { repository_root: "http://tomcat-config.apps.yellow-green.cf-app.com" } }"
Substitute your complete URL for the URL in this example.
A complete
manifest.yml
file will appear similar to:--- applications: - name: http-session-caching path: build/libs/http-session-caching-0.0.1.war buildpack: java_buildpack_offline env: JBP_CONFIG_TOMCAT: "{ tomcat: { external_configuration_enabled: true }, external_configuration: { repository_root: "http://tomcat-config.apps.yellow-green.cf-app.com" } }"
Push, but do not start, your app:
cf push -f ./manifest.yml --no-start -b BUILDPACK-NAME
where
BUILDPACK-NAME
is the name you chose for your custom buildpack, or it is the URL of the most recent Java buildpack version, if you did not create a custom buildpack.The specification of the buildpack on the
cf push
command line takes precedence over specification within the manifest.For VMware Tanzu GemFire for VMs version 1.12 or 1.11, use the URL for the v4.35 buildpack if you did not create a custom buildpack. For the v4.35 buildpack, the
cf push
command becomes:$ cf push -f ./manifest.yml --no-start -b https://github.com/cloudfoundry/java-buildpack.git#v4.35
Bind and start your app:
cf bind-service APP-NAME SERVICE-INSTANCE-NAME cf start APP-NAME
To verify that near caching is disabled for the app, use
cf ssh
to access the app and visually verify thatenableLocalCache='false'
appears within thecontext.xml
file. Use this sequence of commands:cf ssh APP-NAME cat app/.java-buildpack/tomcat/conf/context.xml