<commit_before>---
---
= Ehcache 3.3 Documentation
ifndef::sourcedir33[]
include::common.adoc[]
endif::sourcedir33[]
We feel that the Ehcache 3.x API is a great improvement over the Ehcache 2.x API that has been used by millions of developers. We hope you enjoy this new generation of Ehcache!

ifdef::notBuildingForSite[]
include::menu.adoc[]
endif::notBuildingForSite[]

== Configuring Ehcache

In order to start using Ehcache, you will need to configure your first `CacheManager` and `Cache`.
This can be achieved through <<configuring-with-java,programmatic configuration>> or <<configuring-with-xml,XML>>.

NOTE: If you are looking to use the JSR-107, aka `javax.cache` API, you should start by reading
      <<107.adoc#,the Ehcache 3.x JSR-107 Provider page>>.

[[configuring-with-java]]
=== Programmatic configuration

Java configuration is most easily achieved through the use of builders that offer a fluent API.

As with the previous versions of Ehcache, the canonical way of dealing with `Cache` is through a `CacheManager`:

[source,java,indent=0]
----
include::{sourcedir33}/impl/src/test/java/org/ehcache/docs/GettingStarted.java[tag=cachemanagerExample]
----

<1> The static method `org.ehcache.config.builders.CacheManagerBuilder.newCacheManagerBuilder` returns a new `org.ehcache.config.builders.CacheManagerBuilder` instance.
<2> Use the builder to define a `Cache` with alias "preConfigured". This cache will be created when `cacheManager.build()` is invoked on the actual `CacheManager` instance.
The first `String` argument is the cache alias, which is used to retrieve the cache from the `CacheManager`.
The second argument, `org.ehcache.config.CacheConfiguration`, is used to configure the `Cache`.
We use the static `newCacheConfigurationBuilder()` method on `org.ehcache.config.builders.CacheConfigurationBuilder` to create a default configuration.
<3> Finally, invoking `build()` returns a fully instantiated, **but uninitialized**, `CacheManager` we can use.
<4> Before using the `CacheManager` it needs to be initialized, which can be done in 1 of 2 ways:
Calling `CacheManager.init()` on the `CacheManager` instance, or calling the `CacheManagerBuilder.build(boolean init)` method with the boolean parameter set to true.
<5> A cache is retrieved by passing its alias, key type and value type to the `CacheManager`.
For instance, to obtain the cache declared in step 2 you need its `alias="preConfigured"`, `keyType=Long.class` and `valueType=String.class`.
For type-safety, we ask for both key and value types to be passed in.
If these differ from the ones we expect, the `CacheManager` throws a `ClassCastException` early in the application's lifecycle.
This guards the `Cache` from being polluted by random types.
<6> The `CacheManager` can be used to create new `Cache` instances as needed. Just as in step 2, it requires passing in an
    alias as well as a `CacheConfiguration`. The instantiated and fully initialized `Cache` added will be returned and/or
    accessed through the `CacheManager.getCache` API.
<7> The newly added `Cache` can now be used to store entries, which are comprised of key value pairs.
The put method's first parameter is the key and the second parameter is the value.
Remember the key and value types must be the same types as those defined in the `CacheConfiguration`.
Additionally the key must be unique and is only associated with one value.
<8> A value is retrieved from a cache by calling the `cache.get(key)` method.
It only takes one parameter which is the key, and returns the value associated with that key. If there is no value associated with that key then null is returned.
<9> We can `CacheManager.removeCache(String)` a given `Cache`. The `CacheManager` will not only remove its reference to the
    `Cache`, but will also close it. The `Cache` releases all locally held transient resources (such as memory).
    References to this `Cache` become unusable.
<10> In order to release all transient resources (memory, threads, ...) a `CacheManager` provides to `Cache` instances
     it manages, you have to invoke `CacheManager.close()`, which in turns closes all `Cache` instances known at the time.

[[configuring-with-xml]]
=== XML configuration

You can create an XML file to configure a `CacheManager`:

[source,xml,indent=0]
----
include::{sourcedir33}/xml/src/test/resources/configs/docs/getting-started.xml[tags=gettingStarted]
----

<1> Declares a `Cache` aliased to `foo`.
<2> The keys and values of `foo` are declared as type `String`; if not specified, the default is `java.lang.Object`.
<3> `foo` is declared to hold up to 2,000 entries on heap...
<4> ...as well as up to 500 MB of off-heap memory before it starts evicting
<5> `<cache-template>` elements let you create an abstract configuration that further `<cache>` configurations can then "extend"
<6> `bar` is such a `Cache`.   `bar` uses the `<cache-template>` named `myDefaults` and overrides its `key-type` to a wider type.
<7> `simpleCache` is another such `Cache`.  It uses `myDefaults` configuration for its sole `CacheConfiguration`.

Refer to the <<xml.adoc#,XML documentation>> for more details on the XML format.

In order to parse an XML configuration, you can use the `XmlConfiguration` type:

[source,java]
----
URL myUrl = getClass().getResource("/my-config.xml"); // <1>
Configuration xmlConfig = new XmlConfiguration(myUrl); // <2>
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); // <3>
----

<1> Obtain a `URL` to your XML file location
<2> Instantiate an `XmlConfiguration` passing the XML file URL to it
<3> Using the static `org.ehcache.config.builders.CacheManagerBuilder.newCacheManager(org.ehcache.config.Configuration)` lets you
    create your `CacheManager` instance using the `Configuration` from the `XmlConfiguration`

=== Creating a cache manager with clustering support

To enable Clustering with Terracotta, firstly you will have to <<clustered-cache.adoc#starting-terracotta-server, start the Terracotta server>> configured with clustered storage.
In addition, for creating the cache manager with clustering support, you will need to provide the clustering service configuration:

[source,java,indent=0]
----
include::{sourcedir33}/clustered/client/src/test/java/org/ehcache/clustered/client/docs/GettingStarted.java[tag=clusteredCacheManagerExample]
----

<1> Returns the `org.ehcache.config.builders.CacheManagerBuilder` instance;
<2> Use the `ClusteringServiceConfigurationBuilder`{empty}'s static method `.cluster(URI)` for connecting the cache manager to the clustering storage at the
    URI specified that returns the clustering service configuration builder instance.
    The sample URI provided in the example points to the clustered storage with clustered storage identifier *my-application* on the Terracotta server (assuming the server is running on localhost and port *9510*); the query-param `auto-create`
    creates the clustered storage in the server if it doesn't already exist.
<3> Returns a fully initialized cache manager that can be used to create clustered caches.
<4> Close the cache manager.

NOTE: See <<clustered-cache.adoc#,the clustered cache documentation>> for more information on this feature.

=== Storage Tiers<commit_msg>Invalid URL to start-server<commit_after>---
---
= Ehcache 3.3 Documentation
ifndef::sourcedir33[]
include::common.adoc[]
endif::sourcedir33[]
We feel that the Ehcache 3.x API is a great improvement over the Ehcache 2.x API that has been used by millions of developers. We hope you enjoy this new generation of Ehcache!

ifdef::notBuildingForSite[]
include::menu.adoc[]
endif::notBuildingForSite[]

== Configuring Ehcache

In order to start using Ehcache, you will need to configure your first `CacheManager` and `Cache`.
This can be achieved through <<configuring-with-java,programmatic configuration>> or <<configuring-with-xml,XML>>.

NOTE: If you are looking to use the JSR-107, aka `javax.cache` API, you should start by reading
      <<107.adoc#,the Ehcache 3.x JSR-107 Provider page>>.

[[configuring-with-java]]
=== Programmatic configuration

Java configuration is most easily achieved through the use of builders that offer a fluent API.

As with the previous versions of Ehcache, the canonical way of dealing with `Cache` is through a `CacheManager`:

[source,java,indent=0]
----
include::{sourcedir33}/impl/src/test/java/org/ehcache/docs/GettingStarted.java[tag=cachemanagerExample]
----

<1> The static method `org.ehcache.config.builders.CacheManagerBuilder.newCacheManagerBuilder` returns a new `org.ehcache.config.builders.CacheManagerBuilder` instance.
<2> Use the builder to define a `Cache` with alias "preConfigured". This cache will be created when `cacheManager.build()` is invoked on the actual `CacheManager` instance.
The first `String` argument is the cache alias, which is used to retrieve the cache from the `CacheManager`.
The second argument, `org.ehcache.config.CacheConfiguration`, is used to configure the `Cache`.
We use the static `newCacheConfigurationBuilder()` method on `org.ehcache.config.builders.CacheConfigurationBuilder` to create a default configuration.
<3> Finally, invoking `build()` returns a fully instantiated, **but uninitialized**, `CacheManager` we can use.
<4> Before using the `CacheManager` it needs to be initialized, which can be done in 1 of 2 ways:
Calling `CacheManager.init()` on the `CacheManager` instance, or calling the `CacheManagerBuilder.build(boolean init)` method with the boolean parameter set to true.
<5> A cache is retrieved by passing its alias, key type and value type to the `CacheManager`.
For instance, to obtain the cache declared in step 2 you need its `alias="preConfigured"`, `keyType=Long.class` and `valueType=String.class`.
For type-safety, we ask for both key and value types to be passed in.
If these differ from the ones we expect, the `CacheManager` throws a `ClassCastException` early in the application's lifecycle.
This guards the `Cache` from being polluted by random types.
<6> The `CacheManager` can be used to create new `Cache` instances as needed. Just as in step 2, it requires passing in an
    alias as well as a `CacheConfiguration`. The instantiated and fully initialized `Cache` added will be returned and/or
    accessed through the `CacheManager.getCache` API.
<7> The newly added `Cache` can now be used to store entries, which are comprised of key value pairs.
The put method's first parameter is the key and the second parameter is the value.
Remember the key and value types must be the same types as those defined in the `CacheConfiguration`.
Additionally the key must be unique and is only associated with one value.
<8> A value is retrieved from a cache by calling the `cache.get(key)` method.
It only takes one parameter which is the key, and returns the value associated with that key. If there is no value associated with that key then null is returned.
<9> We can `CacheManager.removeCache(String)` a given `Cache`. The `CacheManager` will not only remove its reference to the
    `Cache`, but will also close it. The `Cache` releases all locally held transient resources (such as memory).
    References to this `Cache` become unusable.
<10> In order to release all transient resources (memory, threads, ...) a `CacheManager` provides to `Cache` instances
     it manages, you have to invoke `CacheManager.close()`, which in turns closes all `Cache` instances known at the time.

[[configuring-with-xml]]
=== XML configuration

You can create an XML file to configure a `CacheManager`:

[source,xml,indent=0]
----
include::{sourcedir33}/xml/src/test/resources/configs/docs/getting-started.xml[tags=gettingStarted]
----

<1> Declares a `Cache` aliased to `foo`.
<2> The keys and values of `foo` are declared as type `String`; if not specified, the default is `java.lang.Object`.
<3> `foo` is declared to hold up to 2,000 entries on heap...
<4> ...as well as up to 500 MB of off-heap memory before it starts evicting
<5> `<cache-template>` elements let you create an abstract configuration that further `<cache>` configurations can then "extend"
<6> `bar` is such a `Cache`.   `bar` uses the `<cache-template>` named `myDefaults` and overrides its `key-type` to a wider type.
<7> `simpleCache` is another such `Cache`.  It uses `myDefaults` configuration for its sole `CacheConfiguration`.

Refer to the <<xml.adoc#,XML documentation>> for more details on the XML format.

In order to parse an XML configuration, you can use the `XmlConfiguration` type:

[source,java]
----
URL myUrl = getClass().getResource("/my-config.xml"); // <1>
Configuration xmlConfig = new XmlConfiguration(myUrl); // <2>
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); // <3>
----

<1> Obtain a `URL` to your XML file location
<2> Instantiate an `XmlConfiguration` passing the XML file URL to it
<3> Using the static `org.ehcache.config.builders.CacheManagerBuilder.newCacheManager(org.ehcache.config.Configuration)` lets you
    create your `CacheManager` instance using the `Configuration` from the `XmlConfiguration`

=== Creating a cache manager with clustering support

To enable Clustering with Terracotta, firstly you will have to <<clustered-cache.adoc#starting-server, start the Terracotta server>> configured with clustered storage.
In addition, for creating the cache manager with clustering support, you will need to provide the clustering service configuration:

[source,java,indent=0]
----
include::{sourcedir33}/clustered/client/src/test/java/org/ehcache/clustered/client/docs/GettingStarted.java[tag=clusteredCacheManagerExample]
----

<1> Returns the `org.ehcache.config.builders.CacheManagerBuilder` instance;
<2> Use the `ClusteringServiceConfigurationBuilder`{empty}'s static method `.cluster(URI)` for connecting the cache manager to the clustering storage at the
    URI specified that returns the clustering service configuration builder instance.
    The sample URI provided in the example points to the clustered storage with clustered storage identifier *my-application* on the Terracotta server (assuming the server is running on localhost and port *9510*); the query-param `auto-create`
    creates the clustered storage in the server if it doesn't already exist.
<3> Returns a fully initialized cache manager that can be used to create clustered caches.
<4> Close the cache manager.

NOTE: See <<clustered-cache.adoc#,the clustered cache documentation>> for more information on this feature.

=== Storage Tiers
{'fraction_non_alphanumeric': 0.08977624784853701, 'fraction_numerical': 0.00963855421686747, 'mean_word_length': 4.972861842105263, 'pattern_counts': {'":': 0, '<': 87, '<?xml version=': 0, '>': 87, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 18}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3741717', 'n_tokens_mistral': 4042, 'n_tokens_neox': 3811, 'n_words': 1834}