ManagedObjectCache

com.apama.cumulocity
Event ManagedObjectCache

The event containing the ManagedObject cache.

Use this event directly in monitors if cache is expected to be a largely independent set of ManagedObjects or the cached ManagedObjects will be trimmed to contain params not needed in other monitors. Repeated instantiations for the same ManagedObject data will unnecessarily increase both memory use and traffic through the Cumulocity Transport API.

Since:: 10.15.5.0

Routes:: com.apama.cumulocity.ManagedObjectCacheError -; com.apama.cumulocity.ManagedObjectCacheResponse -; com.apama.cumulocity.ManagedObjectCacheResponseBatch -

Sends:: com.apama.cumulocity.FindManagedObject -

Listens:: com.apama.cumulocity.FindManagedObjectResponse -; com.apama.cumulocity.FindManagedObjectResponseAck -; com.apama.cumulocity.ManagedObject -; com.apama.cumulocity.ManagedObjectDeleted -

Action summary
`com.apama.cumulocity.ManagedObjectCache`	`static` `cacheAll()` Static action that creates a properly initialized cache instance that will cache all params, in effect the whole ManagedObject as delivered by notification events.
`com.apama.cumulocity.ManagedObjectCache`	`static` `cacheWithParams(sequence<string> cacheParams)` Static action that creates a properly initialized cache instance that will only cache the provided parameters to save on memory use.
`void`	`clear()` Clear the cache.
`integer`	`get(string id)` Get the `ManagedObject` with the given id from the cache. The result is routed as a `ManagedObjectCacheResponse` event.
`integer`	`getBatch(sequence<string> ids)` Get the managed objects with the given ids from the cache. The result is routed as a `ManagedObjectCacheResponseBatch` event.
`void`	`getBatchWithCallback(sequence<string> ids, action<dictionary<string, com.apama.cumulocity.ManagedObject>, sequence<string>> callback)` Get the managed objects with the given ids from the cache. The result is returned via a callback.
`void`	`getWithCallback(string id, action<com.apama.cumulocity.ManagedObject, boolean> callback)` Get the `ManagedObject` with the given id from the cache. The result is returned via a callback.
`boolean`	`hasKey(string id)` Check whether the `ManagedObject` with the given id is currently cached.
`integer`	`query(string id)` Explicitly query the inventory, rather than the cache, for the `ManagedObject` with the given id. The result is routed as a `ManagedObjectCacheResponse` event.
`integer`	`queryBatch(sequence<string> ids)` Explicitly query the inventory, rather than the cache, for the managed objects with the given ids. The result is routed as a `ManagedObjectCacheResponseBatch` event.
`void`	`queryBatchWithCallback(sequence<string> ids, action<dictionary<string, com.apama.cumulocity.ManagedObject>, sequence<string>> callback)` Explicitly query the inventory, rather than the cache, for the managed objects with the given ids. The result is returned as a callback.
`void`	`queryWithCallback(string id, action<com.apama.cumulocity.ManagedObject, boolean> callback)` Explicitly query the inventory, rather than the cache, for the `ManagedObject` with the given id. The result is returned as a callback.
`void`	`remove(string id)` Remove a specific ManagedObject from the cache.
`void`	`setIdlePeriodSecs(float idlePeriodSecs)` Sets the idle period for a cache item before it is removed from the cache.
`void`	`setMaxSize(integer maxSize)` Set the maximum number of items the cache can hold.
`void`	`setTenant(com.apama.cumulocity.TenantDetails tenantDetails)` Set the tenant whose inventory is to be used by the cache.
`integer`	`size()` Get the number of cached ManagedObjects.

Action detail

cacheAll

com.apama.cumulocity.ManagedObjectCache static cacheAll()

Static action that creates a properly initialized cache instance that will cache all params, in effect the whole ManagedObject as delivered by notification events.

Returns:: An instance of a ManagedObjectCache.

Listens:: com.apama.cumulocity.ManagedObjectDeleted -; com.apama.cumulocity.ManagedObject -

cacheWithParams

com.apama.cumulocity.ManagedObjectCache static cacheWithParams(sequence<string> cacheParams)

Static action that creates a properly initialized cache instance that will only cache the provided parameters to save on memory use.

Parameters:: cacheParams - Sequence of param keys to keep in the cache.

Returns:: An instance of a ManagedObjectCache.

clear

void clear()

Clear the cache.

get

integer get(string id)

Get the ManagedObject with the given id from the cache. The result is routed as a ManagedObjectCacheResponse event.

If the ManagedObject is not present, the cache will be populated from the inventory. This result will only contain the properties which are set to be cached.

If the ManagedObject is not found in the inventory, a ManagedObjectCacheError event will be routed instead.

Parameters:: id - The identifier of the ManagedObject to be fetched.

Returns:: The id of the ManagedObjectCacheResponse event that will contain the result.

Routes:: com.apama.cumulocity.ManagedObjectCacheResponse -

getBatch

integer getBatch(sequence<string> ids)

Get the managed objects with the given ids from the cache. The result is routed as a ManagedObjectCacheResponseBatch event.

If a ManagedObject is not present, the cache will be populated from the inventory. This result will only contain the properties which are set to be cached.

If a ManagedObject is not found in the inventory, the id will be added to the errorIds sequence. The result is returned as a whole so that the cache can decide what to do if one or more ManagedObjects is not found.

Note that cached ManagedObjects are populated into the result at the time the request is made, rather than when any queries to the inventory have completed. This keeps the result consistent with the equivalent of calling get() multiple times with each id.

Parameters:: ids - The identifiers of the managed objects to be fetched.

Returns:: The id of the ManagedObjectCacheResponseBatch event that will contain the result.

Routes:: com.apama.cumulocity.ManagedObjectCacheResponseBatch -

getBatchWithCallback

void getBatchWithCallback(sequence<string> ids, action<dictionary<string, com.apama.cumulocity.ManagedObject>, sequence<string>> callback)

Get the managed objects with the given ids from the cache. The result is returned via a callback.

If a ManagedObject is not present, the cache will be populated from the inventory. This result will only contain the properties which are set to be cached.

If a ManagedObject is not found in the inventory, the id will be added to the errorIds sequence. The result is returned as a whole so that the cache can decide what to do if one or more ManagedObjects is not found.

Note that cached ManagedObjects are populated into the result at the time the request is made, rather than when any queries to the inventory have completed. This keeps the result consistent with the equivalent of calling get() multiple times with each id.

Parameters:: ids - The identifiers of the managed objects to be fetched.; callback - The callback called to return the result. The callback's first argument is a dictionary, keyed by id, of the ManagedObject, and the second argument is a sequence of the ids for which a ManagedObject could not be found.

getWithCallback

void getWithCallback(string id, action<com.apama.cumulocity.ManagedObject, boolean> callback)

Get the ManagedObject with the given id from the cache. The result is returned via a callback.

If the ManagedObject is not present, the cache will be populated from the inventory. This result will only contain the properties which are set to be cached.

If the ManagedObject is not found in the inventory, the error boolean will be set true, and the ManagedObject will only contain the id that was requested.

Parameters:: id - The identifier of the ManagedObject to be fetched.; callback - The callback called to return the result. The callback's first argument is the fetched ManagedObject, and the second argument is a boolean which is set true if the ManagedObject could not be found. In this case the ManagedObject will only contain the requested id.

hasKey

boolean hasKey(string id)

Check whether the ManagedObject with the given id is currently cached.

Parameters:: id - The identifier of the ManagedObject to check.

Returns:: Whether the ManagedObject with the provided id is currently in the cache.

query

integer query(string id)

Explicitly query the inventory, rather than the cache, for the ManagedObject with the given id. The result is routed as a ManagedObjectCacheResponse event.

This should be used when you need data that is not being cached, such as the parent hierarchies, which do not appear on update notifications, or params which were omitted from the cache creation.

The cache will be updated from the result of this query.

Parameters:: id - The identifier of the ManagedObject to be queried.

Returns:: The id of the ManagedObjectCacheResponse event that will contain the result.

queryBatch

integer queryBatch(sequence<string> ids)

Explicitly query the inventory, rather than the cache, for the managed objects with the given ids. The result is routed as a ManagedObjectCacheResponseBatch event.

If a ManagedObject is not found in the inventory, the id will be added to the errorIds sequence. The result is returned as a whole so that the cache can decide what to do if one or more ManagedObjects is not found.

This should be used when you need data that is not being cached, such as the parent hierarchies, which do not appear on update notifications, or params which were omitted from the cache creation.

The cache will be updated from the result of this query.

Parameters:: ids - The identifiers of the managed objects to be queried.

Returns:: The id of the ManagedObjectCacheResponseBatch event that will contain the result.

queryBatchWithCallback

void queryBatchWithCallback(sequence<string> ids, action<dictionary<string, com.apama.cumulocity.ManagedObject>, sequence<string>> callback)

Explicitly query the inventory, rather than the cache, for the managed objects with the given ids. The result is returned as a callback.

If a ManagedObject is not found in the inventory, the id will be added to the errorIds sequence. The result is returned as a whole so that the cache can decide what to do if one or more ManagedObjects is not found.

This should be used when you need data that is not being cached, such as the parent hierarchies, which do not appear on update notifications, or params which were omitted from the cache creation.

The cache will be updated from the result of this query.

Parameters:: ids - The identifiers of the managed objects to be queried.; callback - The callback called to return the result. The callback's first argument is a dictionary, keyed by id, of the ManagedObject, and the second argument is a sequence of the ids for which a ManagedObject could not be found.

queryWithCallback

void queryWithCallback(string id, action<com.apama.cumulocity.ManagedObject, boolean> callback)

Explicitly query the inventory, rather than the cache, for the ManagedObject with the given id. The result is returned as a callback.

This should be used when you need data that is not being cached, such as the parent hierarchies, which do not appear on update notifications, or params which were omitted from the cache creation.

The cache will be updated from the result of this query.

Parameters:: id - The identifier of the ManagedObject to be queried.; callback - The callback called to return the result. The callback's first argument is the fetched ManagedObject, and the second argument is a boolean which is set true if the ManagedObject could not be found. In this case the ManagedObject will only contain the requested id.

remove

void remove(string id)

Remove a specific ManagedObject from the cache.

If the ManagedObject does not exist in the cache, the remove is just ignored.

Parameters:: id - The identifier of the ManagedObject to be removed.

setIdlePeriodSecs

void setIdlePeriodSecs(float idlePeriodSecs)

Sets the idle period for a cache item before it is removed from the cache.

The cache is checked for expired cache items if idlePeriodSecs is positive, otherwise the check is disabled and items are not expired from the cache. The default is not to expire cache items.

If the idle period is less than the previous idle period, then the cache is immediately checked for any items now newly expired.

Expired cache items are not removed immediately upon expiry, but polled about every 5 minutes.

Parameters:: idlePeriodSecs - The number of seconds after which a cache item is deemed to have expired.

setMaxSize

void setMaxSize(integer maxSize)

Set the maximum number of items the cache can hold.

If positive the cache will be pruned to never have more than this number of items. The default is not to limit the size of the cache.

When the maximum is reduced, the least recently accessed items are immediately removed to reduce the cache size to the new limit.

Parameters:: maxSize - The maximum number of items the cache can hold.

setTenant

void setTenant(com.apama.cumulocity.TenantDetails tenantDetails)

Set the tenant whose inventory is to be used by the cache.

Changing the designated tenant for the cache will clear the current cache contents.

This is to enable the cache event to be used in a multi-tenant application. This does not need to be used in single tenant applications.

Parameters:: tenantDetails - The details of the tenant. An empty string indicates no specific tenant and is taken to indicate the intended use is with a single tenant application.

size

integer size()

Get the number of cached ManagedObjects.

Returns:: The number of cached ManagedObjects.

com.apama.cumulocityEvent ManagedObjectCache