Cache Folder

Usage Notes

The pub.cache:containsKey service does not verify whether the element is expired. If the element of the specified key is expired, and the element is present in the cache, pub.cache:containsKey returns found with a value of true.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

If useLoader is set to false and pub.cache:get finds the key in the cache, the results contain the value of the element. If the key does not exist in the cache, pub.cache:get returns a null in the value parameter.

If useLoader is set to true and pub.cache:get cannot find the specified key in the cache, it uses the configured cache loader to find the key in the system-of-record (SOR). If the SOR contains the key, pub.cache:get returns the value of the element. If the key does not exist in the SOR, pub.cache:get returns a null in the value parameter.

Integration Server issues a ServiceException in the following cases:

• If useLoader is true and no loaders are configured for the cache.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache:getAll service can be memory-intensive because it loads all of the specified keys into memory.

If useLoader is set to false and pub.cache:get finds the key in the cache, the results contain the value of the element. If the key does not exist in the cache, pub.cache:getAll returns a null in the value parameter.

If useLoader is set to true and pub.cache:get cannot find the specified key in the cache, it uses the configured cache loader to find the key in the system-of-record (SOR). If the SOR contains the key, pub.cache:get returns the value of the element. If the key does not exist in the SOR, pub.cache:getAll returns a null in the value parameter.

Integration Server issues a ServiceException in the following cases:

• If useLoader is true and no loaders are configured for the cache.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

Retrieving all of the keys from a cache may negatively impact the performance of the calling service. This may be especially true when retrieving all of the keys for a large, distributed cache.

Retrieving all of the keys from a cache is a memory-intensive activity. It is possible for the list of available keys to be larger than the memory available on your system. In such cases, Integration Server might issue an OutOfMemoryError and become unresponsive.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

If your cache is a distributed cache or is configured to use disk store or BigMemory, key and value must be Java Serializable objects.

If the element with the specified key does not already exist in the cache, the pub.cache:put service puts the element in the cache. If the element with the specified key already exists in the cache, pub.cache:put updates the element with the specified value.

If you run pub.cache:put on a disabled cache, the cache discards the call.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If useWriter is set to true and no writer is configured for the cache.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

If your cache is a distributed cache or is configured to use disk store or BigMemory, key and value must be Java Serializable objects.

The key and value input parameters cannot be null. The service might end with a NullPointerException if any key or value parameters are null.

If the element with the specified key does not already exist in the cache, the pub.cache:putAll service puts the element in the cache. If the element with the specified key already exists in the cache, pub.cache:putAll updates the element with the specified value.

If you run pub.cache:putAll on a disabled cache, the cache discards the call.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

If the element associated with the specified key does not exist, pub.cache:remove returns false for removed.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

If you want to search a document (IData) in the cache, you must first create an attribute extractor class and identify the search attributes for the cache. Terracotta Ehcache uses the extractor class and the provided search attribute information to search the cache when the pub.cahce:search service executes.

A sample IData that you can specify as the criteria input parameter is given below. The following input searches the personCache cache for entries, where age is greater than 60 and gender is female.

IData idata = IDataFactory.create();

 
//Cache information 
          IDataMap map = new IDataMap(idata)    ; 
          map.put("cacheManagerName", "SearchTestManager")    ; 
          map.put("cacheName", "personCache")    ; 
          map.put("includeKey", "true")    ; 
          map.put("includeValue", "true") ;

//Condition 1 - Age > 60 
          IData input1 = IDataFactory.create()    ; 
          IDataCursor cursor1 = input1.getCursor()    ; 
          IDataUtil.put(cursor1, "OP1", "age")    ; 
          IDataUtil.put(cursor1, "OPR", "gt")    ; 
          IDataUtil.put(cursor1, "OP2", 60) ;

 
//Condition 2 - Gender == Female 
          IData input2 = IDataFactory.create()    ; 
          IDataCursor cursor2= input2.getCursor()    ; 
          IDataUtil.put(cursor2, "OP1", "gender")    ; 
          IDataUtil.put(cursor2, "OPR", "eq")    ; 
          IDataUtil.put(cursor2, "OP2", Person.Gender.FEMALE) ;

 
//Joining conditions, condition 1 && condition 2 
          IData input3 = IDataFactory.create()    ; 
          IDataCursor cursor3 = input3.getCursor()    ; 
          IDataUtil.put(cursor3, "OP1", input1)    ; 
          IDataUtil.put(cursor3, "OPR", "AND")    ; 
          IDataUtil.put(cursor3, "OP2", input2)    ; 
          map.put("criteria", input3) ;

 
//Run the search 
          IData result = invoke(NSName.create("pub.cacheimpl:search"), 
          idata); 
          Object[] objectList = (Object[]) IDataUtil.get(result.getCursor(), 
          "result");

          for (int i = 0; i < objectList.length; i++) { 
          Person value = (Person) ((SearchResult) objectList[i]).getValue(); 
          System.out.println(value.getGender()); 
          System.out.println( value.getAge()); 
        }

When using the between operator for the criteria\OPR parameter, you must specify start and end values. That is, you must specify a two-element Object List with the 0 element as the start value and the first element as the end value. For example:

//Condition  1 < age <10 
      IData input1 = IDataFactory.create() ; 
      IDataCursor cursor1 = input1.getCursor() ; 
      IDataUtil.put(cursor1, "OP1", "age") ; 
      IDataUtil.put(cursor1, "OPR", "between") ; 
      IDataUtil.put(cursor1, "OP2", {1,10}) ;

Because the state of the cache can change between search executions, include all of the aggregators to the search query at the same time, so that the returned aggregators are of the same iteration of the cache.

By default a search will return an unlimited number of results. If too many results are returned, Integration Server might issue an OutOfMemoryError and become unresponsive. Limit the size of the results using the maxResults parameter.

Usage Notes

If pub.cache.admin:clearAllCaches does not find any caches with the specified prefix, the service does not clear any caches, but returns Success for status.

You cannot clear caches managed by system cache managers.

If you have any existing locks on any of the elements in the cache, the pub.cache.admin:clearAllCaches service waits indefinitely until all locks are released.

Integration Server returns a status of Error in the following cases:

• If the cache is managed by a system cache manager.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager.
• If a cache operation fails.

Usage Notes

You cannot clear caches managed by system cache managers.

If you have any existing locks on any of the elements in the cache, the pub.cache.admin:clearCache service waits indefinitely until all locks are released.

Integration Server returns a status of Error in the following cases:

• If the cache is managed by a system cache manager.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

When you disable a cache, the cached elements are unavailable for cache operations but still present in the cache. Use the pub.cache.admin:enableCache service to make the disabled cached elements available again.

You cannot disable caches managed by system cache managers.

After the pub.cache.admin:disableCache service disables a cache, other services cannot add, modify, delete, or retrieve its contents. For example, calls to the pub.cache:get service will return null.

The disabled state of a cache lasts only for the lifetime of its cache manager. When the cache manager is restarted, either by restarting Integration Server or clicking the reload icon on the Settings > Caching page in Integration Server Administrator, the cache is enabled.

When you disable a cache, Integration Server:

• Discards operations such as pub.cache:get, pub.cache:remove, and pub.cache.atomic:replace calls on the cache.
• Returns a null for pub.cache:get calls on the cache.

Integration Server returns a status of Error in the following cases:

• If the cache is managed by a system cache manager.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

You cannot enable caches managed by system cache managers.

When you disable a cache, the cached elements are unavailable but still present in the cache. Use pub.cache.admin:enableCache to make the cached elements available again.

Integration Server returns a status of Error in the following cases:

• If the cache is managed by a system cache manager.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.admin:evictExpiredElements service can take longer to delete expired elements depending on the number of elements contained in the cache. If the cache contains a large number of elements, pub.cache.admin:evictExpiredElements might take longer to process the request than when the cache contains fewer elements.

Integration Server returns a status of Error in the following cases:

• If the cache is managed by a system cache manager.
• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

pub.cache.admin:isCacheDisabled returns Error for status and an accompanying message in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.atomic:putIfAbsent service adds the specified value to the cache only if the specified key does not already exist in the cache. If the specified key already exists in the cache, pub.cache.atomic:putIfAbsent returns true for keyExists and the value of the cached element for oldValue.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.atomic:replace service replaces an element in the cache only if an element with the values of the specified key and oldValue parameters already exist in the cache. If an element exist in the cache with the specified key and oldValue, pub.cache.atomic:replace replaces the cached element with the specified key and newValue.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.atomic:replaceIfKeyExists service replaces an element in the cache only if the specified key already exists in the cache. If an element with the specified key exists, pub.cache.atomic:replaceIfKeyExists replaces value of the cached element with the one specified in value.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.bulk:isClusterBulkLoadEnabled service applies only to distributed caches. If you run pub.cache.bulk:isClusterBulkLoadEnabled on a local cache, the service returns false for enabled.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.bulk:isNodeBulkLoadEnabled service applies only to distributed caches.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.bulk:setNodeBulkLoadEnabled service applies only to distributed caches.

The pub.cache.bulk:setNodeBulkLoadEnabled service does nothing if you:

• Try to enable bulk loading (bulkMode set to true) when the node is already in bulk-load mode.
• Try to disable bulk loading (bulkMode set to false) when the node is not already in bulk-load mode.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

The pub.cache.bulk:waitUntilClusterBulkLoadComplete service applies only to distributed caches.

If none of the nodes are bulk-load enabled, Integration Server immediately executes the next step in the flow service without waiting.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If a cache operation fails.

Usage Notes

If the pub.cache.lock:acquireLock service acquires a lock, the element remains locked until released with the pub.cache.lock:releaseLock service.

You must acquire and release a lock in the same thread in which pub.cache.lock:acquireLock is executing. Failing to do so could cause the key to remain locked indefinitely.

When using the debug flow service to step through a flow service, depending on your breakpoint settings Designer might use a new thread for each step. You cannot release a lock acquired in a previous step of the same flow if break points are triggered on Designer or if you are stepping through a flow service. To avoid orphaned locks, disable invocations of pub.cache.lock:acquireLock and pub.cache.lock:releaseLock before stepping through the flow service or make sure that pub.cache.lock:acquireLock and pub.cache.lock:releaseLock services are called between the boundaries of two breakpoints.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• Whether or not a cached element needs to be locked depends on the application that is using the element. For example, if an application retrieves and holds an element for a time and needs to prevent another client from changing the element during this time, the application should acquire a lock on the element. However, if the application does not hold the element, a lock might not be required.
• If Integration Server cannot find the specified cache manager or cache.
• If pub.cache.lock:acquireLock is unable to acquire a lock.
• If the specified lockWaitTime is not a valid integer.
• If a cache operation fails.

Usage Notes

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.

Usage Notes

You must call pub.cache.lock:releaseLock from the same thread from which you call pub.cache.lock:acquireLock. Failing to do so could cause the key to remain locked indefinitely.

Integration Server issues a ServiceException in the following cases:

• If you do not specify all required input parameters.
• If Integration Server cannot find the specified cache manager or cache.
• If you try to release a read lock on a cached element for which a write lock is set, or release a write lock on a cached element for which a read lock is set.

Usage Notes

If the serviceName service does not exist in Integration Server, or it is not enabled to cache service results, Integration Server throws an exception.

Usage Notes

If serviceName specifies a service that does not exist or a service for which Integration Server does not cache service results, Integration Server returns an empty elements output parameter.-

You can use the pub.cache.serviceResults:listServiceCache with a public service results cache only. You cannot use the pub.cache.serviceResults:listServiceCache with the ServiceResults system cache.

For the pub.cache.serviceResults:listServiceCache service to return results, make sure that the service results cache is searchable and that the cache allows automatic indexing for keys. That is, for the service results cache, the Searchable check box must be selected and the Key check box next to Allow Automatic Indexing must be selected.

Exposing the contents of the service results cache via the pub.cache.serviceResults:listServiceCache may represent a security risk.