Cache Put

You can use the Cache Put transform to insert a key-value pair into the global cache.

Overview

The Cache Put transform accepts only input connections, which provide values for the parameters in the nested mapping.

You can assign or map only single values to a key-value pair in the global cache. By default, the schema type of the Value parameter in the Cache Put transform is defined as xsd:anySimpleType. The Value parameter can accept any simple-typed input mapping to create a cache entry value. The cache entry is created with a Java™ Object type that is determined by the schema type of the mapped input element; see Java Object types that are created for each schema input type. To ensure that the mapped input element has a specific schema type, and hence that the cache entry is always created with a specific Java Object type, you can apply a mapping cast to the Value parameter and map the input element to the resulting target element; see Casting elements in a message map. Alternatively, you can use an xs:type transform to cast the mapped input element, or assigned value; see Cast type (xs:type).

If the element can contain multiple values, set the Cardinality property to ensure that a single value is mapped to the key or value; see Configuring the cardinality of a user-defined element.

The key-value pair is stored in a map that is in the global cache.

You can choose which of the following actions the Cache Put transform takes by selecting from the following options on the General tab of the Properties pane for the Cache Put transform:
Insert an entry in cache
A new key-value pair is added to the global cache. If the cache already contains an entry that has the same key, an error is produced. This option is the default option.
Update an entry in cache
The value that is associated with an existing key in the global cache is updated. If the cache does not already contain an entry that has the same key, an error is produced.
Insert or update an entry in cache
The global cache is queried to determine if the cache contains an entry that has the key. If the cache already contains an entry that has the same key, the value that is associated with the key is updated in the cache. If the cache does not already contain an entry that has the same key, a new key-value pair is added to the cache.
Note: The operation might fail if the key is being concurrently added or deleted.

You can add a Cache Return transform to your Cache Put transform group if you want to return values after a successful Cache Put transform; see Cache Return.

You can add a Cache Failure transform to your Cache Put transform group if you want to handle exceptions that might occur if the Cache Put transform fails; see Cache Failure.

For more information, see Adding key-value pairs to the global cache by using a Mapping node .
Note: The Cache Put transform does not have any conditional properties. To configure conditional execution, you must embed the Cache Put transform inside an If transform.

Parameters

The Cache Put nested mapping has a number of parameters that you configure by mapping values or assigning fixed values. The following table describes the parameters that you can set when you use the Cache Put transform:

Parameter Mandatory Description Result if no value is configured
Value Yes The value in the key-value pair that is inserted into the global cache map. For information about the Java Object types that are created for each schema input type, see Java Object types that are created for each schema input type. Error
Key Yes The name of the key in the key-value pair that is inserted into the global cache map. You use this key name to retrieve the associated value by using the Cache Get transform. Error
MapName You must specify a value for this parameter if you specify a value for the CacheName parameter or the TimeToLive parameter. The name of the global cache map to receive the key-value pair. If the cache map does not exist, the map is created before the key-value pair is added. The default map in the cache is used. If you are using the embedded cache, the default map is SYSTEM.BROKER.DEFAULTMAP.
CacheName No. But if you specify this parameter, you must also specify the MapName parameter, and you must not specify the TimeToLive parameter. The name of a configurable service that specifies how to connect to the global cache. The embedded cache in the integration node is used as the cache.
TimeToLive No. But if you specify this parameter, you must also specify the MapName parameter, and you must not specify the CacheName parameter. The time (in seconds) until the key-value pair is removed from the global cache.

Enter 0 or -1 to configure the key-value pair to remain in the cache until the integration node is restarted, or the cache is cleared by using the mqsicacheadmin command; see mqsicacheadmin command.

Note: The cache ignores negative values other than -1.
The cache entry does not expire.
Note: You can set these parameters by using user-defined properties. Then, you can provide values for the user-defined properties dynamically by using the Integration API or a BAR file override. For more information, see Accessing user-defined properties from a Mapping node.