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.
Message[]	getMultiple(java.lang.String[] keys) Get the values for the specified keys from a map.
Message[]	getMultiple(java.lang.String[] keys, TibLock tiblock) Get the values for the specified keys from 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.
java.lang.String	name() Return the name of the map object.
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	removeAll() Remove all key/value pairs from a map.
void	removeAll(TibLock lock) Remove all key/value pairs from a map as a locked operation.
void	removeMultiple(java.lang.String[] keys) Remove multiple keys and their corresponding values from the map
void	removeMultiple(java.lang.String[] keys, TibLock tiblock) Remove multiple keys and their corresponding values from the 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), getSize(), remove(java.lang.String), or removeAll() (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 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.

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

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

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

Throws:

FTLException

Since:

4.2

removeAll

void removeAll()
        throws FTLException

Remove all key/value pairs from a map.

This call does not destroy the map.

Throws:

FTLException

Since:

6.6

removeAll

void removeAll(TibLock lock)
        throws FTLException

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:

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

Throws:

FTLException

Since:

6.6

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 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:

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

Parameters:

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

Throws:

FTLException

Since:

6.2

name

java.lang.String name()

Return the name of the map object.

Returns:

The name of the map object.

Since:

6.5

getMultiple

Message[] getMultiple(java.lang.String[] keys)
               throws FTLException

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.

Throws:

FTLException

getMultiple

Message[] getMultiple(java.lang.String[] keys,
                      TibLock tiblock)
               throws FTLException

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.

Throws:

FTLException

removeMultiple

void removeMultiple(java.lang.String[] keys)
             throws FTLException

Remove multiple keys and their corresponding values from the map

Parameters:

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

Throws:

FTLException

removeMultiple

void removeMultiple(java.lang.String[] keys,
                    TibLock tiblock)
             throws FTLException

Remove multiple keys and their corresponding values from the 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 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.

Throws:

FTLException