com.thinkaurelius.titan.diskstorage.util

## Class MetricInstrumentedStore

- java.lang.Object
- - com.thinkaurelius.titan.diskstorage.util.MetricInstrumentedStore

- All Implemented Interfaces:
    KeyColumnValueStore

      public class MetricInstrumentedStore
      extends Object
      implements KeyColumnValueStore

  This class instruments an arbitrary KeyColumnValueStore backend with Metrics. The cumulative runtime of, number of invocations of, and number of exceptions thrown by each interface method are instrumented with Metrics (using Timer, Counter, and Counter again, respectively). The Metric names are generated by calling `MetricRegistry#name(backendClass, methodName, identifier)`, where methodName is the exact name of the method including capitalization, and identifier is "time", "calls", or "exceptions".

  In addition to the three standard metrics, `getSlice` and `getKeys` have some additional metrics related to their return values. `getSlice` carries metrics with the identifiers "entries-returned" and "entries-histogram". The first is a counter of total Entry objects returned. The second is a histogram of the size of Entry lists returned. `getKeys` returns a `RecordIterator` that manages metrics for its methods.

  This implementation does not catch any exceptions. Exceptions emitted by the backend store implementation are guaranteed to pass through this implementation's methods.

  The implementation includes repeated `try...catch` boilerplate that could be reduced by using reflection to determine the method name and by delegating Metrics object handling to a common helper that takes a Callable closure, but I'm not sure that the extra complexity and potential performance hit is worth it.
  Author:
    Dan LaRocque

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static List<String>` | `EVENT_NAMES`
    `static String` | `M_ACQUIRE_LOCK`
    `static String` | `M_CALLS`
    `static String` | `M_CLOSE`
    `static String` | `M_CONTAINS_KEY`
    `static String` | `M_ENTRIES_COUNT`
    `static String` | `M_ENTRIES_HISTO`
    `static String` | `M_EXCEPTIONS`
    `static String` | `M_GET_KEYS`
    `static String` | `M_GET_PART`
    `static String` | `M_GET_SLICE`
    `static String` | `M_ITERATOR`
    `static String` | `M_MUTATE`
    `static String` | `M_TIME`
    `static List<String>` | `OPERATION_NAMES`

    - ### Fields inherited from interface com.thinkaurelius.titan.diskstorage.keycolumnvalue.KeyColumnValueStore

      `NO_ADDITIONS, NO_DELETIONS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MetricInstrumentedStore(KeyColumnValueStore backend, String metricsStoreName)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `acquireLock(StaticBuffer key, StaticBuffer column, StaticBuffer expectedValue, StoreTransaction txh)` Attempts to claim a lock on the value at the specified `key` and `column` pair.
    `void` | `close()` Closes this store
    `KeyIterator` | `getKeys(KeyRangeQuery query, StoreTransaction txh)` Returns a `KeyIterator` over all keys that fall within the key-range specified by the given query and have one or more columns matching the column-range.
    `KeyIterator` | `getKeys(SliceQuery query, StoreTransaction txh)` Returns a `KeyIterator` over all keys in the store that have one or more columns matching the column-range.
    `String` | `getName()` Returns the name of this store.
    `EntryList` | `getSlice(KeySliceQuery query, StoreTransaction txh)` Retrieves the list of entries (i.e.
    `Map<StaticBuffer,EntryList>` | `getSlice(List<StaticBuffer> keys, SliceQuery query, StoreTransaction txh)` Retrieves the list of entries (i.e.
    `void` | `mutate(StaticBuffer key, List<Entry> additions, List<StaticBuffer> deletions, StoreTransaction txh)` Verifies acquisition of locks `txh` from previous calls to `KeyColumnValueStore.acquireLock(StaticBuffer, StaticBuffer, StaticBuffer, StoreTransaction)` , then writes supplied `additions` and/or `deletions` to `key` in the underlying data store.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### M_CONTAINS_KEY

          public static final String M_CONTAINS_KEY

      See Also:
        Constant Field Values

    - #### M_GET_SLICE

          public static final String M_GET_SLICE

      See Also:
        Constant Field Values

    - #### M_MUTATE

          public static final String M_MUTATE

      See Also:
        Constant Field Values

    - #### M_ACQUIRE_LOCK

          public static final String M_ACQUIRE_LOCK

      See Also:
        Constant Field Values

    - #### M_GET_KEYS

          public static final String M_GET_KEYS

      See Also:
        Constant Field Values

    - #### M_GET_PART

          public static final String M_GET_PART

      See Also:
        Constant Field Values

    - #### M_CLOSE

          public static final String M_CLOSE

      See Also:
        Constant Field Values

    - #### OPERATION_NAMES

          public static final List<String> OPERATION_NAMES

    - #### M_CALLS

          public static final String M_CALLS

      See Also:
        Constant Field Values

    - #### M_TIME

          public static final String M_TIME

      See Also:
        Constant Field Values

    - #### M_EXCEPTIONS

          public static final String M_EXCEPTIONS

      See Also:
        Constant Field Values

    - #### M_ENTRIES_COUNT

          public static final String M_ENTRIES_COUNT

      See Also:
        Constant Field Values

    - #### M_ENTRIES_HISTO

          public static final String M_ENTRIES_HISTO

      See Also:
        Constant Field Values

    - #### EVENT_NAMES

          public static final List<String> EVENT_NAMES

    - #### M_ITERATOR

          public static final String M_ITERATOR

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MetricInstrumentedStore

          public MetricInstrumentedStore(KeyColumnValueStore backend,
                                 String metricsStoreName)

  - ### Method Detail

    - #### getSlice

          public EntryList getSlice(KeySliceQuery query,
                           StoreTransaction txh)
                             throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Retrieves the list of entries (i.e. column-value pairs) for a specified query.
      Specified by:
        `getSlice` in interface `KeyColumnValueStore`
      Parameters:
        `query` - Query to get results for
        `txh` - Transaction
      Returns:
        List of entries up to a maximum of "limit" entries
      Throws:
        `BackendException` - when columnEnd < columnStart
      See Also:
        `KeySliceQuery`

    - #### getSlice

          public Map<StaticBuffer,EntryList> getSlice(List<StaticBuffer> keys,
                                             SliceQuery query,
                                             StoreTransaction txh)
                                               throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Retrieves the list of entries (i.e. column-value pairs) as specified by the given `SliceQuery` for all of the given keys together.
      Specified by:
        `getSlice` in interface `KeyColumnValueStore`
      Parameters:
        `keys` - List of keys
        `query` - Slicequery specifying matching entries
        `txh` - Transaction
      Returns:
        The result of the query for each of the given keys as a map from the key to the list of result entries.
      Throws:
        `BackendException`

    - #### mutate

          public void mutate(StaticBuffer key,
                    List<Entry> additions,
                    List<StaticBuffer> deletions,
                    StoreTransaction txh)
                      throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Verifies acquisition of locks `txh` from previous calls to `KeyColumnValueStore.acquireLock(StaticBuffer, StaticBuffer, StaticBuffer, StoreTransaction)` , then writes supplied `additions` and/or `deletions` to `key` in the underlying data store. Deletions are applied strictly before additions. In other words, if both an addition and deletion are supplied for the same column, then the column will first be deleted and then the supplied Entry for the column will be added.

      Implementations which don't support locking should skip the initial lock verification step but otherwise behave as described above.
      Specified by:
        `mutate` in interface `KeyColumnValueStore`
      Parameters:
        `key` - the key under which the columns in `additions` and `deletions` will be written
        `additions` - the list of Entry instances representing column-value pairs to create under `key`, or null to add no column-value pairs
        `deletions` - the list of columns to delete from `key`, or null to delete no columns
        `txh` - the transaction to use
      Throws:
        `PermanentLockingException` - if locking is supported by the implementation and at least one lock acquisition attempted by `KeyColumnValueStore.acquireLock(StaticBuffer, StaticBuffer, StaticBuffer, StoreTransaction)` has failed
        `BackendException`

    - #### acquireLock

          public void acquireLock(StaticBuffer key,
                         StaticBuffer column,
                         StaticBuffer expectedValue,
                         StoreTransaction txh)
                           throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Attempts to claim a lock on the value at the specified `key` and `column` pair. These locks are discretionary.

      If locking fails, implementations of this method may, but are not required to, throw `PermanentLockingException`. This method is not required to determine whether locking actually succeeded and may return without throwing an exception even when the lock can't be acquired. Lock acquisition is only only guaranteed to be verified by the first call to `KeyColumnValueStore.mutate(StaticBuffer, List, List, StoreTransaction)` on any given `txh`.

      The `expectedValue` must match the actual value present at the `key` and `column` pair. If the true value does not match the `expectedValue`, the lock attempt fails and `LockingException` is thrown. This method may check `expectedValue`. The `mutate()` mutate is required to check it.

      When this method is called multiple times on the same `key`, `column`, and `txh`, calls after the first have no effect.

      Locks acquired by this method must be automatically released on transaction `commit()` or `rollback()`.

      Implementations which don't support locking should throw `UnsupportedOperationException`.
      Specified by:
        `acquireLock` in interface `KeyColumnValueStore`
      Parameters:
        `key` - the key on which to lock
        `column` - the column on which to lock
        `expectedValue` - the expected value for the specified key-column pair on which to lock (null means the pair must have no value)
        `txh` - the transaction to use
      Throws:
        `PermanentLockingException` - the lock could not be acquired due to contention with other transactions or a locking-specific storage problem
        `BackendException`

    - #### getKeys

          public KeyIterator getKeys(KeyRangeQuery query,
                            StoreTransaction txh)
                              throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Returns a `KeyIterator` over all keys that fall within the key-range specified by the given query and have one or more columns matching the column-range. Calling `KeyIterator.getEntries()` returns the list of all entries that match the column-range specified by the given query.

      This method is only supported by stores which keep keys in byte-order.
      Specified by:
        `getKeys` in interface `KeyColumnValueStore`
      Returns:
      Throws:
        `BackendException`

    - #### getKeys

          public KeyIterator getKeys(SliceQuery query,
                            StoreTransaction txh)
                              throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Returns a `KeyIterator` over all keys in the store that have one or more columns matching the column-range. Calling `KeyIterator.getEntries()` returns the list of all entries that match the column-range specified by the given query.

      This method is only supported by stores which do not keep keys in byte-order.
      Specified by:
        `getKeys` in interface `KeyColumnValueStore`
      Returns:
      Throws:
        `BackendException`

    - #### getName

          public String getName()

      Description copied from interface: `KeyColumnValueStore`
      Returns the name of this store. Each store has a unique name which is used to open it.
      Specified by:
        `getName` in interface `KeyColumnValueStore`
      Returns:
        store name
      See Also:
        `KeyColumnValueStoreManager.openDatabase(String)`

    - #### close

          public void close()
                     throws BackendException

      Description copied from interface: `KeyColumnValueStore`
      Closes this store
      Specified by:
        `close` in interface `KeyColumnValueStore`
      Throws:
        `BackendException`

Copyright © 2012–2014. All rights reserved.