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

    All Methods Instance Methods Abstract Methods
    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`