QuickCache

java.lang.Object
- org.qbroker.common.QuickCache

All Implemented Interfaces:: java.util.Comparator<long[]>

public class QuickCache
extends java.lang.Object
implements java.util.Comparator<long[]>

QuickCache is a HashMap with the unique keys and objects, TTLs (time-to-live) and timestamps, as well as the MetaData. All the objects have their own TTLs to control when to expire. Once an object expires, it will not be visible any more. The expired object will be removed from the cache eventually by the automatic or passive disfragmentation. Therefore, the size of QuickCache is self adjustable with the time and the load.

QuickCache caches objects with their own expiration time. Since each object automatically expires once it passes its TTL, the size of the cache changes with time and load. Therefore, you can control the size of the cache by adjusting the TTLs according to the load.

QuickCache also has timeout and threshold to control the automatic disfragmentations. When certain objects expire, QuickCache will not clean them up immediately. It waits until the certain conditions are met. You can also turn on/off the chache temporarily via its status. Each time the status of the cache changes, its mtime changes too. For auto part, if the timeout is set to 0, the time-driven disfragmentation is disabled. If the threshold is set to 0, the size-driven disfragmentation is disabled.

Besides the objects, QuickCache also stores MetaData for each objects. Metadata is an opaque array with integers. It is up to the developers to decide how many integers and what they stand for. For example, users can put id and gid into the MetaData array.

For each object, QuickCache will create some internal properties, like TIME, COUNT and TTL. QuickCache uses them to manage the cached objects. However, these internal properties may mean differently according to their initial options. For example, TIME is the timestamp of either the modification time (mtime) or the access time (atime). COUNT may mean the access count (acount) or the modification count (mcount). TTL controls if and when the object is expired and is ready to be removed by the process of disfragmentation. According to the cache option, TTL may be either the number of milliseconds as the expiration time or the maximum count as the threshold to determine if the object has expired or not. In case of the expiration time, TTL really means Time-To-Live which controls when the object expires. In case of the count, TTL is the maximum count required for an object to be treaded as expired. Hence if the COUNT is less than or equal to TTL, the object is treated as expired since it is not used often enough. The expired objects will be removed eventually by disfragmentation.

Since QuickCache is a dynamic container, it may actively or passively remove those objects that are not needed any longer, in order to free memory. The disfragmentation may base on either TIME or COUNT. Therefore, there are 8 different ways to interpret the internal properties. Each combination defines a unique way for QuickCache to determin what objects can be removed. Here is the list for all 8 options:

Options
Option	Time	Count	TTL
META_MTAC	mtime	acount	TIME
META_MCMT	mtime	mcount	COUNT
META_MTMC	mtime	mcount	TIME
META_MCAT	atime	mcount	COUNT
META_ATAC	atime	acount	TIME
META_ACMT	mtime	acount	COUNT
META_ATMC	atime	mcount	TIME
META_ACAT	atime	acount	COUNT

The default is META_MTAC.

This is NOT MT-Safe. Therefore please use it with care.

Author:: yannanlu@yahoo.com

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CACHE_EXPIRED`
`static int`	`CACHE_NONE`
`static int`	`CACHE_OFF`
`static int`	`CACHE_ON`
`static int`	`META_ACAT`
`static int`	`META_ACMT`
`static int`	`META_ATAC`
`static int`	`META_ATMC`
`static int`	`META_DEFAULT`
`static int`	`META_MCAT`
`static int`	`META_MCMT`
`static int`	`META_MTAC`
`static int`	`META_MTMC`

Constructor Summary

Constructors
Constructor and Description

QuickCache(java.lang.String name, int option, int timeout, int threshold)

Constructors
Constructor and Description
`QuickCache(java.lang.String name, int option, int timeout, int threshold)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()`
`int`	`compare(long[] a, long[] b)`
`boolean`	`containsKey(java.lang.String key)` It only checks the existence of the object identified by the key, no matter whether the object has expired or not.
`java.lang.String[]`	`disfragment()`
`java.lang.String[]`	`disfragment(long currentTime)` It removes all expired objects, resets all sequence numbers and returns an array of all expired keys that have been just removed.
`int`	`expire(java.lang.String key)`
`int`	`expire(java.lang.String key, long currentTime)` It expires the object and returns 0 if the ttl is larger than zero.
`protected void`	`finalize()`
`java.lang.Object`	`get(java.lang.String key)`
`java.lang.Object`	`get(java.lang.String key, long currentTime)` It returns the object of the key only if it has not expired yet.
`long`	`getCount(java.lang.String key)` It returns the count for the object referenced by the key.
`int[]`	`getMetaData(java.lang.String key)` It returns the metadata for the object referenced by the key no matter whether the object has expired or not.
`long`	`getMTime()`
`java.lang.String`	`getName()`
`int`	`getOption()`
`int`	`getStatus()`
`long`	`getTimeout()`
`long`	`getTimestamp(java.lang.String key)` It returns the timestamp for the object referenced by the key.
`int`	`getTTL(java.lang.String key)` It returns the ttl for the object referenced by the key.
`int`	`insert(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj)`
`int`	`insert(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj, long currentTime)` It checks the existence of the key first.
`protected int`	`invalidate(java.lang.String key, long currentTime)` It sets the object into null no matter what the ttl is.
`boolean`	`isExpired(java.lang.String key)`
`boolean`	`isExpired(java.lang.String key, long currentTime)` It returns true if the object of the key has expired, or false otherwise.
`java.util.Set<java.lang.String>`	`keySet()` returns a set for all existing keys
`java.lang.Object`	`replace(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj)`
`java.lang.Object`	`replace(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj, long currentTime)` It replaces the existing object or inserts as the new object if there is no such key in the cache.
`void`	`setStatus(int status)` sets the CacheStatus and the modify time as the currentTime
`void`	`setStatus(int status, long currentTime)` sets the CacheStatus and the modify time
`int`	`size()`
`java.lang.Object[]`	`sortedEntries()`
`java.lang.String[]`	`sortedKeys()` It returns an array of all the existing keys in the NATURAL order no matter whether they have expired or not.
`int`	`touch(java.lang.String key, long timestamp)`
`int`	`touch(java.lang.String key, long timestamp, long currentTime)` It updates mtime or mcount of the key if it has not expired at the given currentTime yet.
`int`	`update(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj)`
`int`	`update(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj, long currentTime)` It checks the existence of the key first.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator
comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

- Field Detail
  - CACHE_NONE
```
public static final int CACHE_NONE
```
    See Also:
    
    Constant Field Values
  - CACHE_ON
```
public static final int CACHE_ON
```
    See Also:
    
    Constant Field Values
  - CACHE_OFF
```
public static final int CACHE_OFF
```
    See Also:
    
    Constant Field Values
  - CACHE_EXPIRED
```
public static final int CACHE_EXPIRED
```
    See Also:
    
    Constant Field Values
  - META_DEFAULT
```
public static final int META_DEFAULT
```
    See Also:
    
    Constant Field Values
  - META_MTAC
```
public static final int META_MTAC
```
    See Also:
    
    Constant Field Values
  - META_MCMT
```
public static final int META_MCMT
```
    See Also:
    
    Constant Field Values
  - META_MTMC
```
public static final int META_MTMC
```
    See Also:
    
    Constant Field Values
  - META_MCAT
```
public static final int META_MCAT
```
    See Also:
    
    Constant Field Values
  - META_ATAC
```
public static final int META_ATAC
```
    See Also:
    
    Constant Field Values
  - META_ACMT
```
public static final int META_ACMT
```
    See Also:
    
    Constant Field Values
  - META_ATMC
```
public static final int META_ATMC
```
    See Also:
    
    Constant Field Values
  - META_ACAT
```
public static final int META_ACAT
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - QuickCache
```
public QuickCache(java.lang.String name,
                  int option,
                  int timeout,
                  int threshold)
```
- Method Detail
  - size
```
public int size()
```
  - getName
```
public java.lang.String getName()
```
  - getOption
```
public int getOption()
```
  - getTimeout
```
public long getTimeout()
```
  - getMTime
```
public long getMTime()
```
  - getStatus
```
public int getStatus()
```
  - setStatus
```
public void setStatus(int status,
                      long currentTime)
```
    sets the CacheStatus and the modify time
  - setStatus
```
public void setStatus(int status)
```
    sets the CacheStatus and the modify time as the currentTime
  - insert
```
public int insert(java.lang.String key,
                  long timestamp,
                  int ttl,
                  int[] meta,
                  java.lang.Object obj,
                  long currentTime)
```
    It checks the existence of the key first. If the key exists, it checks the TTL. If the key has expired, it updates the object and timestamp, then returns 0. If the key has not expired, it returns -1 for insert failure. If the key does not exist, it just inserts the object and timestamp, then returns 1.
    
    return code:
    1: new object inserted successfully
    0: object expired, so updated the object and its meta data
    -1: object exists, no changes made to it
  - insert
```
public int insert(java.lang.String key,
                  long timestamp,
                  int ttl,
                  int[] meta,
                  java.lang.Object obj)
```
  - update
```
public int update(java.lang.String key,
                  long timestamp,
                  int ttl,
                  int[] meta,
                  java.lang.Object obj,
                  long currentTime)
```
    It checks the existence of the key first. If the key exists, it check the expiration of the key. If the key has expired, it updates the object and timestamp, then returns 1. If the key has not expired, it updates anyway and returns 0. If the key does not exist, it returns -1 for failure.
    
    return code:
    1: object expired, but it and its meta data are updated
    0: unexpired object updated successfully
    -1: update failed due to its not existence
  - update
```
public int update(java.lang.String key,
                  long timestamp,
                  int ttl,
                  int[] meta,
                  java.lang.Object obj)
```
  - touch
```
public int touch(java.lang.String key,
                 long timestamp,
                 long currentTime)
```
    It updates mtime or mcount of the key if it has not expired at the given currentTime yet. It retruns 0 on success, -1 if no key is found or 1 if the object has expired already.
  - touch
```
public int touch(java.lang.String key,
                 long timestamp)
```
  - isExpired
```
public boolean isExpired(java.lang.String key,
                         long currentTime)
```
    It returns true if the object of the key has expired, or false otherwise. If the key is not found, it throws IllegalArgumentException for failure.
  - isExpired
```
public boolean isExpired(java.lang.String key)
```
  - replace
```
public java.lang.Object replace(java.lang.String key,
                                long timestamp,
                                int ttl,
                                int[] meta,
                                java.lang.Object obj,
                                long currentTime)
```
    It replaces the existing object or inserts as the new object if there is no such key in the cache. It updates the metadata and checks the TTL to determine what to return. If the object does not exist, it just returns the new object back. If the existing object has not expired yet, it just returns the replaced object. If the existing object has expired, normally the method returns null except for the case that TTL is on count and COUNT is reset to 0 by touch(). In that case, it returns the new object, just like the original object does not exist.
    
    returned object:
    itself: new object inserted successfully or invalid object replaced
    null: object expired and replaced
    other: replaced object, its meta data updated
  - replace
```
public java.lang.Object replace(java.lang.String key,
                                long timestamp,
                                int ttl,
                                int[] meta,
                                java.lang.Object obj)
```
  - containsKey
```
public boolean containsKey(java.lang.String key)
```
    It only checks the existence of the object identified by the key, no matter whether the object has expired or not.
  - getTTL
```
public int getTTL(java.lang.String key)
```
    It returns the ttl for the object referenced by the key.
  - getTimestamp
```
public long getTimestamp(java.lang.String key)
```
    It returns the timestamp for the object referenced by the key.
  - getCount
```
public long getCount(java.lang.String key)
```
    It returns the count for the object referenced by the key.
  - getMetaData
```
public int[] getMetaData(java.lang.String key)
```
    It returns the metadata for the object referenced by the key no matter whether the object has expired or not. However, it returns null if the key is not found.
  - get
```
public java.lang.Object get(java.lang.String key,
                            long currentTime)
```
    It returns the object of the key only if it has not expired yet. Otherwise, it returns null if TTL is for TIME. If TTL is for COUNT, it returns the object anyway. Since the object for the key may be null originally, the existence of the key should be checked to tell whether the object has expired or has never existed before, or is just null.
  - get
```
public java.lang.Object get(java.lang.String key)
```
  - expire
```
public int expire(java.lang.String key,
                  long currentTime)
```
    It expires the object and returns 0 if the ttl is larger than zero. For an evergreen object(ttl=0), it just returns 1 with no changes to its state. If the key does not exist, it returns -1. The expiration action will not modify any metadata and the object.
  - expire
```
public int expire(java.lang.String key)
```
  - invalidate
```
protected int invalidate(java.lang.String key,
                         long currentTime)
```
    It sets the object into null no matter what the ttl is. For a non-evergreen object(ttl!=0), it also expires the object. If the key does not exist, it returns -1. Otherwise, it returns 0. The invalidation will set the object to null. But it will not touch the metadata.
  - disfragment
```
public java.lang.String[] disfragment(long currentTime)
```
    It removes all expired objects, resets all sequence numbers and returns an array of all expired keys that have been just removed. If TTL is for COUNT, the count will also be reset for all existing objects.
  - disfragment
```
public java.lang.String[] disfragment()
```
  - sortedKeys
```
public java.lang.String[] sortedKeys()
```
    It returns an array of all the existing keys in the NATURAL order no matter whether they have expired or not.
  - sortedEntries
```
public java.lang.Object[] sortedEntries()
```
  - clear
```
public void clear()
```
  - finalize
```
protected void finalize()
```
    Overrides:
    
    finalize in class java.lang.Object
  - keySet
```
public java.util.Set<java.lang.String> keySet()
```
    returns a set for all existing keys
  - compare
```
public int compare(long[] a,
                   long[] b)
```
    Specified by:
    
    compare in interface java.util.Comparator<long[]>

Class QuickCache

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Comparator

Field Detail

CACHE_NONE

CACHE_ON

CACHE_OFF

CACHE_EXPIRED

META_DEFAULT

META_MTAC

META_MCMT

META_MTMC

META_MCAT

META_ATAC

META_ACMT

META_ATMC

META_ACAT

Constructor Detail

QuickCache

Method Detail

size

getName

getOption

getTimeout

getMTime

getStatus

setStatus

setStatus

insert

insert

update

update

touch

touch

isExpired

isExpired

replace

replace

containsKey

getTTL

getTimestamp

getCount

getMetaData

get

get

expire

expire

invalidate

disfragment

disfragment

sortedKeys

sortedEntries

clear

finalize

keySet

compare