Software AG Products 10.7 | Administering Integration Server | Configuring Ehcache on Integration Server | Working with Caches | Creating a Cache
 
Creating a Cache
Use the following procedure to create a cache.
Note:
You cannot add a cache to a system cache manager.
You must complete the following before you create a cache:
*The cache manager to which you want to add the cache must already exist. If you need to create the cache manager, see Creating a Cache Manager.
*If you are creating a distributed cache, your Integration Server must have a license to use a Terracotta Server Array. In addition, the cache manager to which you want to add the cache must be configured to use a Terracotta Server Array. For more information about licenses, see Installing, Viewing, and Changing the Terracotta License.
*If you want to create an off-heap cache (a cache that uses BigMemory), your Integration Server must have a license to use BigMemory. For more information about licenses, see Installing, Viewing, and Changing the Terracotta License.
If you are creating a cache for the first time, review the following sections before you begin.
If you want to create
See the following topic
An on-heap cache
An off-heap cache
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.
*To create a cache
1. Open Integration Server Administrator if it is not already open.
2. Go to Settings > Caching.
3. Under Public Cache Managers, click the cache manager to which you want to add a cache.
4. Click Add Cache.
5. Under Cache Configuration, specify the following information.
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.
6. If you are creating a distributed cache, select the Distributed check box and then configure the following fields under Distributed Cache Configuration:
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. You must specify a value greater than 0.
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.
7. If you are creating a local cache and you want the cache to overflow to BigMemory, select the Overflow to Off-heap check box and then configure the following field under BigMemory:
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.
8. Configure the following fields under Cache Configuration Advanced Settings:
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.
9. To make the cache searchable, select the Searchable check box and configure the following field under Search Configuration:
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.
10. Under Search Attributes, define one or more attributes that will be used in searches by configuring the following fields:
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 add icon to add or delete icon to delete search attributes to use in searches.
11. Click Save Changes. Integration Server creates the cache and places it in the disabled state.
12. When you are ready to put the cache into use, enable it using the procedure in Enabling a Cache.