TIBCO FTL®

Public Member Functions | List of all members
TIBCO.FTL.ITibMap Interface Reference

Programs can use maps to store key/value pairs in a persistence store. More...

Inheritance diagram for TIBCO.FTL.ITibMap:

## Public Member Functions
ITibMapIterator | CreateIterator (ITibLock tiblock, ITibProperties props)
| Create an iterator over the keys in a map and associate it with a lock. More...
ITibMapIterator | CreateIterator (ITibProperties props)
| Create an iterator over the keys in a map. More...
IMessage | Get (string key)
| Get the value of a key in a map. More...
IMessage | Get (string key, ITibLock tiblock)
| Get the value of a key in a map as a locked operation. More...
IMessage[] | GetMultiple (String[] keys)
| Get the values for the specified keys from a map. More...
IMessage[] | GetMultiple (String[] keys, ITibLock tiblock)
| Get the values for the specified keys from a map as a locked operation More...
long | GetSize ()
| Returns the size of this map. More...
long | GetSize (ITibLock tiblock)
| Returns the size of this map. More...
string | Name ()
| Returns the name of this map. More...
void | Remove (string key)
| Remove a key/value pair from a map. More...
void | Remove (string key, ITibLock tiblock)
| Remove a key/value pair from a map as a locked operation. More...
void | RemoveAll ()
| Remove all key/value pairs from a map. More...
void | RemoveAll (ITibLock tiblock)
| Remove all key/value pairs from a map as a locked operation. More...
void | RemoveMultiple (String[] keys)
| Remove multiple keys and their corresponding values from the map </summary More...
void | RemoveMultiple (String[] keys, ITibLock tiblock)
| Remove multiple keys and their corresponding values from the map as a locked operation </summary More...
void | Set (string key, IMessage value)
| Set a key/value pair in a map. More...
void | Set (string key, IMessage value, ITibLock tiblock)
| Set a key/value pair in a map as a locked operation. More...
void | Set (String[] keys, IMessage[] values)
| Set multiple key/value pairs in a map. More...
void | Set (String[] keys, IMessage[] values, ITibLock tiblock)
| Set multiple key/value pairs in a map as a locked operation. More...

## Detailed Description

Programs can use maps to store key/value pairs in a persistence store.

Prerequisite: Administrators must enable dynamic last-value durables in a persistence store. For more information, see TIBCO FTL Administration.

This interface defines map calls.

To create a map object, see IRealm.CreateMap.

To delete a map from a store, see IRealm.RemoveMap.

Customers do not implement this interface.

## Member Function Documentation

## ◆ CreateIterator() [1/2]

ITibMapIterator TIBCO.FTL.ITibMap.CreateIterator | ( | ITibLock | tiblock,
|  | ITibProperties | 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 lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Subsequent calls to advance the iterator require that the process hold the lock.

Parameters

  tiblock | The iterator uses the lock represented by this lock object.
  props | String matcher properties: FTL.TIBMAPITER_PROPERTY_STRING_MATCHER

Returns
  A map iterator object.

## ◆ CreateIterator() [2/2]

ITibMapIterator TIBCO.FTL.ITibMap.CreateIterator | ( | ITibProperties | props | ) |

Create an iterator over the keys in a map.

The iterator produces every key/value pair in the map.

Parameters

  props | String matcher properties: FTL.TIBMAPITER_PROPERTY_STRING_MATCHER

Returns
  A map iterator object.

## ◆ Get() [1/2]

IMessage TIBCO.FTL.ITibMap.Get | ( | string | 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`.

Parameters

  key | The call gets a value for this key.

Returns
  A message.

## ◆ Get() [2/2]

IMessage TIBCO.FTL.ITibMap.Get | ( | string | key,
|  | ITibLock | tiblock
| ) |  |

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 lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

If the key is not set in the map, this call returns `Null`.

Parameters

  key | The call gets a value for this key.
  tiblock | The call requires the lock represented by this lock object.

Returns
  A message.

## ◆ GetMultiple() [1/2]

IMessage[] TIBCO.FTL.ITibMap.GetMultiple | ( | String[] | keys | ) |

Get the values for the specified keys from a map.

The values array will be populated by the library and returns. An entry of NULL in the values array means that no value is present for the key at the corresponding index of the keys array.

Parameters

  keys | The call gets values for the specfied keys.

Returns
  The values array is populated by the library an returned.

## ◆ GetMultiple() [2/2]

IMessage[] TIBCO.FTL.ITibMap.GetMultiple | ( | String[] | keys,
|  | ITibLock | tiblock
| ) |  |

Get the values for the specified keys from a map as a locked operation

The values array will be populated by the library and returned; An entry of NULL in the values array means that no value is present for the key at the corresponding index of the keys array.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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 sets an exception, and does not return any values.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Parameters

  keys | The call gets values for the specfied keys.
  tiblock | The call requires the lock represented by this lock object.

Returns
  The values array is populated by the library.

## ◆ GetSize() [1/2]

long TIBCO.FTL.ITibMap.GetSize | ( |  | ) |

Returns the size of this map.

Return the number of key/value pairs in the map.

Returns
  The size of the map.

## ◆ GetSize() [2/2]

long TIBCO.FTL.ITibMap.GetSize | ( | ITibLock | tiblock | ) |

Returns the size of this map.

Return the number of key/value pairs in the map using a specified lock.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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 the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Parameters

  tiblock | The call requires the lock represented by this lock object.

Returns
  The size of the map.

## ◆ Name()

string TIBCO.FTL.ITibMap.Name | ( |  | ) |

Returns the name of this map.

Returns
  The name of the map.

## ◆ Remove() [1/2]

void TIBCO.FTL.ITibMap.Remove | ( | string | key | ) |

Remove a key/value pair from a map.

Parameters

  key | The call removes this key.

## ◆ Remove() [2/2]

void TIBCO.FTL.ITibMap.Remove | ( | string | key,
|  | ITibLock | tiblock
| ) |  |

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 lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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/value pair.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Parameters

  key | The call removes this key.
  tiblock | The call requires the lock represented by this lock object.

## ◆ RemoveAll() [1/2]

void TIBCO.FTL.ITibMap.RemoveAll | ( |  | ) |

Remove all key/value pairs from a map.

This call does not destroy the map.

## ◆ RemoveAll() [2/2]

void TIBCO.FTL.ITibMap.RemoveAll | ( | ITibLock | tiblock | ) |

Remove all key/value pairs from a map as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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/value pairs.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

This call does not destroy the map.

Parameters

  tiblock | The call requires the lock represented by this lock object.

## ◆ RemoveMultiple() [1/2]

void TIBCO.FTL.ITibMap.RemoveMultiple | ( | String[] | keys | ) |

Remove multiple keys and their corresponding values from the map </summary

Parameters

  keys | The call removes the specified keys and their values.

## ◆ RemoveMultiple() [2/2]

void TIBCO.FTL.ITibMap.RemoveMultiple | ( | String[] | keys,
|  | ITibLock | tiblock
| ) |  |

Remove multiple keys and their corresponding values from the map as a locked operation </summary

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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 sets an exception, and does not return any values.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Parameters

  keys | The call removes the specified keys and their values.
  tiblock | The call requires the lock represented by this lock object.

## ◆ Set() [1/4]

void TIBCO.FTL.ITibMap.Set | ( | string | key,
|  | IMessage | 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.

Parameters

  key | The call sets a value for this key.
  value | The call sets this value for the key.

## ◆ Set() [2/4]

void TIBCO.FTL.ITibMap.Set | ( | string | key,
|  | IMessage | value,
|  | ITibLock | tiblock
| ) |  |

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 lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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 the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

If a value has already been set for the key, this call overwrites the existing value.

Parameters

  key | The call sets a value for this key.
  value | The call sets this value for the key.
  tiblock | The call requires the lock represented by this lock object.

## ◆ Set() [3/4]

void TIBCO.FTL.ITibMap.Set | ( | String[] | keys,
|  | IMessage[] | 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.

Parameters

  keys | The call sets values for these keys.
  values | The call sets these values for the corresponding keys.

## ◆ Set() [4/4]

void TIBCO.FTL.ITibMap.Set | ( | String[] | keys,
|  | IMessage[] | values,
|  | ITibLock | tiblock
| ) |  |

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 lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, 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 any values.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

If a value has already been set for the key, this call overwrites the existing value.

Parameters

  keys | The call sets values for these keys. keys.
  values | The call sets these values the corresponding keys.
  tiblock | The call requires the lock represented by this lock object.