GroupedCache

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

```
public class GroupedCache
extends java.lang.Object
```
GroupedCache is a QuickCache with group support. Each cached object is identified by its unique key. The object also belongs to at least one group. Therefore, the objects in GroupedCache are related to each other based on their groups.

A group is identified by either its name or its id. There is no limit on the capacity of a group. But there is a limit on maximum number of groups. With group support, it is much easier to manage the cached objects.

Author:

yannanlu@yahoo.com

Constructor Summary

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()`
`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(long currentTime)` It removes all expired objects, resets all sequence numbers and returns an array of all expired keys that have been just removed.
`boolean`	`existsGroup(int id)` returns true if the group with the id exists
`boolean`	`existsGroup(java.lang.String name)` returns true if the group with the name exists
`int`	`expire(java.lang.String key, long currentTime)` It expires the object and returns 0 if the ttl is larger than zero.
`int`	`expireGroup(int id, long currentTime)` It expires all the object belonging to the group of id and returns number of the objects expired.
`protected void`	`finalize()`
`java.lang.Object`	`get(java.lang.String key, long currentTime)` It only returns the object of the key if it has not expired yet.
`int`	`getCapacity()`
`long`	`getCount(java.lang.String key)` returns the access 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 is expired or not.
`java.lang.String`	`getName()`
`long`	`getTimestamp(java.lang.String key)` returns the timestamp for the object referenced by the key.
`int`	`getTTL(java.lang.String key)` returns the ttl for the object referenced by the key.
`Browser`	`groupBrowser()` returns a Browser for all group IDs in the natural order
`int`	`groupID(java.lang.String name)`
`java.lang.String`	`groupName(int id)`
`int`	`groupSize()`
`int`	`insert(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.String[] groups, java.lang.Object obj)` It checks the existence of the key first.
`int`	`invalidateGroup(int id, long currentTime)` It invalidates all the object belonging to the group of id and returns number of the objects invalidated.
`boolean`	`isExpired(java.lang.String key, long currentTime)` returns true if the object of the key has expired, or false otherwise.
`java.util.Iterator`	`keyIterator(int id)` returns an Iterator for all existing keys in the group with id or null if the group id does not exist.
`java.util.Set<java.lang.String>`	`keySet()` returns a set for all existing keys of the entire cache
`int`	`size()` returns the total number of cached objects
`java.lang.String[]`	`sortedKeys()` returns the 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)` updates mtime of key if it has not expired.
`int`	`touch(java.lang.String key, long timestamp, long currentTime)` updates mtime of key with a given reference time for expiration.
`int`	`update(java.lang.String key, long timestamp, int ttl, int[] meta, java.lang.Object obj)` 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

- Constructor Detail
  - GroupedCache
```
public GroupedCache(java.lang.String name,
                    int capacity,
                    int option,
                    int timeout,
                    int threshold)
```
  - GroupedCache
```
public GroupedCache(java.lang.String name,
                    int capacity)
```
- Method Detail
  - insert
```
public int insert(java.lang.String key,
                  long timestamp,
                  int ttl,
                  int[] meta,
                  java.lang.String[] groups,
                  java.lang.Object obj)
```
    It checks the existence of the key first. If the key exists but has expired, it updates the object, metadata, timestamp, and a array of group name, then returns 0. If the key has not expired yet, it returns -1 for insert failure. If the key does not exist, it just inserts the key, object, timestamp and the group, then returns 1. The given group should not be empty. Otherwise, it throws IllegalArgumentException.
  - update
```
public int update(java.lang.String key,
                  long timestamp,
                  int ttl,
                  int[] meta,
                  java.lang.Object obj)
```
    It checks the existence of the key first. If the key exists, it checks the expiration. If the key has expired, it updates the object and timestamp, and 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.
  - get
```
public java.lang.Object get(java.lang.String key,
                            long currentTime)
```
    It only returns the object of the key if it has not expired yet. Otherwise, it returns null. Since the object for the key may be null originally, please check existence of the key to figure out if the object has expired or it just does not exist at all.
  - 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, it just returns 1 with no changes to its state. If the key does not exist, it returns -1. The expire action will not modify any metadata and object.
  - touch
```
public int touch(java.lang.String key,
                 long timestamp)
```
    updates mtime of key if it has not expired. 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,
                 long currentTime)
```
    updates mtime of key with a given reference time for expiration. It retruns 0 on success, -1 if no key is found or 1 if the object has expired already
  - expireGroup
```
public int expireGroup(int id,
                       long currentTime)
```
    It expires all the object belonging to the group of id and returns number of the objects expired.
  - invalidateGroup
```
public int invalidateGroup(int id,
                           long currentTime)
```
    It invalidates all the object belonging to the group of id and returns number of the objects invalidated.
  - isExpired
```
public boolean isExpired(java.lang.String key,
                         long currentTime)
```
    returns true if the object of the key has expired, or false otherwise. It throws IllegalArgumentException if the key is not found.
  - 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)
```
    returns the ttl for the object referenced by the key.
  - getTimestamp
```
public long getTimestamp(java.lang.String key)
```
    returns the timestamp for the object referenced by the key.
  - getCount
```
public long getCount(java.lang.String key)
```
    returns the access 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 is expired or not. However, it returns null if the key is not found.
  - size
```
public int size()
```
    returns the total number of cached objects
  - 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.
  - sortedKeys
```
public java.lang.String[] sortedKeys()
```
    returns the array of all the existing keys in the NATURAL order no matter whether they have expired or not.
  - keySet
```
public java.util.Set<java.lang.String> keySet()
```
    returns a set for all existing keys of the entire cache
  - keyIterator
```
public java.util.Iterator keyIterator(int id)
```
    returns an Iterator for all existing keys in the group with id or null if the group id does not exist.
  - groupBrowser
```
public Browser groupBrowser()
```
    returns a Browser for all group IDs in the natural order
  - existsGroup
```
public boolean existsGroup(int id)
```
    returns true if the group with the id exists
  - existsGroup
```
public boolean existsGroup(java.lang.String name)
```
    returns true if the group with the name exists
  - groupName
```
public java.lang.String groupName(int id)
```
  - groupID
```
public int groupID(java.lang.String name)
```
  - groupSize
```
public int groupSize()
```
  - getCapacity
```
public int getCapacity()
```
  - getName
```
public java.lang.String getName()
```
  - clear
```
public void clear()
```
  - finalize
```
protected void finalize()
```
    Overrides:
    
    finalize in class java.lang.Object

Class GroupedCache

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

GroupedCache

GroupedCache

Method Detail

insert

update

get

expire

touch

touch

expireGroup

invalidateGroup

isExpired

containsKey

getTTL

getTimestamp

getCount

getMetaData

size

disfragment

sortedKeys

keySet

keyIterator

groupBrowser

existsGroup

existsGroup

groupName

groupID

groupSize

getCapacity

getName

clear

finalize