Welcome to the BigMemory Max Online Documentation
About BigMemory Max
BigMemory Max Overview
What is BigMemory Max?
Basic Terms
Caching Basics
Will an Application Benefit from Caching?
How Much Will an Application Speed up with Caching?
Topology Types
Storage Tiers
Automatic Resource Control
Installation Guide
Installation Overview
Installation using the Software AG Installer
Performing the Standalone Installation of BigMemory Max
Configuring BigMemory Max
Working with Terracotta License Files
Starting the Terracotta Server and Management Console
Using Terracotta Products in Docker Containers
Upgrade and Migration Guide
Upgrading from 4.1/4.2 to 4.3
Summary of Changes from 4.1/4.2 to 4.3
Procedure for Upgrading from 4.1/4.2 to 4.3
Upgrading from 4.1 to 4.2
Procedure for Upgrading from 4.1 to 4.2
Installing Maintenance Version Upgrades for 4.2
Overview of Maintenance Version Upgrades for 4.2
Preparing for Maintenance Version Upgrades for 4.2
Installing Maintenance Version Upgrades for 4.2
Reverting TSAs to a Previous Version
Upgrading from 3.7 or 4.0
Summary of Changes from 4.0 to 4.1
Summary of Changes from 3.7 to 4.0
Procedure for Upgrading from 3.7 or 4.0
Tutorials
Hello World!
Basic CRUD
Searching
Sorting Results
Grouping Results
Adding the Server Array
Code Samples
About the BigMemory Max Code Samples
Example: Declarative Configuration
Example: Programmatic Configuration
Example: Create, Read, Update, Delete
Example: Search
Example: Nonstop/Rejoin
Example: Automatic Resource Control
Example: Using BigMemory Max As a Cache
Example: Nagios Integration
Product Documentation
BigMemory Max Developer Guide
Key Classes and Methods
About the Key Classes
CacheManager
Cache
Element
Basic Caching
Creating a CacheManager
Loading a Configuration
Adding and Removing Caches Programmatically
Performing Basic Cache Operations
Shut down the CacheManager
JUnit Tests
Cache Usage Patterns
Supported Usage Patterns
cache-aside
cache-as-sor
read-through
write-through
write-behind
Copy Cache
Searching a Cache
About Searching
Making a Cache Searchable
Defining Attributes
Creating a Query
Obtaining and Organizing Query Results
Best Practices for Optimizing Searches
Concurrency Considerations
Options for Working with Nulls
Searching with BigMemory SQL
About BigMemory SQL
Using BigMemory SQL
Using the QueryManager API
SQL Syntax and Examples
SELECT Clause
FROM Clause
WHERE Clause
Data Types
Enums
Dates
GROUP BY Clause
ORDER BY Clause
ORDER BY and GROUP BY Together
LIMIT Clause
Additional Syntax
Using Explicit Locking
About Explicit Locking
Code Sample for Explicit Locking
How Locking Works
The Locking API
Blocking and Self Populating Caches
About Blocking and Self-Populating Caches
Blocking Cache
SelfPopulatingCache
Transaction Support
About Transaction Support
Requirements for Transactional Caches
Configuring Transactional Cache
Working with Global Transactions
Failure Recovery
Sample Applications
Transaction Managers
Working with Local Transactions
Performance Considerations
Potential Timeouts in a Transactional Cache
Transactions in Write-Behind and Write-Through Caches
Support for Other Transaction Systems
Write-Through and Write-Behind Caches
About Write-Through and Write-Behind Caches
Using a Combined Read-Through and Write-Behind Cache
Write-Behind Sample Application
Configuring a Cache Writer
CacheWriterFactory Attributes
API
SPI
Monitoring the Size of Write-Behind Queue
Handling Exceptions that Occur After a Writer is Called
Bulk Loading
About Bulk Loading
Using the Bulk Load API
Bulk-Load Sample Code
Performance Improvement
Refresh Ahead
About Refresh Ahead
Inline Refresh Ahead
Scheduled Refresh Ahead
Implementing the CacheLoader
Cluster Events
About Cluster Events
Cluster Topology
Listening for Cluster Events
Troubleshooting
Cache Manager Event Listeners
About CacheManager Event Listeners
Configuring a Cache Manager Event Listener
Implementing a CacheManager Event Listener Factory and CacheManager Event Listener
Cache Event Listeners
About Cache Event Listeners
Configuring a Cache Event Listener
Implementing a Cache Event Listener Factory and Cache Event Listener
Adding a Listener Programmatically
Running Multiple Listeners on Separate Nodes
Cache Events in a Terracotta Cluster
Cache Exception Handlers
About Exception Handlers
Declarative Configuration
Implementing a Cache Exception Handler Factory and Cache Exception Handler
Programmatic Configuration
Cache Decorators
About Cache Decorators
Built-in Decorators
Creating a Decorator
Declarative Creation
Programmatic Creation
Adding Decorated Caches to a CacheManager
Cache Extensions
About Cache Extensions
Declarative Configuration
Implementing a Cache Extension Factory and Cache Extension
Programmatic Configuration
Class Loading
About Class Loading
Plugin Class Loading
Loading of ehcache.xml Resources
Working with Apache Maven
About Working with Apache Maven
Creating Enterprise Edition Clients
Using the tc-maven Plugin
Working With Terracotta SNAPSHOT Projects
Terracotta Repositories
BigMemory Max Configuration Guide
Planning a Successful Deployment
Configuring BigMemory Max
About BigMemory Max Configuration
XML Configuration
Dynamically Changing Cache Configuration
Dynamically Changing a Distributed Configuration
Passing Copies Instead of References
Configuring Storage Tiers
About Storage Tiers
Configuring Memory Store
Configuring Off-Heap Store
Off-Heap Configuration Examples
Tuning Off-Heap Store Performance
Configuring Disk Store
Sizing Storage Tiers
The Sizing Attributes
Pooling Resources Versus Sizing Individual Data Sets
Sizing Examples
Sizing Distributed Caches
Pinning and Size Limitations
Built-In Sizing Computation and Enforcement
Eviction When Using CacheManager-Level Storage
Managing Data Life
Configuration Options that Affect Data Life
Setting Expiration
Pinning Data
How Configuration Affects Element Flushing and Eviction
How Configuration Affects Eviction in Distributed Cache
Data Freshness and Expiration
Configuring Fast Restart (FRS)
About Fast Restart (FRS)
System Requirements
Data Persistence Implementation
Configuration Examples
Fast Restart Performance
Fast Restart Limitations
Defining a Distributed Configuration
About Distributed Configurations
Configuring a CacheManager
Terracotta Clustering Configuration Elements
terracotta
terracottaConfig
Embedding Terracotta Configuration
Incompatible Configuration Attributes
How Server Settings Can Override Client Settings
Controlling Cache Size
Cache Events Configuration
Copy On Read
Consistency Modes
Configuring Robust Distributed In-Memory Data Sets
Exporting Configuration from the Terracotta Management Console
Default Settings for a Distributed Configuration
Terracotta Server Array Properties
Terracotta Client Properties
Configuring Nonstop Operation
About Nonstop Operation
Configuring Nonstop Cache
Nonstop Timeouts and Behaviors
Tuning for Nonstop Timeouts and Behaviors
Nonstop Exceptions
Working with Transactions
About Transactional Caches
Strict XA (Support for All JTA Components)
XA (Basic JTA Support)
Local Transactions
Avoiding XA Commit Failures With Atomic Methods
Implementing an Element Comparator
Working with OSGi
Working With OSGi
Working with VMware vMotion
System Properties
Special System Properties
BigMemory Max Administrator Guide
About the Terracotta Server Array
What is the Terracotta Server Array?
New for BigMemory Max 4.x
Definitions and Functional Characteristics
Terracotta Server Array Architecture
Terracotta Cluster in Development
Terracotta Cluster with Reliability using Fast Restart (FRS)
Fast Restart (FRS) Disk Compaction Strategies
Terracotta Cluster with High Availability
Failover Tuning for Guaranteed Consistency
Scaling the Terracotta Server Array
Configuring the Terracotta Server Array
About Terracotta Server Configuration
How Terracotta Servers Get Configured
How Terracotta Clients Get Configured
Configuration in a Development Environment
Configuration in a Production Environment
Configuring the Terracotta Server Array
Binding Ports to Interfaces
Which Configuration?
Automatic Resource Management
What is Automatic Resource Management?
Eviction
Customizing the Eviction Strategy
Managing Near-Memory-Full Conditions
Behavior of the TSA under Near-Memory-Full Conditions
Restricted Mode Operations
Recovery
Monitoring Cluster Events
About Cluster Events
Event Types and Definitions
Backing Up Live In-Memory Data
About Live Backup
Creating a Backup
The Backup Directory
Restoring Data from a Backup
Clearing Data from a Terracotta Server
How to Clear Data from a Terracotta Server
Changing Topology of a Live Cluster
About Changing the Topology
Adding a New Server
Removing an Existing Server
Editing the Configuration of an Existing Server
Enabling Production Mode
Setting the Production Mode Property
Managing Distributed Garbage Collection
About Distributed Garbage Collection (DGC)
Running the Periodic Distributed Garbage Collection
Monitoring and Troubleshooting DGC
Starting the Terracotta Server as a Windows Service
Configuring the Terracotta Server to Run as a Service
Using BigMemory Hybrid
About BigMemory Hybrid
System Requirements
Hardware Capacity Guidelines
Configuring BigMemory Hybrid
Using the TMC with BigMemory Hybrid
Operator Events
Logging
SLFJ Logging
Recommended Logging Levels
Using Command Central to Manage Terracotta
Monitoring Terracotta BigMemory Max from Command Central
Troubleshooting a Secure Terracotta Server from Command Central
Commands that Terracotta Supports
Configuration Types that Terracotta Supports
Lifecycle Actions for Terracotta
Run-time Monitoring Statuses for Terracotta
Run-time Monitoring States for Terracotta
Operational Scripts
Archive Utility (archive-tool)
Database Backup Utility (backup-data)
Backup Status (backup-status)
Cluster Thread and State Dumps (debug-tool, cluster-dump)
Exit Safe Mode (exit-safe-mode)
Distributed Garbage Collector (run-dgc)
Start and Stop Server Scripts (start-tc-server, stop-tc-server)
Server Status (server-stat)
Version Utility (version)
Terracotta Configuration Parameters
The Terracotta Configuration File
The Servers Parameters
/tc:tc-config/servers
/tc:tc-config/servers/server
/tc:tc-config/servers/server/data
/tc:tc-config/servers/server/logs
/tc:tc-config/servers/server/index
/tc:tc-config/servers/server/data-backup
/tc:tc-config/servers/server/tsa-port
/tc:tc-config/servers/server/jmx-port
/tc:tc-config/servers/server/tsa-group-port
/tc:tc-config/servers/server/management-port
/tc:tc-config/servers/server/security
/tc:tc-config/servers/server/security/ssl/certificate
/tc:tc-config/servers/server/security/keychain
/tc:tc-config/servers/server/security/auth
/tc:tc-config/servers/server/security/management
/tc:tc-config/servers/server/authentication
/tc:tc-config/servers/dataStorage
/tc:tc-config/servers/mirror-group
/tc:tc-config/servers/garbage-collection
/tc:tc-config/servers/restartable
/tc:tc-config/servers/client-reconnect-window
The Clients Parameters
/tc:tc-config/clients/logs
BigMemory Max Security Guide
Overview of BigMemory Max Security
Introduction to Security
Authentication Mechanisms
Configuring Security Using LDAP (via JAAS)
Configuring Security Using JMX Authentication
Configuring SSL-based Security
User Roles
Using Scripts Against a Server with Authentication
Extending Server Security
About Security in a Cluster
Introduction
Security Related Files
Process Diagram
Setting Up Server Security
Basic Steps to Set Up Server Security
Creating the Server Certificates
Setting up the Server Keychain
Setting up Authentication/Authorization
Setting up Authorization for TMC Queries
Configuring Server Security
Enabling SSL on Terracotta Clients
How to Enable SSL Securing on the Client
Creating a Keychain Entry
Using a Client Truststore
Serialization: Securing Against Untrusted Clients
Setting Up a TSA to Use the Terracotta Management Server
Required Configuration
Configuring Identity Assertion
JMX Authentication Using the Keychain
Setting up the Security on the TMS
Securing TSA Access using a Permitted IP List
Restricting Clients to Specified Servers (Optional)
Running a Secured Server
Introduction
Confirming that Security is Enabled
Stopping a Secured Server
Troubleshooting
Using LDAP or Active Directory for Authentication
Introduction
Configuration Overview
Active Directory Configuration
Standard LDAP Configuration
Using the CDATA Construct
Using Encrypted Keychains
Introduction
Configuration Example
Configuring the Encrypted Server Keychain
Adding Entries to Encrypted Keychain Files
Configuring the Encrypted Client Keychain Files
Securing with the TMS
Reading the Keychain Master Password from a File
BigMemory Max High-Availability Guide
About High Availability
Overview of High-Availability Features
Basic High-Availability Configuration
Configuring High Availability Features
Configuring the HealthChecker Properties
About HealthChecker
HealthChecker Properties
How the HealthChecker Functions
Calculating HealthChecker Maximum
Configuration Examples
Tuning HealthChecker to Allow for Interruptions
Configuring Reconnection and Rejoin Properties
Automatic Server Instance Reconnect
Automatic Client Reconnect
Special Client Connection Properties
Using Rejoin to Reconnect Terracotta Clients
Effective Client-Server Reconnection Settings
Testing High-Availability Deployments
Designing and Testing Cluster Architecture
High-Availability Network Architecture and Testing
Deployment Configuration: Simple
Deployment Configuration: Fully Redundant
Terracotta Cluster Tests
Terracotta Management Console User Guide
Getting Started with Terracotta Management Console
About the Terracotta Management Console
Installing the Terracotta Management Server
Running the Terracotta Management Server with a Different Container
Configuring the Terracotta Management Server
Starting and Stopping the Terracotta Management Console
Starting the Terracotta Management Console
To Stop the Terracotta Management Console
Connecting to the Terracotta Management Console
Updating the Terracotta Management Server
Uninstalling the Terracotta Management Console
Using the Terracotta Management Console
Initial Setup
The TMC Home Page
Connections and Global Settings
Dashboards, Tabs, and Management Panels
Using the Application Data Tab
About the Application Data Tab
Overview Panel
Charts Panel
Sizing Panel
Management Panel
Contents Panel
Using the Monitoring Tab
About the Monitoring Tab
Runtime Statistics
Events
Versions
Using the Administration Tab
About the Administration Tab
Configuration
Backing Up Cluster Data
Changing Cluster Topology
Off-line Data
Using the Troubleshooting Tab
About the Troubleshooting Tab
Understanding Special TSA Modes
Generating Thread Dumps
Viewing Server Logs
Using the WAN Tab
About the WAN Tab
Overview Panel for Master Caches
Overview Panel for Replica Caches
Charts Panel for Master Caches
Charts Panel for Replica Caches
The WAN Tab Statistics
Setting up Security
Available Security Levels
No Security
Default Security
Basic Connection Security
Adding SSL
Certificate-Based Client Authentication
Forcing SSL Connections For TMC Clients
Setting up LDAP or Active Directory Authorization
Integrating with Nagios
About Integrating with Nagios XI
Example of a Shell Script Plugin
Integration with Prometheus
Connecting to Prometheus with Security disabled in TMC
Connecting to Prometheus with Security enabled in TMC
Prometheus Usage Notes
Cache Metrics
Server Metrics
Visualization with Grafana
Troubleshooting
Setup Errors
Connection Errors
Logged SSL Connection Errors
Runtime Errors
Display Errors
Terracotta REST Developer Guide
Using the Terracotta Managment REST API
Overview of the Management Components
Connecting to the Management Service REST API
REST API Versions
Constructing URIs for HTTP Operations
The URI for the Terracotta Management Service
Security for REST API usage without TMC
Special Resource Locations
Specifications for HTTP Operations
Response Headers
Examples of URIs
DELETE
GET and HEAD
OPTIONS
PUT
Using Query Parameters in URIs
Using Query Parameters in URIs
JSON Schema
JSON Schema
REST API for the Terracotta Server Array
REST API for TSA
Statistics
Topology Views
Configuration
Diagnostics
Backups
Operator Events
Logs
BigMemory Max Integrations
Using BigMemory Max with Hibernate
About Using BigMemory Max with Hibernate
Downloading and Installing BigMemory Max for Hibernate
Building with Maven
Configuring BigMemory Max as the Second-Level Cache Provider
Enabling Second-Level Cache and Query Cache Settings
Configuring Hibernate Entities to use Second-Level Caching
Configuring ehcache.xml Settings
Ehcache Settings for Domain Objects
Ehcache Settings for Collections
Ehcache Settings for Queries
The Demo Application and Tutorial
Performance Tips
Viewing Hibernate Statistics
FAQ
Using BigMemory Max with ColdFusion
About ColdFusion and BigMemory Max
Example Integration
Using BigMemory Max with Spring
Using Spring 3.1
Spring 2.5 to 3.1
Annotations for Spring Project
Using BigMemory Max with JSR107
About BigMemory Max Support for JSR107
Reference Documentation
Component Documentation
Reliability, High Availability and Failover Tuning
Web Sessions User Guide
About Web Sessions
What is Web Sessions?
Architecture
Installing and Configuring Web Sessions
Requirements
Installing the Session JARS
Configuring Your Web Sessions Cluster
Starting the Cluster
Configuring a Terracotta Cluster
Running the Shopping Cart Example
Starting the Example
Viewing the Example
Viewing the Session in Other VMs
Using Web Sessions
Optional Configuration Attributes
Managing Web Sessions Using JMX
Managing Web Sessions Using the REST API
Common Issues
BigMemory Max Best Practices
Tuning Off-Heap Store Performance
Tuning Heap Memory Performance
Common Causes of Failures in a Cluster
Manage Sessions in a Cluster
A Safe Failover Procedure
Safe Cluster Shutdown and Restart Procedures
Safe Cluster Shutdown and Restart Automation Guidelines
Safe Cluster Restart Automation Guidelines
FAQ
General Questions
Configuration, Development and Operations Questions
Environment and Interoperability Questions
Troubleshooting Questions
Specific Errors and Warnings
Welcome to the BigMemory Max Online Documentation
Specific Errors and Warnings