Creating a Cache

Note:

You cannot add a cache to a system cache manager.

If you want to create...	See the following topic...
An on-heap cache	Configuring an On-Heap Cache.
An off-heap cache	Configuring a BigMemory Cache.
A distributed cache	Configuring a Distributed Cache.

Note:

The parameter descriptions in the following procedure indicate whether a parameter is dynamic or non-dynamic. If the parameter applies to a distributed cache, the description also indicates whether it is cache-wide or client-specific. For more information about dynamic and non-dynamic parameters, see Dynamic vs. Non-Dynamic Cache Parameters. For more information about cache-wide and client-specific parameters, see Cache-Wide and Client-Specific Parameters for a Distributed Cache.

Field

Description

Cache Name

Name for the cache. A valid cache name:

Must be unique within a cache manager.

Must not be null.

Must not contain these characters:

? [ ] / \ = + < > : ; “ , * | ^ @

Note:

You cannot modify the name of a cache once the cache is created.

Maximum Elements in Memory

Total number of elements that this cache can keep in on-heap memory. A value of 0 sets no limit. However, specifying no limit can affect performance. Therefore, Software AG recommends setting this field to a value greater than 0.

Note:

When you are using off-heap memory (BigMemory), Software AG recommends setting this field to at least 100 elements to minimize performance degradation.

This parameter is: Dynamic. Cache-wide.

Eternal

Optional. When selected, indicates that the elements in this cache will never expire once they are put into the cache. If selected, values in Time to Live and Time to Idle are ignored.

This check box is cleared by default.

This parameter is: Dynamic. Cache-wide.

Time to Live

Optional. Maximum amount of time (in seconds) that an element can remain in the cache regardless of whether it is accessed or not. A value of 0 indicates that elements in this cache do not have a time-to-live expiration. The default value is 0.

This field is ignored when Eternal is selected.

Note:

If you set both Time to Live and Time to Idle to 0, elements in the cache will never expire. Setting both of these fields to 0 is equivalent to selecting the Eternal check box.

Important:

If you need to modify this field after creating the cache as part of a distributed cache, do not change this value if the cache manager is shut down. Doing so will cause Integration Server to issue an exception and the cache manager will not start. To change this parameter, first start the cache manager by following the procedure in Starting a Cache Manager.

This parameter is: Dynamic. Cache-wide.

Time to Idle

Optional. Maximum amount of time (in seconds) that an element can remain in the cache without being accessed. A value of 0 indicates that elements in this cache do not have a time-to-idle expiration. The default value is 0.

This field is ignored when Eternal is selected.

Note:

If you set both Time to Live and Time to Idle to 0, elements in the cache will never expire. Setting both of these fields to 0 is equivalent to selecting the Eternal check box.

Important:

If you need to modify this field after creating the cache as part of a distributed cache, do not change this value if the cache manager is shut down. Doing so will cause Integration Server to issue an exception and the cache manager will not start. To change this parameter, first start the cache manager by following the procedure in Starting a Cache Manager.

This parameter is: Dynamic. Cache-wide.

Overflow to Disk

Optional. When selected, indicates that Integration Server writes elements to disk when the memory-based portion of on-heap and off-heap cache is filled.

If you select this check box, make sure that the key/value pairs used for elements in the cache are Java serializable. Not doing so would result in an exception while using the cache during the execution of public Integration Server services.

This check box applies to local caches only and is cleared by default. It is disabled for distributed caches when the Persist to Disk check box is selected.

This parameter is: Non-dynamic. Not applicable to distributed cache.

Persist to Disk

Optional. When selected, indicates that Integration Server maintains a copy of the entire cache on disk so that the state of the cache is preserved when Integration Server is shut down or the cache manager is reinitialized.

If you select this check box, make sure that the key/value pairs used for elements in the cache are Java serializable. Not doing so would result in an exception while using the cache during the execution of public Integration Server services.

Note:

Caches that have Persist to Disk enabled cannot be changed to any other form of persistence once the cache manager is started.

This check box applies to local caches only and is cleared by default. It is disabled for distributed caches when the Overflow to Disk check box is selected.

This parameter is: Non-dynamic. Not applicable to distributed cache.

Maximum Entries Local Disk

Optional. Maximum number of elements that can be maintained in this cache, on-heap, off-heap, and on-disk combined. For example, if you have an on-heap cache of 5000 elements and you want to allow a maximum of 1000 additional elements to overflow to disk, set Maximum Entries Local Disk to 6000.

A value of 0 sets no limit. However, specifying no limit can affect performance and can lead to errors if the disk runs out of space. Therefore, Software AG recommends setting this field to a value greater than 0.

Note:

This field applies to only to local caches and is enabled only when the Overflow to Disk check box is selected.

This parameter is: Dynamic. Client-specific.

Note:

You can only select the Distributed check box if 1) Your Integration Server has the licenses necessary to create a distributed cache, and 2) The Terracotta Server Array URLs field is configured in the cache manager to which you are adding the cache. For more information about licenses, see Installing, Viewing, and Changing the Terracotta License.

Field

Description

Consistency

Model to use to ensure consistency of elements across all caches in the cluster. Select one of the following:

strong guarantees the consistency of elements across the cluster at all times by immediately synchronizing updates to an element across the cluster. This is the default.

eventual guarantees eventual consistency of elements across the cluster. With this setting, updates to an element are not immediately synchronized across the cluster.

Important:

Do not change this value if the cache manager is shut down. Doing so will cause Integration Server to issue an exception and the cache manager will not start. To change this parameter, follow the procedure in Modifying Settings for a Distributed Cache.

This parameter is: Non-dynamic. Client-specific.

Maximum Entries in Cache

The maximum size (in number of elements) to which this cache can grow on the Terracotta Server Array.

Important:

Do not change this value if the cache manager is shut down. Doing so will cause Integration Server to issue an exception and the cache manager will not start. To change this parameter, follow the procedure in Modifying Settings for a Distributed Cache.

This parameter is: Dynamic. Cache-wide.

Enable High Availability

When selected, indicates that you want to enable nonstop behavior for the distributed cache. Nonstop behavior allows Integration Server to take a prescribed action if an operation on the distributed cache does not complete within a specified timeout period (for example, if the Terracotta Server Array is unresponsive because it is busy or if the network connection is down). For more information about nonstop behavior, see The Nonstop Behavior of a Distributed Cache.

Note:

Integration Server automatically selects this check box for a distributed cache. You cannot clear this check box.

Timeout

Optional. Amount of time (in milliseconds) that must elapse before Integration Server determines that it cannot reach the Terracotta Server Array and performs the time-out measure specified in Timeout Behavior. The default value is 30000.

This parameter is: Dynamic. Client-specific.

Timeout Behavior

Step you want Integration Server to take in order to complete a cache operation when the Terracotta Server Array does not respond within the amount of time specified in Timeout. Select one of the following:

exception - Returns a NonStopCacheException. This is the default.

noop - Returns a null for “get” operations. Ignores operations that modify elements in the cache (for example, “put,” “replace,” and “remove” operations).

localReads - Returns elements that reside in the local cache in response to “get” operations. Ignores operations that modify elements in the cache (for example, “put,” “replace,” and “remove” operations).

This parameter is: Dynamic. Client-specific.

Immediate Timeout When Disconnected

Optional. When selected, indicates that Integration Server should automatically time out all subsequent operations for this cache if Integration Server becomes disconnected from the Terracotta Server Array.

If you select this check box when Integration Server is disconnected, Integration Server will immediately time out all subsequent operations on the cache instead of waiting for the timeout period specified in Timeout. Integration Server will begin processing cache operations normally again when it successfully rejoins the Terracotta Server Array.

This check box is cleared by default.

This parameter is: Dynamic. Client-specific.

Synchronous Writes

Optional. When selected, indicates that synchronous writes to the Terracotta Server Array are allowed. Selecting this check box maximizes data integrity by requiring Integration Servert o wait for a “transaction received” acknowledgment from a server in the Terracotta Server Array before considering the write operation to have completed. However, enabling synchronous writes can significantly degrade the performance of distributed caches. Conversely, clearing this check box improves performance but may compromise the integrity of the data.

This check box is only available when Consistency is set to strong. It is cleared by default.

This parameter is: Non-dynamic. Client-specific.

Note:

You can only select the Overflow to Off-heap check box if your Integration Server is licensed to use BigMemory. For more information about licenses, see Installing, Viewing, and Changing the Terracotta License. For more information about things to consider when creating a BigMemory cache, see Configuring a BigMemory Cache.

Field

Description

Maximum Off-heap

Maximum amount of off-heap memory that this cache can use. Add one of the following suffixes to the amount to indicate the unit of measure:

k or K for kilobytes

m or M for megabytes

g or G for gigabytes

t or T for terabytes

For example, 2g allocates 2 gigabytes to off-heap memory. The minimum amount you can allocate is 1 megabyte. There is no maximum.

This field applies to local caches only and is available only if Overflow to Off-heap is selected.

This parameter is: Non-dynamic. Not applicable to distributed cache.

Field

Description

Disk Expiry Thread Interval

Optional. Amount of time (in seconds) that Integration Server waits before checking for and removing expired elements based on the values set for Time to Live and Time to Idle. The default value is 120 seconds.

This field applies to local caches only and is enabled only when the Overflow to Disk check box is selected. It is disabled for distributed caches.

This parameter is: Non-dynamic. Not applicable to distributed cache.

Disk Spool Buffer Size

Optional. Size (in megabytes) allocated on the disk store for the spool buffer that this cache uses to improve the performance of write operations. The default size is 30 megabytes.

Consider increasing the value of this field to improve disk store performance, or decreasing the value if you start to receive OutOfMemory errors.

This field applies to local caches only and is enabled only when the Overflow to Disk check box is selected. It is disabled for distributed caches.

This parameter is: Non-dynamic. Not applicable to distributed cache.

Clear on Flush

Optional. When selected, indicates that memory should be cleared when a “flush” operation is performed on the cache.

This check box is selected by default.

This parameter is: Non-dynamic. Client-specific.

Copy on Read

Optional. When selected, indicates that a copy of the element is returned when the element is read from the cache. Any changes you make to the element affect only the copy. When you put the copy of the element back into the cache, the changes become visible to other users of the cache.

When this check box is cleared, the element is not copied. Any changes you make to the element affect the element directly, through its reference, even if a “put” operation has not been performed to replace the element in the cache.

This check box is selected by default.

This parameter is: Non-dynamic. Client-specific.

The corresponding property is watt.server.serviceResults.copyOnRead.

Note:

Selecting this check box provides a degree of safety against certain logic errors in your application. However, each “get” operation on the cache causes a copy of the element to be created. This can affect performance, especially for large elements. Alternatively, consider structuring your application code so that cache gets are isolated, and references to cached objects are not retained by the application.

Important:

Do not change this value if the cache manager is shut down. Doing so will cause Integration Server to issue an exception and the cache manager will not start. To change this parameter, follow the procedure in Modifying Settings for a Distributed Cache.

Copy on Write

Optional. When selected, indicates that a copy of the element is placed in the cache during a put operation. Any subsequent changes you make to the element affect only the copy. When you put the copy of the element back into the cache, the changes become visible to other users of the cache.

When this check box is cleared, put operations pass the element by reference. If you retain a reference to the element after it is put into the cache, any changes you make to the element will also modify the element in the cache, even if you do not do a subsequent put operation.

This check box is selected by default.

This parameter is: Non-dynamic. Client-specific.

The corresponding property is watt.server.serviceResults.copyOnWrite.

Note:

Selecting this check box provides a degree of safety against certain logic errors in your application. However, each “put” operation on the cache causes a copy of the element to be created. This can affect performance, especially for large elements. Alternatively, consider structuring your application code so that cache “put” operations are isolated, and references to cached objects are not retained by the application.

Memory Store Eviction Policy

Optional. Policy used to remove elements from the memory store when the value in Maximum Elements in Memory is reached. Select one of the following:

LRU (Least Recently Used). This is the default.

LFU (Least Frequently Used)

FIFO (First In First Out). This setting is not available for distributed caches.

This parameter is: Dynamic. Client-specific.

Logging

Optional. When selected, indicates that basic distributed-map logging messages are saved to the Terracotta logs.

This check box is cleared by default.

Note:

When this check box is selected for a distributed cache, logging events are recorded on the Terracotta Server Array. For more information about logging, see Logging Ehcache Activity.

This parameter is: Non-dynamic. Client-specific.

Field

Description

Allow Automatic Indexing

Optional. When you select either Key, Value, or both, Integration Server automatically indexes the searchable keys and values. If you are not planning to include the keys and values in your query, do not enable automatic indexing.

Note:

If you select automatic indexing, you cannot have a mix of search types for keys or values.

This parameter is: Non-dynamic. Cache-wide.

Field	Description
Attribute	Name of the attribute.
Extract Method	The method to use to extract the search attributes from keys or values. Select one of the following: Expression to specify expressions based on which attributes are extracted from keys or values. Enter the expression in the Class/Expression field. For example, key.name, value.age. Class to provide the extractor class and, optionally, the properties for the extractor class. Enter the extractor class in the Class/Expression field. In the Properties field, specify the properties as key/value pairs separated by commas (,). The extractor must be an implementation of net.sf.ehcache.search.attribute.AttributeExtractor. For more information about attribute extractors, see Defining Attributes and Ehcache product documentation.
Add/Remove	Click to add or to delete search attributes to use in searches.