### Start Pre-activated Terracotta Server via CLI

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/server/README.md

Starts a node with specific configuration, log directories, and auto-activation enabled.

```bash
docker run -d \
  -p 9410:9410 \
  -h ehcache-terracotta-server \
  --network terracotta-net \
  --name ehcache-terracotta-server \
  ehcache-terracotta-server:@version@ \
  -config-dir "/terracotta/run/config" \
  -failover-priority availability \
  -offheap-resources "offheap-1:512MB,offheap-2:512MB" \
  -name "ehcache-terracotta-server" \
  -hostname "ehcache-terracotta-server" \
  -log-dir "/terracotta/run/logs" \
  -cluster-name "tc-cluster" \
  -auto-activate
```

--------------------------------

### Start Terracotta Server with Default Settings

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/server/README.md

Starts the container with default offheap resources and configuration paths.

```bash
docker run -d \
  -p 9410:9410 \
  -h ehcache-terracotta-server \
  --network terracotta-net \
  --name ehcache-terracotta-server \
  ehcache-terracotta-server:@version@
```

--------------------------------

### Start Ehcache Node with Persistence

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/server/README.md

Start a node in ACTIVE state with persistent storage and configuration mounts.

```bash
docker run -d \
  -v /path/to/run-directory:/terracotta/run:rw \
  -v /path/to/config-directory:/terracotta/config:ro \
  -e DEFAULT_ACTIVATE="true" \
  -p 9410:9410 \
  -h ehcache-terracotta-server \
  --network terracotta-net \
  --name ehcache-terracotta-server \
  ehcache-terracotta-server:@version@
```

--------------------------------

### Start Terracotta Server with Custom Arguments

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/server/README.md

Starts the server by passing CLI arguments directly, bypassing default environment variable settings.

```bash
docker run -d \
  -p 9410:9410 \
  -h ehcache-terracotta-server \
  --network terracotta-net \
  --name ehcache-terracotta-server \
  ehcache-terracotta-server:@version@ \
  <arguments>
```

--------------------------------

### Configure XSD Locations in XML

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xsds.adoc

Example showing how to define XSD locations within an XML configuration file.

```xml
include::{sourcedir310}/ehcache-107/src/test/resources/org/ehcache/docs/public-xsds-location.xml[tag=xsdLocations]
```

--------------------------------

### Run Terracotta Server

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/README.md

Starts the server container interactively in consistency mode.

```bash
docker run -it --rm \
  -e DEFAULT_ACTIVATE="true" \
  -e DEFAULT_FAILOVER="consistency:1" \
  -h ehcache-terracotta-server \
  --network terracotta-net \
  --name ehcache-terracotta-server \
  --user 1234:0 \
  ehcache-terracotta-server:@version@
```

--------------------------------

### Basic JCache Configuration with Ehcache

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/107.adoc

Demonstrates how to retrieve the default CachingProvider, get a CacheManager, configure a cache with specific types and expiry, and then create and use the cache.

```java
CachingProvider provider = Caching.getCachingProvider();
CacheManager cacheManager = provider.getCacheManager();

MutableConfiguration<Long, String> config = new MutableConfiguration<>();
config.setTypes(Long.class, String.class)
      .setStoreByValue(false)
      .setExpiry(ExpiryPolicy.ETERNAL, new TouchedExpiryPolicy(Duration.ONE_MINUTE));

Cache<Long, String> jCache = cacheManager.createCache("jCache", config);

jCache.put(1L, "data1");
String value = jCache.get(1L);
System.out.println("Retrieved value: " + value);
```

--------------------------------

### Configure Simple XA Cache in Java

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xa.adoc

Basic setup for an XA transactional cache using the Bitronix transaction manager.

```java
include::{sourcedir310}/ehcache-transactions/src/test/java/org/ehcache/docs/transactions/xa/XAGettingStarted.java[tag=testSimpleXACache]
```

--------------------------------

### Start Terracotta Server with Environment Variables

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/server/README.md

Configures the server using environment variables for offheap resources, cluster naming, and failover priority.

```bash
docker run -d \
  -e DEFAULT_OFFHEAP="offheap-1:512MB,offheap-2:512MB,offheap-3:512MB" \
  -e DEFAULT_CLUSTER_NAME="tc-cluster" \
  -e DEFAULT_ACTIVATE="true" \
  -e DEFAULT_FAILOVER="availability" \
  -p 9410:9410 \
  -h ehcache-terracotta-server \
  --network terracotta-net \
  --name ehcache-terracotta-server \
  ehcache-terracotta-server:@version@
```

--------------------------------

### Implementing Write-Through Cache in Java

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/writers.adoc

Demonstrates registering a CacheLoaderWriter for write-through behavior. This example shows how a cache entry is loaded and written to the system of record.

```java
Cache<String, String> cache = cacheManager.createCache("writeThroughCache",
    new CacheConfiguration<String, String>()
        .add(new CacheLoaderWriterConfiguration<String, String>(MyLoaderWriter.class))
);

// Cache miss, delegates to CacheLoaderWriter.load("41L")
String value = cache.get("41L");

// Cache hit, delegates to CacheLoaderWriter.write("41L", "zero")
cache.put("41L", "zero");

```

--------------------------------

### Multi-Tier Cache Setup (Heap, Offheap, Clustered)

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/tiering.adoc

Configure a CacheManager with three tiers: Heap, Offheap, and Clustered. This setup requires specific configurations for connecting to the Terracotta cluster and defining each tier's resources.

```java
CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .with(CacheManagerBuilder.clustered(TERRACOTTA_URI).autoCreate()) 
    .withCache("three-tiers-cache",
        CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, 
            newResourceConfiguration("heap://a")
            .append(newResourceConfiguration("offheap://a"))
            .append(newResourceConfiguration("clustered://a/my-resource"))))
    .build(true);
```

--------------------------------

### Basic User Managed Cache Lifecycle Example

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/usermanaged.adoc

Demonstrates the lifecycle of a basic UserManagedCache, including explicit initialization and closing. Pass 'true' to the builder to auto-initialize.

```java
    @Test
    public void userManagedCacheExample() {
        // tag::userManagedCacheExample[]
        UserManagedCache<Long, String> cache = UserManagedCacheBuilder.userManagedCache(CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, newHeapCacheConfiguration(100, MemoryUnit.MEGABYTES)).build(), false);

        // <1> Create a UserManagedCache instance. Pass 'false' to manually init.
        // <2> Explicitly initialize the cache before use.
        cache.init();

        // <3> Use the cache as usual.
        cache.put(1L, "one");
        assertThat(cache.get(1L), is("one"));

        // <4> Explicitly close the cache to release resources.
        cache.close();
        // end::userManagedCacheExample[]
    }

```

--------------------------------

### Run Peeper with Cache-aside Caching

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/examples.adoc

Builds and runs the Peeper application that utilizes Ehcache for cache-aside. This involves starting a Jetty web service.

```bash
./gradlew :demos:01-CacheAside:run
```

--------------------------------

### Configure XA Cache with Three Tiers and Persistence

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xa.adoc

This example demonstrates setting up an XA transactional cache with persistence, enabling in-doubt transaction recovery across restarts. It includes configuring the transaction manager, persistence, and the XA store.

```java
TransactionManager transactionManager = BtmUtils.createTransactionManager();

CacheManager cacheManager = CacheManagerBuilder.newCacheManager(new TransactionManagerProvider() {
    @Override
    public TransactionManager getTransactionManager() {
        return transactionManager;
    }
});

PersistenceConfiguration persistenceConfiguration = new PersistenceConfiguration("/path/to/persistence");

XAStoreConfiguration xaStoreConfig = new XAStoreConfiguration("my-xa-resource");

Cache<Long, String> xaCache = cacheManager.createCache("xaCache",
    CacheConfigurationBuilder.newConfiguration(Long.class, String.class)
        .add(persistenceConfiguration)
        .add(xaStoreConfig));

transactionManager.begin();
try {
    xaCache.put(1L, "value1");
    transactionManager.commit();
} catch (Exception e) {
    transactionManager.rollback();
    throw e;
}
```

--------------------------------

### Start Next Ehcache Version Script

Source: https://github.com/ehcache/ehcache3/wiki/dev.release

Use this script to prepare the repository for the next major.minor version of Ehcache. This helps in managing the transition of development efforts.

```bash
./start_next_version.sh
```

--------------------------------

### XML Cache Template Definition

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xml.adoc

Example XML fragment defining a cache template named 'example' with a capacity constraint.

```xml
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.ehcache.org/v3 http://www.ehcache.org/schema/ehcache-core-3.0.xsd"
         xmlns="http://www.ehcache.org/v3">

    <cache-template name="example">
        <key-type>java.lang.Long</key-type>
        <value-type>java.lang.String</value-type>
        <resources>
            <heap unit="entries">200</heap>
        </resources>
    </cache-template>

    <cache name="myCache" uses-template="example"/>
</ehcache>
```

--------------------------------

### Ehcache 107 Extension XML Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/examples.adoc

An example XML configuration file demonstrating the use of the 107 extension in Ehcache.

```xml
include::{sourcedir310}/ehcache-107/src/test/resources/ehcache-example.xml[]
```

--------------------------------

### Configure a 3-Tier Cache with ResourcePoolsBuilder

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/tiering.adoc

Example demonstrating the creation of a cache with three tiers (heap, offheap, disk) using ResourcePoolsBuilder. The order of tier declaration does not affect the final configuration due to tier heights.

```java
CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .withCache("threeTieredCache",
        CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class)
            .build(ResourcePoolsBuilder.newResourcePoolsBuilder()
                .heap(100, MemoryUnit.MB)
                .offheap(500, MemoryUnit.MB)
                .disk(1, MemoryUnit.GB, "myDiskStorePath")
            )
    )
    .build(true);
```

--------------------------------

### Ehcache Unspecified Clustered Cache Inheritance Example

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/clustered-cache.adoc

Java code demonstrating how to configure a cache manager with auto-create on reconnect and then create caches using both dedicated and unspecified clustered resource pools.

```java
final String CACHE_NAME = "my-dedicated-cache";

// Configure the first cache manager with auto create on reconnect
CacheManager cacheManager1 = CacheManagerBuilder.newCacheManagerBuilder()
    .store(ClusteredStoreConfigurationBuilder.withClusteredStoreServiceConfiguration(CacheManagerBuilder.persistenceHandler("my-cache-manager")))
    .build(true);

// Build a cache configuration for a clustered `dedicated` resource pool
Configuration cacheManagerConfig1 = new ConfigurationBuilder()
    .addDefaultServerStoreService(new ClusteredStoreConfiguration("my-cache-manager", "my-dedicated-resource"))
    .build();

// Create cache `my-dedicated-cache` using the cache configuration
cacheManager1.createCache(CACHE_NAME, CacheConfigurationBuilder.newCacheConfiguration(Long.class, String.class)
    .add(cacheManagerConfig1.getServiceConfiguration(ClusteredStoreConfiguration.class))
);

// Configure the second cache manager as _expecting_
CacheManager cacheManager2 = CacheManagerBuilder.newCacheManagerBuilder()
    .store(ClusteredStoreConfigurationBuilder.withClusteredStoreServiceConfiguration(CacheManagerBuilder.persistenceHandler("my-cache-manager")))
    .build(true);

// Build a cache configuration for a clustered _unspecified_ resource pool, which will use the previously configured clustered _dedicated_ resource pool.
Configuration cacheManagerConfig2 = new ConfigurationBuilder()
    .addDefaultServerStoreService(new ClusteredStoreConfiguration("my-cache-manager"))
    .build();

// Create cache with the same name `my-dedicated-cache` and use the clustered _unspecified_ cache configuration
cacheManager2.createCache(CACHE_NAME, CacheConfigurationBuilder.newCacheConfiguration(Long.class, String.class)
    .add(cacheManagerConfig2.getServiceConfiguration(ClusteredStoreConfiguration.class))
);

cacheManager1.close();
cacheManager2.close();
```

--------------------------------

### Run Peeper without Caching

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/examples.adoc

Builds and runs the base Peeper application that does not use caching. This involves starting a Jetty web service.

```bash
./gradlew :demos:00-NoCache:run
```

--------------------------------

### Load CacheManager from XML Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xa.adoc

This Java code demonstrates how to load an Ehcache CacheManager using an XML configuration file. It requires the Bitronix transaction manager to be started before initializing the CacheManager.

```java
URL xmlConfig = getClass().getResource("/docs/configs/xa-getting-started.xml");
XmlConfiguration xmlConfiguration = new XmlConfiguration(xmlConfig);

CacheManager cacheManager = CacheManagerBuilder.newCacheManager(xmlConfiguration);
cacheManager.init();
```

--------------------------------

### Ehcache 2.x Per Mapping Expiry Example

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/migration-guide.adoc

Demonstrates creating a cache manager with a default time-to-live (TTL) expiry in Ehcache 2.x. It shows how to verify and set expiry on an Element only when it differs from the Cache expiry.

```java
int defaultCacheTTLInSeconds = 20;

CacheManager cacheManager = initCacheManager();
CacheConfiguration cacheConfiguration = new CacheConfiguration().name("cache")
    .maxEntriesLocalHeap(100)
    .timeToLiveSeconds(defaultCacheTTLInSeconds);   // <1>
cacheManager.addCache(new Cache(cacheConfiguration));

Element element = new Element(10L, "Hello");

int ttlInSeconds = getTimeToLiveInSeconds((Long)element.getObjectKey(), (String)element.getObjectValue()); // <2>

if (ttlInSeconds != defaultCacheTTLInSeconds) {   // <3>
  element.setTimeToLive(ttlInSeconds);
}

cacheManager.getCache("cache").put(element);

System.out.println(cacheManager.getCache("cache").get(10L).getObjectValue());

sleep(2100);  // <4>

// Now the returned element should be null, as the mapping is expired.
System.out.println(cacheManager.getCache("cache").get(10L));
```

--------------------------------

### Activate Cluster with Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/config-tool/README.md

Activate a cluster by mounting a local configuration directory and providing the path to the cluster configuration file.

```bash
docker run -it --rm \
  -v /path/to/config-directory:/terracotta/config:ro \
  --network terracotta-net \
  ehcache-terracotta-config-tool:@version@ \
  activate -config-file /terracotta/config/cluster.cfg
```

--------------------------------

### Configure XA Write-Through Cache in Java

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xa.adoc

Setup for an XA transactional cache with a CacheLoaderWriter for write-through operations.

```java
include::{sourcedir310}/ehcache-transactions/src/test/java/org/ehcache/docs/transactions/xa/XAGettingStarted.java[tag=testXACacheWithWriteThrough]
```

--------------------------------

### Define Cache Template in XML

Source: https://github.com/ehcache/ehcache3/blob/master/ehcache-xml/README.adoc

Example of a cache-template element defined within an Ehcache XML configuration file.

```xml
<ehcache:cache-template name="example">
  <ehcache:capacity>120</ehcache:capacity>
</ehcache:cache-template>
```

--------------------------------

### Initialize CacheManager with Static Imports

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/getting-started.adoc

Demonstrates using try-with-resources for automatic closure and static imports for builders.

```java
include::{sourcedir310}/integration-test/src/test/java/org/ehcache/docs/GettingStartedWithStaticImports.java[tag=java7Example]
```

--------------------------------

### Ehcache Clustered XML Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/clustered-cache.adoc

XML configuration for a clustered Ehcache setup, specifying consistency levels via custom service configuration.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://www.ehcache.org/v3"
        xmlns:clustered="http://www.ehcache.org/v3/clustered">

    <service>
        <clustered:cache-manager-configuration>
            <clustered:consistency>
                <clustered:strong/>
            </clustered:consistency>
        </clustered:cache-manager-configuration>
    </service>

    <cache alias="my-clustered-cache">
        <key-type>java.lang.Long</key-type>
        <value-type>java.lang.String</value-type>
        <resources>
            <clustered:resource name="my-clustered-resource"/>
        </resources>
    </cache>
</config>
```

--------------------------------

### Execute Ehcache Deployment Script

Source: https://github.com/ehcache/ehcache3/wiki/dev.release

Launch the main deployment script from the root of the Ehcache source directory to initiate the release process.

```bash
./deploy.sh
```

--------------------------------

### Update Cache Configuration by Adding Resource

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/config-derive.adoc

Modify an existing cache's configuration by applying a UnaryOperator to its builder, for example, to add an offheap resource.

```java
Configuration configuration = CacheManagerBuilder.newCacheManagerBuilder().build(false).getConfiguration();
Configuration.DeriveResult deriveResult = configuration.derive();
ConfigurationBuilder builder = deriveResult.getBuilder().updateCache("cache", cacheConfiguration -> cacheConfiguration.add(ResourcePoolsBuilder.newResourcePoolsBuilder().offheap(100, MemoryUnit.MB)));
```

```xml
<ehcache>
  <cache alias="cache">
    <key-type>Long.class</key-type>
    <value-type>Object.class</value-type>
    <heap>10</heap>
  </cache>
</ehcache>
```

```xml
<ehcache>
  <cache alias="cache">
    <key-type>Long.class</key-type>
    <value-type>Object.class</value-type>
    <resources>
      <heap>10</heap>
      <offheap unit="MB">100</offheap>
    </resources>
  </cache>
</ehcache>
```

--------------------------------

### Create Docker Network

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/README.md

Initializes a network for the Terracotta containers to communicate.

```bash
docker network create terracotta-net
```

--------------------------------

### Get Ehcache RuntimeConfiguration from JCache MutableConfiguration

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/107.adoc

Access the underlying Ehcache `CacheRuntimeConfiguration` from a JCache `MutableConfiguration` by unwrapping through JCache's `CompleteConfiguration` and the configuration bridge.

```java
MutableConfiguration<String, String> mutableConfig = new MutableConfiguration<>();

// Get to the JCache CompleteConfiguration
CompleteConfiguration<String, String> completeConfig = mutableConfig;

// Get to the configuration bridge connecting Ehcache and JCache
// This step is conceptual and depends on the specific bridge implementation if not directly available

// Unwrap to the Ehcache CacheRuntimeConfiguration type
// This would typically involve a cast or a specific method provided by the bridge
// For example, if 'completeConfig' were an Ehcache-specific wrapper:
// CacheRuntimeConfiguration<String, String> ehcacheConfig = ((EhcacheCompleteConfiguration<?, ?>) completeConfig).unwrap(CacheRuntimeConfiguration.class);
```

--------------------------------

### Run Config-Tool Image

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/README.md

Tests the configuration tool image by running a diagnostic command against the server.

```bash
docker run -it --rm \
  --network terracotta-net \
  --user 1234:0 \
  ehcache-terracotta-config-tool:@version@ diagnostic -connect-to ehcache-terracotta-server
```

--------------------------------

### BitronixTransactionManagerLookup Implementation

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xa.adoc

This Java class implements the TransactionManagerLookup interface for Bitronix. It provides a no-argument constructor and returns a TransactionManagerWrapper, ensuring the Bitronix transaction manager is started.

```java
public class BitronixTransactionManagerLookup implements TransactionManagerLookup {

    public BitronixTransactionManagerLookup() {
        // Ensure BTM is started
        BtmUtils.ensureBtmStarted();
    }

    @Override
    public TransactionManagerWrapper lookupTransactionManagerWrapper() {
        TransactionManager tm = TransactionManagerLocator.getTransactionManager();
        return new TransactionManagerWrapper(tm, XAResourceRegistry.instance());
    }
}
```

--------------------------------

### Configure Disk Store Thread Pools

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/thread-pools.adoc

Demonstrates configuring thread pools for disk stores, including setting a default pool and a specific pool for a cache.

```java
PooledExecutionServiceConfigurationBuilder pooledExecutionServiceConfigurationBuilder = PooledExecutionServiceConfigurationBuilder.newPooledExecutionServiceConfigurationBuilder()
    .defaultPool("dflt", 1, 10)
    .pool("diskPool", 2, 5);

CacheManagerBuilder<PersistentCacheManager> config = CacheManagerBuilder.newCacheManagerBuilder()
    .using(pooledExecutionServiceConfigurationBuilder.build())
    .using(new OffHeapDiskStoreProviderConfiguration("diskPool")); // <2>

CacheConfiguration<Long, String> cacheConfiguration = CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
    ResourcePoolsBuilder.newResourcePoolsBuilder().disk(10, MemoryUnit.MB, true))
    .add(new OffHeapDiskStoreConfiguration("diskPool")) // <3>
    .build();
```

--------------------------------

### Configure EvictionAdvisor in Ehcache

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/eviction-advisor.adoc

Demonstrates how to configure an EvictionAdvisor instance within a cache configuration to influence eviction behavior.

```java
CacheConfiguration<Long, String> cacheConfiguration = CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
    ResourcePoolsBuilder.heap(2)) // <1>
    .withEvictionAdvisor(new OddKeysEvictionAdvisor<Long, String>()) // <2>
    .build();
```

--------------------------------

### Configure Cache Event Listener

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/cache-event-listeners.adoc

Register a CacheEventListenerConfiguration to receive specific cache events during cache setup. Events can be filtered by type, and delivery mode can be specified.

```java
CacheEventListenerConfiguration cacheEventListenerConfig = CacheConfigurationBuilder.newCacheEventListenerConfiguration()
    .forType(MyCacheEventListener.class)
    .as(CacheEventListener.class)
    .withEvent(CacheEvent.ON_CREATE)
    .withEvent(CacheEvent.ON_UPDATE);

CacheConfiguration cacheConfig = CacheConfigurationBuilder.newCacheConfigurationBuilder()
    .add(cacheEventListenerConfig)
    .build();
```

--------------------------------

### XML Configuration ClassLoader

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/class-loading.adoc

Explains how to configure ClassLoaders using XML, including different constructor options.

```APIDOC
## XML Configuration ClassLoader

### Description
When using XML to configure Ehcache, custom types are referenced by their fully qualified class name. This requires a `ClassLoader` to transform these names into class representations.
The `XmlConfiguration` class provides constructors to specify `ClassLoader` instances.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Query Parameters
- **url** (URL) - Required - The URL to the XML configuration file.

#### Request Body
N/A

### Request Example
N/A

### Response
N/A

### Constructors
- `public XmlConfiguration(URL url)`: Uses the default ClassLoader.
- `public XmlConfiguration(URL url, final ClassLoader classLoader)`: Uses a specific ClassLoader at the CacheManager level.
- `public XmlConfiguration(URL url, final ClassLoader classLoader, final Map<String, ClassLoader> cacheClassLoaders)`: Uses a specific ClassLoader at the CacheManager level and a map of `<String, ClassLoader>` for specific Caches by alias.
```

--------------------------------

### Ehcache JSR107 XML Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/107.adoc

An example of an Ehcache XML configuration file used for JCache integration. This allows for cache configuration without direct code dependency on Ehcache as the provider.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://www.ehcache.org/v3" xmlns:jsr107="http://www.ehcache.org/v3/jsr107">

    <service ref="org.ehcache.jsr107.EhcacheCachingProvider">
        <providedService>
            <jsr107:defaults enable-statistics="true" enable-management="true"/>
        </providedService>
    </service>

    <cache alias="stringCache">
        <key-type>java.lang.String</key-type>
        <value-type>java.lang.String</value-type>
        <resources>
            <heap unit="entries">1000</heap>
        </resources>
    </cache>

    <cache alias="overrideCache" >
        <key-type>java.lang.String</key-type>
        <value-type>java.lang.String</value-type>
        <resources>
            <heap unit="entries">1000</heap>
        </resources>
        <jsr107:cache enable-statistics="false" enable-management="false"/>
    </cache>

    <cache alias="overrideOneCache" >
        <key-type>java.lang.String</key-type>
        <value-type>java.lang.String</value-type>
        <resources>
            <heap unit="entries">1000</heap>
        </resources>
        <jsr107:cache enable-statistics="false"/>
    </cache>

</config>
```

--------------------------------

### Build Ehcache Docker Images

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/README.md

Builds the server, config-tool, and voter images from the root of the Ehcache kit.

```bash
docker build -f docker/server/Dockerfile -t ehcache-terracotta-server:@version@ .
docker build -f docker/config-tool/Dockerfile -t ehcache-terracotta-config-tool:@version@ .
docker build -f docker/voter/Dockerfile -t ehcache-terracotta-voter:@version@ .
```

--------------------------------

### Import Cluster Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/config-tool/README.md

Import a cluster configuration file into a specific node by connecting to the Terracotta server.

```bash
docker run -it --rm \
  -v /path/to/config-directory:/terracotta/config:ro \
  --network terracotta-net \
  ehcache-terracotta-config-tool:@version@ \
  import -config-file /terracotta/config/cluster.cfg -connect-to ehcache-terracotta-server
```

--------------------------------

### Adding Write-Behind to Cache in Java

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/writers.adoc

Configures a cache with write-behind functionality using WriteBehindConfigurationBuilder. This example sets batch size, maximum write delay, queue size, concurrency level, and enables coalescing.

```java
Cache<String, String> cache = cacheManager.createCache("writeBehindCache",
    new CacheConfiguration<String, String>()
        .add(new CacheLoaderWriterConfiguration<String, String>(MyLoaderWriter.class))
        .add(WriteBehindConfigurationBuilder.writeBehind()
            .ப்பினர்(3)
            .maximumWriteDelay(1, TimeUnit.SECONDS)
            .queueSize(1000)
            .concurrencyLevel(4)
            .enableCoalescing()
            .build())
);

```

--------------------------------

### Configure Persistence Directory with System Property

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/xml.adoc

Use the ${property-name} syntax to dynamically set the persistence directory path based on system properties.

```xml
<persistence directory="${user.home}/cache-data"/> <!--1-->
```

--------------------------------

### Verify JCache Template Overrides in Java

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/107.adoc

Demonstrates how template configurations, such as capacity and store-by-reference settings, are applied to JCache caches at runtime.

```java
include::{sourcedir310}/ehcache-107/src/test/java/org/ehcache/docs/EhCache107ConfigurationIntegrationDocTest.java[tag=jsr107SupplementWithTemplatesExample]
```

--------------------------------

### Access JCache CacheManager using Ehcache XML Configuration

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/107.adoc

Example of how to obtain a JCache `CacheManager` configured via an Ehcache XML file. This involves using `CachingProvider.getCacheManager` with a `URI` pointing to the XML configuration.

```java
URI ehcacheXmlUri = new URI("uri:ehcache-jsr107-config.xml");
ClassLoader cl = Thread.currentThread().getContextClassLoader();

// Invoke javax.cache.spi.CachingProvider.getCacheManager(java.net.URI, java.lang.ClassLoader)
CacheManager cacheManager = Caching.getCachingProvider().getCacheManager(ehcacheXmlUri, cl);

// Get the configured Cache out of the CacheManager
Cache<String, String> stringCache = cacheManager.getCache("stringCache", String.class, String.class);

```

--------------------------------

### Configure Clustered Cache Timeouts

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/resilience.adoc

Demonstrates how to set read, write, and connection timeouts for a clustered cache using the builder pattern.

```java
ClusteredResourcePoolBuilder.clusteredDedicated("primary", 8, MemoryUnit.MB)
    .withReadOperationTimeout(10, TimeUnit.SECONDS) // <2>
    .withWriteOperationTimeout(5, TimeUnit.SECONDS) // <3>
    .withConnectionTimeout(0, TimeUnit.SECONDS); // <4>
```

--------------------------------

### Configure Thread Pools with XML

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/thread-pools.adoc

Define thread pools for different services like events, write-behind, and disk stores using XML configuration. This allows declarative setup of thread pool usage.

```xml
<thread-pools>
    <thread-pool name="my-event-pool"/>
    <thread-pool name="my-write-behind-pool"/>
    <thread-pool name="my-disk-store-pool"/>
</thread-pools>

<cache name="myCache" uses-template="default-cache-template">
    <listener configuration-class="org.ehcache.event.DefaultCacheEventListenerConfiguration">
        <property name="executor" value="my-event-pool"/>
    </listener>
    <write-behind>
        <batching enabled="true"/>
        <executor name="my-write-behind-pool"/>
    </write-behind>
    <resources>
        <disk store-by-value="true">
            <disk-path>data</disk-path>
            <resources>
                <heap>50m</heap>
                <offheap unit="MB">50</offheap>
            </resources>
            <disk-store-settings>
                <executor name="my-disk-store-pool"/>
            </disk-settings>
        </disk>
    </resources>
</cache>

<cache name="anotherCache" uses-template="default-cache-template">
    <listener configuration-class="org.ehcache.event.DefaultCacheEventListenerConfiguration">
        <property name="executor" value="my-event-pool"/>
    </listener>
    <write-behind>
        <batching enabled="true"/>
        <executor name="my-write-behind-pool"/>
    </write-behind>
    <resources>
        <disk store-by-value="true">
            <disk-path>data2</disk-path>
            <resources>
                <heap>50m</heap>
                <offheap unit="MB">50</offheap>
            </resources>
            <disk-store-settings>
                <executor name="my-disk-store-pool"/>
            </disk-store-settings>
        </disk>
    </resources>
</cache>
```

--------------------------------

### Ehcache3 Data Operations

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/developer/clustered.adoc

Provides essential data manipulation operations for Ehcache3. Use 'put' to add or update a value, 'get' to retrieve a value, and 'putIfAbsent' to add a value only if the key does not already exist.

```java
void put(key, value) {
  server.append(key.hash, function(put(key, value)));
}
```

```java
value get(key) {
  return resolve(server.get(key.hash), key);
}
```

```java
value putIfAbsent(key, value) {
  return resolve(server.getAndAppend(key.hash, operation(putIfAbsent(key, value))), key);
}
```

--------------------------------

### Implement Cache-aside Read Pattern

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/caching-patterns.adoc

Consult the cache first, and if the data is missing, fetch it from the system-of-record and update the cache.

```java
v = cache.get(k)
if (v == null) {
  v = sor.get(k)
  cache.put(k, v)
}
```

--------------------------------

### Clone Ehcache Repositories

Source: https://github.com/ehcache/ehcache3/wiki/dev.release

Clone all required Ehcache repositories to your local machine. Ensure they are cloned side-by-side for easier management.

```bash
git clone git@github.com:ehcache/ehcache3.git
git clone git@github.com:ehcache/ehcache.org-site.git
git clone git@github.com:ehcache/ehcache3-samples.git
git clone git@github.com:Terracotta-OSS/docker.git
```

--------------------------------

### Initialize CacheManager from XML

Source: https://github.com/ehcache/ehcache3/blob/master/ehcache-xml/README.adoc

Load a CacheManager instance using an XML configuration file located in the classpath.

```java
final URL myUrl = this.getClass().getResource("/my-config.xml"); // <1>
XmlConfiguration xmlConfig = new XmlConfiguration(myUrl); // <2>
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); // <3>
```

--------------------------------

### Run Terracotta Config Tool

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/config-tool/README.md

Execute the config-tool container to manage cluster topology and configuration.

```bash
docker run -it --rm --network terracotta-net ehcache-terracotta-config-tool:@version@ <arguments>
```

--------------------------------

### Configure ExpiryPolicy in Java and XML

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/expiry.adoc

Demonstrates setting a time-to-live expiry policy at the cache level.

```java
CacheConfiguration<Long, String> cacheConfiguration = CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
    ResourcePoolsBuilder.heap(10))
    .withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofMinutes(10)))
    .build();
```

```xml
<cache alias="expiryCache">
  <key-type>java.lang.Long</key-type>
  <value-type>java.lang.String</value-type>
  <expiry>
    <ttl unit="minutes">10</ttl>
  </expiry>
  <resources>
    <heap unit="entries">10</heap>
  </resources>
</cache>
```

--------------------------------

### Define Off-Heap Resources for Terracotta Server

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/clustered-cache.adoc

Configure off-heap resources for the Terracotta server. This can be done in a properties file or during server startup.

```properties
offheap-resources=primary-server-resource:128MB,secondary-server-resource:96MB
```

--------------------------------

### Configure Key Copier by Instance

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/user/serializers-copiers.adoc

Configures a custom copier for cache keys using an existing instance. This allows for more control over copier instantiation.

```java
CacheConfigurationBuilder.withKeyCopier(Copier<K> keyCopier)
```

--------------------------------

### Visualize Cache and Store Lifecycle States

Source: https://github.com/ehcache/ehcache3/blob/master/docs/src/docs/asciidoc/developer/design.basics.adoc

A PlantUML state diagram representing the lifecycle transitions for cache stores and data structures.

```plantuml
@startuml
state store {
[*] --> UNINITIALIZED

UNINITIALIZED --> UNINITIALIZED : transition failure

UNINITIALIZED --> AVAILABLE : init
UNINITIALIZED --> MAINTENANCE : toMaintenance

AVAILABLE --> UNINITIALIZED : shutdown
MAINTENANCE --> UNINITIALIZED : shutdown

MAINTENANCE --> MAINTENANCE : destroy
MAINTENANCE --> MAINTENANCE : create
}

state data {
  [*] --> ONLINE : create
  ONLINE --> [*] : destroy

  OFFLINE --> ONLINE : init
  ONLINE --> OFFLINE : shutdown
  OFFLINE --> [*] : destroy
  OFFLINE --> OFFLINE : transition failure
}
hide empty description
@enduml
```

--------------------------------

### Automated Build and Test

Source: https://github.com/ehcache/ehcache3/blob/master/clustered/ehcache-clustered/src/assemble/docker/README.md

Executes the automated build and test script.

```bash
./docker/buildAndTest.groovy
```