com.tibco.ftl

Interface TibMap

public interface TibMap

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

To create a map object, see Realm.createMap.

To delete a map from a store, see Realm.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.

Since:

4.2

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION Retry duration for map operations; double.
static java.lang.String	PROPERTY_STRING_LABEL Property name for a map label; string.

Method Summary

Modifier and Type	Method and Description
void	close() Destroy a map object.
TibMapIterator	createIterator(TibLock lock, TibProperties props) Create an iterator over the keys in a map and associate it with a lock.
TibMapIterator	createIterator(TibProperties props) Create an iterator over the keys in a map.
Message	get(java.lang.String key) Get the value of a key in a map.
Message	get(java.lang.String key, TibLock lock) Get the value of a key in a map as a locked operation.
long	getSize() Returns the size of the map.
long	getSize(TibLock lock) Returns the size of the map as a locked operation.
void	remove(java.lang.String key) Remove a key/value pair from a map.
void	remove(java.lang.String key, TibLock lock) Remove a key/value pair from a map as a locked operation.
void	set(java.lang.String[] keys, Message[] values) Set Multiple key/value pairs in a map.
void	set(java.lang.String[] keys, Message[] values, TibLock lock) Set multiple key/value pairs in a map as a locked operation.
void	set(java.lang.String key, Message value) Set a key/value pair in a map.
void	set(java.lang.String key, Message value, TibLock lock) Set a key/value pair in a map as a locked operation.

Field Detail

PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

static final java.lang.String PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Retry duration for map operations; double.

When Realm.createMap(java.lang.String, java.lang.String, com.tibco.ftl.TibProperties), set(java.lang.String, com.tibco.ftl.Message), get(java.lang.String), or remove(java.lang.String) (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:

• 0 No retry. The call raises an exception.
• -1 Synchronously retry the interaction until it succeeds. The call returns only upon success.
• n (Any positive double value) Retry the interaction for n seconds. Return upon success or raise an exception after timeout.

Closing the realm or destroying the map supersedes and cancels retry behavior.

This property does not apply to map iterators.

See Also:

Constant Field Values

PROPERTY_STRING_LABEL

static final java.lang.String PROPERTY_STRING_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.

See Also:

Realm.createMap, Constant Field Values

Method Detail

close

void close()
    throws FTLException

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 Realm.removeMap.

Throws:

FTLException

Since:

4.2

set

void set(java.lang.String key,
         Message value)
  throws FTLException

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.

Throws:

FTLException

Since:

4.2

set

void set(java.lang.String key,
         Message value,
         TibLock lock)
  throws FTLException

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.

Parameters:

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.

Throws:

FTLException

Since:

4.2

set

void set(java.lang.String[] keys,
         Message[] values)
  throws FTLException

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.

Throws:

FTLException

Since:

5.4

set

void set(java.lang.String[] keys,
         Message[] values,
         TibLock lock)
  throws FTLException

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.

Parameters:

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.

Throws:

FTLException

Since:

5.4

get

Message get(java.lang.String key)
     throws FTLException

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:

The message object stored as the value of the key.

Throws:

FTLException

Since:

4.2

get

Message get(java.lang.String key,
            TibLock lock)
     throws FTLException

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.

Parameters:

key - The call gets a value for this key.

lock - The call requires the lock represented by this lock object.

Returns:

The message object stored as the value of the key.

Throws:

FTLException

Since:

4.2

remove

void remove(java.lang.String key)
     throws FTLException

Remove a key/value pair from a map.

Parameters:

key - The call removes this key.

Throws:

FTLException

Since:

4.2

remove

void remove(java.lang.String key,
            TibLock lock)
     throws FTLException

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.

Parameters:

key - The call removes this key.

lock - The call requires the lock represented by this lock object.

Throws:

FTLException

Since:

4.2

createIterator

TibMapIterator createIterator(TibProperties props)
                       throws FTLException

Create an iterator over the keys in a map.

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

Parameters:

props - Optional. Supply null to omit.

String matcher properties:

• TibMapIterator.PROPERTY_STRING_MATCHER

Returns:

A map iterator object.

Throws:

FTLException

Since:

4.2

createIterator

TibMapIterator createIterator(TibLock lock,
                              TibProperties props)
                       throws FTLException

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.

Parameters:

lock - The iterator uses the lock represented by this lock object.

props - Optional. Supply null to omit.

String matcher properties:

• TibMapIterator.PROPERTY_STRING_MATCHER

props - Limit the iterator to only matches of the value to this string. For all key/value pairs, supply null.

Returns:

A map iterator object.

Throws:

FTLException

Since:

4.2

getSize

long getSize()
      throws FTLException

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

Throws:

FTLException

Since:

6.2

getSize

long getSize(TibLock lock)
      throws FTLException

Returns the size of the map as a locked operation. 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 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 size of the map object.

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.

Parameters:

lock - The call requires the lock represented by this lock object.

Throws:

FTLException

Since:

6.2