TIBCO FTL®
|
Programs can use maps to store key/value pairs in a persistence store. More...
Macros | |
#define | TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION "com.tibco.ftl.client.map.persistence.retry.duration" |
Retry duration for map operations; double. More... | |
#define | TIB_MAP_PROPERTY_STRING_LABEL "com.tibco.ftl.client.map.label" |
Property name for a map label; string. More... | |
Typedefs | |
typedef struct __tibMapId * | tibMap |
Functions | |
TIB_API void | tibMap_Close (tibEx e, tibMap tibmap) |
Destroy a map object. More... | |
TIB_API tibMapIterator | tibMap_CreateIterator (tibEx e, tibMap tibmap, tibProperties props) |
Create an iterator over the keys in a map. More... | |
TIB_API tibMapIterator | tibMap_CreateIteratorWithLock (tibEx e, tibMap tibmap, tibLock lock, tibProperties props) |
Create an iterator over the keys in a map and associate it with a lock. More... | |
TIB_API tibMessage | tibMap_Get (tibEx e, tibMap tibmap, const char *key) |
Get the value of a key in a map. More... | |
TIB_API tibMessage | tibMap_GetWithLock (tibEx e, tibMap tibmap, const char *key, tibLock lock) |
Get the value of a key in a map as a locked operation. More... | |
TIB_API void | tibMap_Remove (tibEx e, tibMap tibmap, const char *key) |
Remove a key/value pair from a map. More... | |
TIB_API void | tibMap_RemoveWithLock (tibEx e, tibMap tibmap, const char *key, tibLock lock) |
Remove a key/value pair from a map as a locked operation. More... | |
TIB_API void | tibMap_Set (tibEx e, tibMap tibmap, const char *key, tibMessage value) |
Set a key/value pair in a map. More... | |
TIB_API void | tibMap_SetMultiple (tibEx e, tibMap tibmap, tibint32_t numKeys, const char **keys, tibMessage *values) |
Set multiple key/value pairs in a map. More... | |
TIB_API void | tibMap_SetMultipleWithLock (tibEx e, tibMap tibmap, tibint32_t numKeys, const char **keys, tibMessage *values, tibLock lock) |
Set multiple key/value pairs in a map as a locked operation. More... | |
TIB_API void | tibMap_SetWithLock (tibEx e, tibMap tibmap, const char *key, tibMessage value, tibLock lock) |
Set a key/value pair in a map as a locked operation. More... | |
Programs can use maps to store key/value pairs in a persistence store.
To create a map object, see tibRealm_CreateMap.
To delete a map from a store, see tibRealm_RemoveMap.
Prerequisite: Administrators must enable dynamic last-value durables in a persistence store. For more information, see TIBCO FTL Administration.
This file defines map calls.
#define TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION "com.tibco.ftl.client.map.persistence.retry.duration" |
Retry duration for map operations; double.
When tibRealm_CreateMap, tibMap_Set, tibMap_Get, or tibMap_Remove (with lock or without lock) cannot access the persistence server (usually because of network failure or quorum unavailability), they can automatically retry the interaction. The value of this property overrides the retry behavior of the server. Supply it to the map create call.
Values:
Closing the realm or destroying the map supersedes and cancels retry behavior.
This property does not apply to map iterators.
#define TIB_MAP_PROPERTY_STRING_LABEL "com.tibco.ftl.client.map.label" |
Property name for a map label; string.
It is good practice to include this property in every map create call. Monitoring data incorporates these labels so administrators can identify and distinguish among internal publishers and subscribers created on behalf of maps. Use labels that reveal the unique role and identity of each map within the application program.
When the map label is present in the map create call, the new map assigns it as the label of its internal publishers and subscribers.
typedef struct __tibMapId* tibMap |
Destroy a map object.
This call destroys only the local map object in the client process. To delete the map from the persistence store, see tibRealm_RemoveMap.
e | The exception object captures information about failures. |
tibmap | The call destroys this map object. |
TIB_API tibMapIterator tibMap_CreateIterator | ( | tibEx | e, |
tibMap | tibmap, | ||
tibProperties | props | ||
) |
Create an iterator over the keys in a map.
The iterator produces every key/value pair in the map.
e | The exception object captures information about failures. |
tibmap | The call destroys this map object. |
props | Reserved for future use. To ensure forward compatibility, programmers must supply NULL . |
TIB_API tibMapIterator tibMap_CreateIteratorWithLock | ( | tibEx | e, |
tibMap | tibmap, | ||
tibLock | lock, | ||
tibProperties | props | ||
) |
Create an iterator over the keys in a map and associate it with a lock.
The iterator produces every key/value pair in the map.
Before creating an iterator, this call ensures that the process holds the lock. If the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not create an iterator.
Subsequent calls to advance the iterator require that the process hold the lock.
If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until it explicitly returns it.
e | The exception object captures information about failures. |
tibmap | The call destroys this map object. |
lock | The iterator uses the lock represented by this lock object. |
props | Reserved for future use. To ensure forward compatibility, programmers must supply NULL . |
TIB_API tibMessage tibMap_Get | ( | tibEx | e, |
tibMap | tibmap, | ||
const char * | key | ||
) |
Get the value of a key in a map.
This call returns a copy of the stored message. Client program code accepts ownership of the message object. Client program code may pass this message to another program thread. Client program code must explicitly destroy the message object.
If the key is not set in the map, this call returns null.
e | The exception object captures information about failures. |
tibmap | The call gets the key's value in this map. |
key | The call gets a value for this key. |
TIB_API tibMessage tibMap_GetWithLock | ( | tibEx | e, |
tibMap | tibmap, | ||
const char * | key, | ||
tibLock | lock | ||
) |
Get the value of a key in a map as a locked operation.
This call returns a copy of the stored message. Client program code accepts ownership of the message object. Client program code may pass this message to another program thread. Client program code must explicitly destroy the message object.
Before its map operation, this call ensures that the process holds the lock. If the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not return the key's value.
If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until it explicitly returns it.
If the key is not set in the map, this call returns null.
e | The exception object captures information about failures. |
tibmap | The call gets the key's value in this map. |
key | The call gets a value for this key. |
lock | The call requires the lock represented by this lock object. |
Remove a key/value pair from a map.
e | The exception object captures information about failures. |
tibmap | The call removes the key from this map. |
key | The call removes this key. |
Remove a key/value pair from a map as a locked operation.
Before its map operation, this call ensures that the process holds the lock. If the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not remove the key's value.
If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until it explicitly returns it.
e | The exception object captures information about failures. |
tibmap | The call removes the key from this map. |
key | The call removes this key. |
lock | The call requires the lock represented by this lock object. |
TIB_API void tibMap_Set | ( | tibEx | e, |
tibMap | tibmap, | ||
const char * | key, | ||
tibMessage | value | ||
) |
Set a key/value pair in a map.
If a value has already been set for the key, this call overwrites the existing value.
e | The exception object captures information about failures. |
tibmap | The call stores the key/value pair in this map. |
key | The call sets a value for this key. |
value | The call sets this value for the key. |
TIB_API void tibMap_SetMultiple | ( | tibEx | e, |
tibMap | tibmap, | ||
tibint32_t | numKeys, | ||
const char ** | keys, | ||
tibMessage * | values | ||
) |
Set multiple key/value pairs in a map.
If a value has already been set for a key, this call overwrites the existing value.
e | The exception object captures information about failures. |
tibmap | The call stores the key/value pairs in this map. |
numKeys | Number of keys/value pairs to store. |
keys | The call sets values for these keys. |
values | The call sets these values for the corresponding keys. |
TIB_API void tibMap_SetMultipleWithLock | ( | tibEx | e, |
tibMap | tibmap, | ||
tibint32_t | numKeys, | ||
const char ** | keys, | ||
tibMessage * | values, | ||
tibLock | lock | ||
) |
Set multiple key/value pairs in a map as a locked operation.
Before its map operation, this call ensures that the process holds the lock. If the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not change the key's value.
If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until it explicitly returns it.
If a value has already been set for a key, this call overwrites the existing value.
e | The exception object captures information about failures. |
tibmap | The call stores the key/value pairs in this map. |
numKeys | Number of keys/value pairs to store. |
keys | The call sets values for these keys. |
values | The call sets these values the corresponding keys. |
lock | The call requires the lock represented by this lock object. |
TIB_API void tibMap_SetWithLock | ( | tibEx | e, |
tibMap | tibmap, | ||
const char * | key, | ||
tibMessage | value, | ||
tibLock | lock | ||
) |
Set a key/value pair in a map as a locked operation.
Before its map operation, this call ensures that the process holds the lock. If the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not change the key's value.
If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until it explicitly returns it.
If a value has already been set for the key, this call overwrites the existing value.
e | The exception object captures information about failures. |
tibmap | The call stores the key/value pair in this map. |
key | The call sets a value for this key. |
value | The call sets this value for the key. |
lock | The call requires the lock represented by this lock object. |