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 java.lang.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 class	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(java.lang.String keyName)	Drains the Queue for the provided key.
java.util.List<E>	getAtMost(java.lang.String keyName, int num)	This removes the "num" values currently at the head of the Queue for the provided key.
E	getNext(java.lang.String keyName)	This removes the value currently at the head of the Queue for the provided key.
int	getSize(java.lang.String keyName)	Get size of the Queue for keyName.
void	initializeQueuesForKeys(java.lang.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 Detail

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 Detail

initializeQueuesForKeys

public void initializeQueuesForKeys(java.lang.String... keyNames)
                             throws java.util.concurrent.ExecutionException

Initializes the Value Queues for the provided keys by calling the fill Method with "numInitValues" values

Parameters:

keyNames - Array of key Names

Throws:

java.util.concurrent.ExecutionException - executionException.

getNext

public E getNext(java.lang.String keyName)
          throws java.io.IOException,
                 java.util.concurrent.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:

java.io.IOException - raised on errors performing I/O.

java.util.concurrent.ExecutionException - executionException.

drain

public void drain(java.lang.String keyName)

Drains the Queue for the provided key.

Parameters:

keyName - the key to drain the Queue for

getSize

@VisibleForTesting
public int getSize(java.lang.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 java.util.List<E> getAtMost(java.lang.String keyName,
                                   int num)
                            throws java.io.IOException,
                                   java.util.concurrent.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:

java.io.IOException - raised on errors performing I/O.

java.util.concurrent.ExecutionException - execution exception.

shutdown

public void shutdown()

Cleanly shutdown