ValueQueue (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.crypto.key.kms, class: ValueQueue

Package org.apache.hadoop.crypto.key.kms

# Class ValueQueue<E>

java.lang.Object
org.apache.hadoop.crypto.key.kms.ValueQueue<E>

@Private public class ValueQueue<E> extends Object
A Utility class that maintains a Queue of entries for a given key. It tries to ensure that there is are always at-least `numValues` entries available for the client to consume for a particular key. It also uses an underlying Cache to evict queues for keys that have not been accessed for a configurable period of time. Implementing classes are required to implement the `QueueRefiller` interface that exposes a method to refill the queue, when empty

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `ValueQueue.QueueRefiller<E>`
  QueueRefiller interface a client must implement to use this class
  `static enum`
  `ValueQueue.SyncGenerationPolicy`
  Policy to decide how many values to return to client when client asks for "n" values and Queue is empty.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ValueQueue(int numValues, float lowWaterMark, long expiry, int numFillerThreads, ValueQueue.QueueRefiller<E> fetcher)`
  `ValueQueue(int numValues, float lowWatermark, long expiry, int numFillerThreads, ValueQueue.SyncGenerationPolicy policy, ValueQueue.QueueRefiller<E> refiller)`
  Constructor takes the following tunable configuration parameters

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `drain(String keyName)`
  Drains the Queue for the provided key.
  `List<E>`
  `getAtMost(String keyName, int num)`
  This removes the "num" values currently at the head of the Queue for the provided key.
  `E`
  `getNext(String keyName)`
  This removes the value currently at the head of the Queue for the provided key.
  `int`
  `getSize(String keyName)`
  Get size of the Queue for keyName.
  `void`
  `initializeQueuesForKeys(String... keyNames)`
  Initializes the Value Queues for the provided keys by calling the fill Method with "numInitValues" values
  `void`
  `shutdown()`
  Cleanly shutdown

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

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

- ## Constructor Details

  - ### ValueQueue

    public ValueQueue(int numValues, float lowWatermark, long expiry, int numFillerThreads, ValueQueue.SyncGenerationPolicy policy, ValueQueue.QueueRefiller<E> refiller)
    Constructor takes the following tunable configuration parameters
    Parameters:
      `numValues` - The number of values cached in the Queue for a particular key.
      `lowWatermark` - The ratio of (number of current entries/numValues) below which the `fillQueueForKey()` funciton will be invoked to fill the Queue.
      `expiry` - Expiry time after which the Key and associated Queue are evicted from the cache.
      `numFillerThreads` - Number of threads to use for the filler thread
      `policy` - The SyncGenerationPolicy to use when client calls "getAtMost"
      `refiller` - implementation of the QueueRefiller

  - ### ValueQueue

    public ValueQueue(int numValues, float lowWaterMark, long expiry, int numFillerThreads, ValueQueue.QueueRefiller<E> fetcher)

- ## Method Details

  - ### initializeQueuesForKeys

    public void initializeQueuesForKeys(String... keyNames) throws IOException
    Initializes the Value Queues for the provided keys by calling the fill Method with "numInitValues" values
    Parameters:
      `keyNames` - Array of key Names
    Throws:
      `IOException` - if initialization fails for any provided keys

  - ### getNext

    public E getNext(String keyName) throws IOException, ExecutionException
    This removes the value currently at the head of the Queue for the provided key. Will immediately fire the Queue filler function if key does not exist. If Queue exists but all values are drained, It will ask the generator function to add 1 value to Queue and then drain it.
    Parameters:
      `keyName` - String key name
    Returns:
      E the next value in the Queue
    Throws:
      `IOException` - raised on errors performing I/O.
      `ExecutionException` - executionException.

  - ### drain

    public void drain(String keyName)
    Drains the Queue for the provided key.
    Parameters:
      `keyName` - the key to drain the Queue for

  - ### getSize

    @VisibleForTesting public int getSize(String keyName)
    Get size of the Queue for keyName. This is only used in unit tests.
    Parameters:
      `keyName` - the key name
    Returns:
      int queue size. Zero means the queue is empty or the key does not exist.

  - ### getAtMost

    public List<E> getAtMost(String keyName, int num) throws IOException, ExecutionException
    This removes the "num" values currently at the head of the Queue for the provided key. Will immediately fire the Queue filler function if key does not exist How many values are actually returned is governed by the `SyncGenerationPolicy` specified by the user.
    Parameters:
      `keyName` - String key name
      `num` - Minimum number of values to return.
    Returns:
      List<E> values returned
    Throws:
      `IOException` - raised on errors performing I/O.
      `ExecutionException` - execution exception.

  - ### shutdown

    public void shutdown()
    Cleanly shutdown