com.waveset.util
Class Quota

java.lang.Object
  extended bycom.waveset.util.Quota
All Implemented Interfaces:
WavesetProperties.Listener

public class Quota
extends java.lang.Object
implements WavesetProperties.Listener

A simple class that provides arbitrary named quotas for things and an interface to wait when the quota is exceeded for an item. Keeps a map of quota pools. Entries are maps of fifo semaphores. Each pool will have settings like default limits for entries and lists of entry names that have unlimited quotas. An example of this is the pool for administrator background saves which has a limit read from waveset.properties and can have unlimited saves for Configurator. Or not. Quotas can also be reset and dumped for field debugging. To use this, you must define a quota item. This can be done in WavesetProperties, or in code by calling: Quota.addItem("myQuota", myLimit);

Next, instrument any code that needs to be limited to call: Quota.acquire("myQuota"); //block indefinitely or boolean acquired = Quota.acquire("myQuota", 1000); //wait one second If you specify a wait limit, your code must check the return value to see whether the quota was successfully acquired.

Finally, instrument the same code to free the quota when it is finished: Quota.release("myQuota");

For more sophisticated schemes, you may define a separate quota pool. This quota pool specifies a default concurrent usage limit, but this can be overridden on an item-by-item basis. Use this to specify, for example, a concurrent usage limit of ten that applies to most administrators trying to use something, but for which Configurator has unlimited access.


Field Summary
static java.lang.String code_id
           
static java.lang.String MAIN_POOL
           
static int NO_LIMIT
          Indicates that any number of requestors may concurrently request the same quota.
static long WAIT_FOREVER
          Indicates that the requestor is willing to block indefinitely waiting to acquire a quota.
 
Method Summary
static boolean acquire(java.lang.String itemName)
          Acquire an item from the default pool of quotas.
static boolean acquire(java.lang.String itemName, long waitMillis)
          Acquire an item from the default pool of quotas.
static boolean acquire(java.lang.String poolName, java.lang.String itemName)
          From the named pool of quotas, acquire an item.
static boolean acquire(java.lang.String poolName, java.lang.String itemName, long waitMillis)
          Acquire an item from the specified pool of quotas.
static void addItem(java.lang.String itemName, int concurrentUsageLimit)
          Add an item to the default quota pool.
static void addItem(java.lang.String poolName, java.lang.String itemName, int concurrentUsageLimit)
          Add an item to an existing quota pool.
static void addPool(java.lang.String poolName, int defaultConcurrentUsageLimit)
          Add a pool if it does not exist.
protected static com.waveset.util.Quota.QuotaPool getPool(java.lang.String poolName)
           
static Quota getQuota()
          Deprecated. - Don't need this. All public methods are now static.
static boolean itemExists(java.lang.String poolName, java.lang.String itemName)
          Check for the existence of a quotaPoolItem
protected static java.lang.String makeSafeName(java.lang.String inName)
           
static boolean poolExists(java.lang.String poolName)
          Check for the existence of a quota Pool
 void propertiesFileChanged()
          Read the values of the properties file and update our settings.
static void release(java.lang.String itemName)
          Release the specified quota item from the default pool.
static void release(java.lang.String poolName, java.lang.String itemName)
          Release the specified quota item in the specified pool.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

code_id

public static final java.lang.String code_id
See Also:
Constant Field Values

WAIT_FOREVER

public static final long WAIT_FOREVER
Indicates that the requestor is willing to block indefinitely waiting to acquire a quota.

See Also:
Constant Field Values

NO_LIMIT

public static final int NO_LIMIT
Indicates that any number of requestors may concurrently request the same quota.

See Also:
Constant Field Values

MAIN_POOL

public static final java.lang.String MAIN_POOL
See Also:
Constant Field Values
Method Detail

propertiesFileChanged

public void propertiesFileChanged()
Read the values of the properties file and update our settings. Properties file settings: Quota.poolNames - comma delimited list of pool names Quota.pool.xxx.defaultLimit - for each pool, settings Quota.pool.xxx.unlimitedItems - comma sep list of items with no limit Quota.pool.xxx.items - comma sep list of items Quota.pool.xxx.item.yyy.limit - limit for the item So the basic algorithm is to walk over the names in poolNames, building properties file variables and setting up the pools.

Specified by:
propertiesFileChanged in interface WavesetProperties.Listener

getQuota

public static Quota getQuota()
Deprecated. - Don't need this. All public methods are now static.


addItem

public static void addItem(java.lang.String itemName,
                           int concurrentUsageLimit)
Add an item to the default quota pool.

Parameters:
itemName - - the name of the thing we want to limit.
concurrentUsageLimit - - the maximum number of requestors who can have the thing at any one time.
Throws:
java.lang.NullPointerException - if itemName is null.
java.util.NoSuchElementException - if the pool does not exist.

addItem

public static void addItem(java.lang.String poolName,
                           java.lang.String itemName,
                           int concurrentUsageLimit)
Add an item to an existing quota pool.

Parameters:
poolName - - the pool that should contain the item.
itemName - - the name of the thing we want to limit.
concurrentUsageLimit - - the maximum number of requestors who can have the thing at any one time.
Throws:
java.lang.NullPointerException - if poolName or itemName is null.
java.util.NoSuchElementException - if the pool does not exist.

addPool

public static void addPool(java.lang.String poolName,
                           int defaultConcurrentUsageLimit)
Add a pool if it does not exist.

Parameters:
poolName - - the name of the pool to add.
defaultConcurrentUsageLimit - - the maximum number of requestors who can have an item from this pool at any one time unless the item specifies a concurrentUsageLimit.
Throws:
java.lang.NullPointerException - if poolName or itemName is null.

poolExists

public static boolean poolExists(java.lang.String poolName)
Check for the existence of a quota Pool

Parameters:
poolName - - the name of the quota pool.
Throws:
java.lang.NullPointerException - if poolName is null.

getPool

protected static com.waveset.util.Quota.QuotaPool getPool(java.lang.String poolName)
Parameters:
poolName - - the name of the quota pool.
Returns:
the named quota pool (if any); otherwise null.

itemExists

public static boolean itemExists(java.lang.String poolName,
                                 java.lang.String itemName)
Check for the existence of a quotaPoolItem

Parameters:
poolName - - the name of the pool expected to contain the item.
itemName - - the name of the thing we want to limit
Returns:
true if the specified quotaPoolItem exists; otherwise false.
Throws:
java.lang.NullPointerException - if poolName or itemName is null.

makeSafeName

protected static java.lang.String makeSafeName(java.lang.String inName)

acquire

public static boolean acquire(java.lang.String poolName,
                              java.lang.String itemName)
                       throws java.lang.InterruptedException
From the named pool of quotas, acquire an item. Wait indefinitely if the quota is used up.

Parameters:
poolName - - the name of the pool expected to contain the item.
itemName - - the name of the thing we want to limit The classic example is acquire("ReProvision", "bob"). NOTE: MUST match the calls to release().
Throws:
java.lang.InterruptedException

acquire

public static boolean acquire(java.lang.String poolName,
                              java.lang.String itemName,
                              long waitMillis)
                       throws java.lang.InterruptedException
Acquire an item from the specified pool of quotas.

Parameters:
poolName - - the name of the pool expected to contain the item.
itemName - - the name of the thing we want to limit
waitMillis - - wait this long if the quota is used up.
Returns:
true if the item is successfully acquired; otherwise ?????
Throws:
java.lang.NullPointerException - - if the specified poolName is null. NOTE: MUST match the calls to release().
java.lang.InterruptedException

acquire

public static boolean acquire(java.lang.String itemName)
                       throws java.lang.InterruptedException
Acquire an item from the default pool of quotas. Wait indefinitely if the quota item is used up.

Parameters:
itemName - - the name of the thing we want to limit
Returns:
true if the item is successfully acquired; otherwise ?????
Throws:
java.lang.NullPointerException - - if the specified poolName is null. NOTE: MUST match the calls to release().
java.lang.InterruptedException

acquire

public static boolean acquire(java.lang.String itemName,
                              long waitMillis)
                       throws java.lang.InterruptedException
Acquire an item from the default pool of quotas. Wait indefinitely if the quota item is used up.

Parameters:
itemName - - the name of the thing we want to limit
waitMillis - - wait this long if the quota is used up.
Returns:
true if the item is successfully acquired; otherwise ?????
Throws:
java.lang.NullPointerException - - if the specified poolName is null. NOTE: MUST match the calls to release().
java.lang.InterruptedException

release

public static void release(java.lang.String poolName,
                           java.lang.String itemName)
Release the specified quota item in the specified pool.

Parameters:
poolName - - the name of the pool expected to contain the item.
itemName - - the name of the thing we want to limit.
Throws:
java.lang.NullPointerException - - if the specified poolName is null. NOTE: MUST match the calls to acquire().

release

public static void release(java.lang.String itemName)
Release the specified quota item from the default pool.

Parameters:
itemName - - the name of the thing we want to limit. NOTE: MUST match the calls to acquire().