Tomcat Session State Caching

This topic explains Tomcat session state caching for apps with VMware Tanzu GemFire for Tanzu Application Service.

Tomcat, by default, stores all sessions and their data in memory. However, under certain circumstances, it may be beneficial to persist sessions and their data to a repository. This is particularly useful for small amounts of data that need to survive the failure of an individual instance. In such cases, the Java buildpack can automatically configure Tomcat to store sessions in GemFire for Tanzu Application Service.

The geode-store is a component within the Java buildpack that enables this functionality by integrating Tomcat with GemFire for Tanzu Application Service. It allows session data to be stored and managed in a distributed GemFire cluster, providing high availability, scalability, and data persistence. This ensures that session data remains consistent and accessible, even in the event of instance failures, enhancing the reliability of your application.

When deploying applications with session state caching, ensuring compatibility between the versions of Tomcat, GemFire, and the geode-store is crucial for optimal performance and reliability.

Confirm that you are using a Java buildpack version 4.30 or later.

Do not mix Tomcat session state caching with Spring Session Caching. Mixing Tomcat session state caching with Spring Session caching can cause issues.

Enable Session State Caching

To store session data in GemFire for Tanzu Application Service instead of Tomcat’s memory, specify the session-replication tag when creating or updating a service instance. Applications bound to this service operate within Tomcat instances, while a dedicated region named gemfire_modules_sessions is created in GemFire for Tanzu Application Service to manage session storage. Sessions automatically expire after 30 minutes.

To enable Tomcat session state caching, choose one of the following options:

Option 1: Create a service instance with the session-replication tag:

$ cf create-service p-cloudcache small-plan my-service-instance -t session-replication

Option 2: Update your service instance to include the session-replication tag:
```
$ cf update-service new-service-instance -t session-replication
```
Option 3: Include session-replication anywhere in the service instance name when creating the service:
```
 $ cf create-service p-cloudcache small-plan my-service-instance-session-replication
 
```

Java Buildpack Compatibility

Tomcat Version

When deploying applications with session state caching in GemFire for Tanzu Application Service, you might encounter the following warning:

WARNING: Tomcat version X does not match Geode Tomcat Y module. If you
encounter compatibility issues, please make sure these versions match.

This warning indicates an issue that needs to be addressed if your version of Tomcat is significantly older (such as a Tomcat version prior to version 8) than the current default Tomcat version specifications.

You can fix this warning by changing the version of Tomcat being used by the Java buildpack in one of two ways:

Create a Custom Buildpack and modify the version of Tomcat in your custom buildpack.
Specify the online buildpack in the app’s manifest.yml file, and set an environment variable in the app’s manifest.yml file as described in the Java Buildpack Configuration and Extension README.

For example:

    ```
    buildpacks:
      - https://github.com/cloudfoundry/java-buildpack.git#v4.37
    env:
      JBP_CONFIG_TOMCAT: '{ tomcat: { version: 9.0.+ } }'
    ```

For a full list of environment variables related to configuring Tomcat in the Java buildpack, see Tomcat Container Configuration.

geode-store Version

The following table shows the corresponding Java buildpack and geode-store versions. Each version of Tanzu Application Service for VMs comes with a Java buildpack, which includes the specified version of the geode-store. Refer to the Tanzu Application Service for VMs release notes to determine which version of the java-offline-buildpack is included with the release.

For compatibility, VMware recommends using Java buildpacks configured with a geode-store version that aligns with the GemFire for Tanzu Application Service version you’re using. The latest Java buildpack version comes with a geode-store version of 1.14.9, as shown in the following table.

If you’re using GemFire for Tanzu Application Service version 2.0 or above, it’s advisable to create a custom buildpack using the instructions provided in the following section to ensure compatibility and optimal performance.

Java Build Pack	geode-store
4.61.1-4.7.0	1.14.9
4.57-4.61.0	1.13.7
4.48.1-4.56	1.12.5
4.46-4.48.0	1.12.4
4.44-4.45	1.13.4
4.37-4.43	1.11.0
4.36	1.13.0
4.30-4.35	0.0.2

Specify a Different Java Buildpack or geode-store Version

As noted earlier, there may be times when you need to specify a different version of the geode-store. For example, if your Java buildpack specifies a geode_store version greater than your GemFire for Tanzu Application Service version, you need to specify a lower geode_store version. The geode_store version must be less than or equal to the GemFire for Tanzu Application Service version.

You can find the comprehensive list of geode_store versions at https://java-buildpack-tomcat-gemfire-store.s3-us-west-2.amazonaws.com/index.yml.

If you use the java_offline_buildpack, you cannot change the geode_store value by using environment variables. You must either use an online version of the Java Buildpack alongside the environment variable or create a custom buildpack that specifies the version as described in Create a Custom Buildpack.

There are three ways to specify and use a different buildpack or geode-store:

Option 1: Replace the VMware Tanzu Application Service for VMs environment’s Java buildpack:
1. Log in using cf login, targeting the correct org and space.
2. Delete the current Tanzu Application Service for VMs environment’s offline Java buildpack:
```
cf delete-buildpack java_buildpack_offline
```
3. Log in to the Broadcom Customer Support Portal with your customer credentials. For more information about login requirements, see the Download Broadcom products and software article.
4. Go to My Downloads on the left hand side navigation.com.
5. At the top you should see My Downloads - Tanzu. If you do not see this, make sure you have selected Tanzu in the drop-down menu to the left of your username.
6. On the My Downloads - Tanzu page, search for Java Buildpack. Make sure to select Java Buildpack and NOT the Java Buildpack for VMware Tanzu.
7. Click on Java Buildpack in the table to show the available versions, and select the version needed for your project.
8. Click I agree to Terms and Conditions. Click the HTTPS Download icon next to the Java Buildpack (offline) to download.
9. Upload the replacement Java buildpack (offline) to your Tanzu Application Service for VMs environment. This following example specifies a version 4.70 buildpack:
```
cf create-buildpack java_buildpack_offline /PATH/TO/java-buildpack-offline-v4.70.zip POSITION
```
  Where POSITION is the order in which this buildpack will be selected.
Option 2: Specify BOTH a geode_store version environment variable and an online buildpack for your application.

Choose one of the following two ways to set the geode_store version environment variable.
- Set the geode_store version environment variable in your application’s manifest.yml file. For example:
```
env:
  JBP_CONFIG_TOMCAT: '{ geode_store: { version: 2.1.0 } }'
```
  For details about specifying configuration values with an environment variable in the Java Buildpack, see Configuration and Extension in the Cloud Foundry Java Buildpack repository in GitHub.
  
  You can find the buildpack’s geode_store version in the buildpacks /config directory: /config/tomcat.yml file.
- Or you can set the geode_store version environment variable with the cf set-env command. For more information about this command, see set-env in the Cloud Foundry CLI Reference Guide.
Choose one of the following two ways to specify an Online Buildpack:
- Specify an online buildpack in your application’s manifest.yml file. For example:
```
buildpacks:
  - https://github.com/cloudfoundry/java-buildpack.git#v4.70
```
- Or specify an online buildpack in the cf push command of your application.
Option 3: Create a custom buildpack that specifies the version as described in Create a Custom Buildpack.

Deactivate 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 Tanzu GemFire session state caching have near caching by default. To keep an app stateless, deactivate near caching.

If you are not using an external repository for configuration, Create a Custom Buildpack to deactivate near caching.

Create a Custom Buildpack

If your GemFire for Tanzu Application Service 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 [email protected]:cloudfoundry/java-buildpack.git

Navigate to the newly-created cloned repository:
```
$ cd java-buildpack
```
Check out the desired version or release of the java-buildpack repository on a local branch. Use v4.70 or the most recent version available.
To change the version of GemFire for Tanzu Application Service used by the buildpack, edit the /config/tomcat.yml configuration file to specify the geode_store. Here is the portion of the file to be changed, with the string to change in bold:
```
geode_store:
  version: 2.1.0
  repository_root: https://java-buildpack-tomcat-gemfire-store.s3-us-west-2.amazonaws.com
```
For GemFire for Tanzu Application Service version 1.11 - 2.1.0 and greater, set the geode_store version to match your GemFire for Tanzu Application Service minor version.

For all previous versions of GemFire for Tanzu Application Service, set the geode_store version to 0.0.2.

Here is a complete list of geode_store versions.
If you changed the version of GemFire for Tanzu Application Service 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 current geode_store version:
```
SESSION_MANAGER_CLASS_NAME = 'org.apache.geode.modules.session.catalina.Tomcat9DeltaSessionManager'
```
- For geode_store versions 1.11 and greater, use Tomcat9DeltaSessionManager.
- For geode_store versions earlier than 1.11, including version 0.0.2, use Tomcat8DeltaSessionManager.

To deactivate near caching within the custom buildpack, edit the java-buildpack repository file lib/java_buildpack/container/tomcat/tomcat_geode_store.rb to deactivate caching within the app. Change the string true to false.

Before the change, here is the portion of the file to be modified, 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 to false, here is the updated portion of the file:

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 Tanzu Application Service for VMs with the following command:
```
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. * POSITION 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 by placing the custom configuration in a repository. This approach not only allows for easier customization but also facilitates maintaining a single configuration that can be used across multiple applications. By using an external repository for configuration, you ensure consistency and reduce the effort required to manage configurations for various apps.

There are two parts to using an external repository:

Part 1: Building the Repository

Create a directory to hold the configuration:
```
$ mkdir tomcat-config
```

Create the necessary files and directories within the new 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 with the following content. This example specifies Tomcat version 9 and deactivates 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 further customize Tomcat by placing additional configuration files within the tomcat-1.0.0/conf directory.

Compress the tomcat-1.0.0 directory into a TAR file and move it to the public 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, use cf push to place the configuration into the VMware Tanzu Application Service for VMs space that will host the app:
```
$ cf push tomcat-config
```
Get the URL of the tomcat-config app:
```
$ cf apps
```
Prepend the listed URL with http:// to get the URL to identify the location of the configuration needed by the app. For example, http://tomcat-config.apps.yellow-green.cf-app.com.
Edit public/index.yml in the tomcat-config directory to include the URL-specific contents:
```
---
1.0.0: http://tomcat-config.apps.yellow-green.cf-app.com/tomcat-1.0.0.tar.gz
```
Push the configuration again with the completed configuration:
```
cf push tomcat-config
```

Part 2: Modifying the App to Use the External Repository

Edit the manifest.yml file to include the URL-specific configuration in the applications section of the manifest.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 example URL.

A complete manifest.yml file looks like this:

---
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
```
Replace BUILDPACK-NAME with the name of your custom buildpack or the URL of the most recent Java buildpack version if you did not create a custom buildpack.

Note The specification of the buildpack on the cf push command line takes precedence over the specification within the manifest.

Bind and start your app:

cf bind-service APP-NAME SERVICE-INSTANCE-NAME

cf start APP-NAME

Verify that near caching is deactivated by checking enableLocalCache='false' in the context.xml file:
```
cf ssh APP-NAME

cat app/.java-buildpack/tomcat/conf/context.xml
```