com.isti.util
Class IstiTimeObjectCache

java.lang.Object
  com.isti.util.IstiTimeObjectCache

Direct Known Subclasses:

IstiMessageObjectCache

public class IstiTimeObjectCache
extends java.lang.Object

Class IstiTimeObjectCache implements the time object cache. The 'removeOldObjects()' method should be called on a periodic basis to remove old objects from the cache.

Nested Class Summary

static class	IstiTimeObjectCache.BasicTimeObjectEntry Basic time object entry.
static class	IstiTimeObjectCache.CacheInformation Class CacheInformation holds information about the cache.
static interface	IstiTimeObjectCache.TimeObjectEntry Time object entry
static class	IstiTimeObjectCache.VectorWithCount Subclass of Vector that also holds a 'count' value.

Field Summary

protected long	defaultRemoveAge
protected long	lastMsgTimeTracker
protected LogFile	logObj
protected int	maximumObjectCount
protected long	maximumTotalDataSize
protected FifoHashtable	objectCache
protected long	tolerance
protected long	totalCacheDataSize
protected boolean	useLookupKeyFlag

Constructor Summary

IstiTimeObjectCache(LogFile logObj, long tolerance)
Constructs a time object cache.

IstiTimeObjectCache(LogFile logObj, long tolerance, boolean useLookupKeyFlag)
Constructs a time object cache.

IstiTimeObjectCache(LogFile logObj, long tolerance, long removeAge)
Constructs a time object cache with a default remove age.

IstiTimeObjectCache(LogFile logObj, long tolerance, long removeAge, boolean useLookupKeyFlag)
Constructs a time object cache with a default remove age.

Method Summary

void	add(IstiTimeObjectCache.TimeObjectEntry entryObj) Adds the time object entry.
void	add(long timeGenerated, java.lang.Object dataObj, java.lang.String keyStr) Adds the time entry.
protected void	checkRemoveViaTotalDataSize() Checks if the total-data size for the cache is above the 'maximumTotalDataSize' limit and, if so, removes entries until the total-data size is under the limit.
void	clearCache() Clears all entries in the cache.
void	close() Deallocates resources associated with the cache.
boolean	containsEntry(IstiTimeObjectCache.TimeObjectEntry entryObj) Returns true if the cache contains an entry equal to the given entry-object.
boolean	containsKey(java.lang.Object keyObj) Returns true if the cache contains an entry with a 'keyStr' equal to the given object.
boolean	containsObjectKey(IstiTimeObjectCache.TimeObjectEntry entryObj) Returns true if the cache contains an entry with a 'keyStr' equal to the 'keyStr' for the given entry-object.
java.util.Vector	getAllObjects() Retrieves a copy of all of the objects.
IstiTimeObjectCache.CacheInformation	getCacheInformation() Returns information about the cache.
IstiTimeObjectCache.TimeObjectEntry	getFirstObject() Returns the first object in the cache.
java.util.Vector	getFirstObjects(int numObjects) Retrieves a copy of the first 'n' objects.
IstiTimeObjectCache.TimeObjectEntry	getLastObject() Returns the last object in the cache.
LogFile	getLogFile() Returns the log file.
protected java.lang.String	getLogPrefixString() Gets the prefix to use for log output.
int	getMaximumObjectCount() Returns the maximum-object count for the cache.
long	getMaximumTotalDataSize() Returns the maximum-total-data size for the cache.
int	getMessageCount() Returns the number of objects in the cache.
IstiTimeObjectCache.VectorWithCount	getNewerObjects(long time) Retrieves a copy of objects that are newer or equal to the specified time.
IstiTimeObjectCache.VectorWithCount	getNewerObjects(long time, int maxCount) Retrieves a copy of objects that are newer or equal to the specified time.
protected IstiTimeObjectCache.TimeObjectEntry	getObject(int index) Returns the entry at the given index.
IstiTimeObjectCache.VectorWithCount	getObjects(long beginTime, long endTime) Retrieves a copy of objects in the specified time range (inclusive).
IstiTimeObjectCache.VectorWithCount	getObjects(long beginTime, long endTime, int maxCount) Retrieves a copy of objects in the specified time range (inclusive).
IstiTimeObjectCache.VectorWithCount	getOlderObjects(long time) Retrieves a copy of objects that are older or equal to the specified time.
IstiTimeObjectCache.VectorWithCount	getOlderObjects(long time, int maxCount) Retrieves a copy of objects that are older or equal to the specified time.
long	getTotalCacheDataSize() Returns the total-data size for the cache.
boolean	getUseLookupKeyFlag() Returns the 'useLookupKeyFlag' flag value.
boolean	isEmpty() Returns the status of whether or not the cache is empty.
boolean	removeOldObjects() Removes old objects from the cache with the default remove age.
boolean	removeOldObjects(long removeAge) Removes old objects using the specified remove age.
void	setDefaultRemoveAge(long ageVal) Sets the remove-age value used by the no-parameter version of 'removeOldObjects()'.
void	setMaximumObjectCount(int val) Sets the maximum-object count for the cache.
void	setMaximumTotalDataSize(long val) Sets the maximum-total-data size for the cache.
int	size() Returns the number of entries in the cache.
protected IstiTimeObjectCache.VectorWithCount	subListVector(long beginTime, long endTime, int maxCount) Retrieves a sub list of objects.

Methods inherited from class java.lang.Object

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

Field Detail

logObj

protected final LogFile logObj

useLookupKeyFlag

protected final boolean useLookupKeyFlag

tolerance

protected long tolerance

defaultRemoveAge

protected long defaultRemoveAge

maximumObjectCount

protected int maximumObjectCount

maximumTotalDataSize

protected long maximumTotalDataSize

totalCacheDataSize

protected long totalCacheDataSize

objectCache

protected final FifoHashtable objectCache

lastMsgTimeTracker

protected long lastMsgTimeTracker

Constructor Detail

IstiTimeObjectCache

public IstiTimeObjectCache(LogFile logObj,
                           long tolerance,
                           long removeAge,
                           boolean useLookupKeyFlag)

Constructs a time object cache with a default remove age.

Parameters:

logObj - log file object to use or null for no logging.

tolerance - number of milliseconds for time tolerance that is used with time checks

removeAge - number of milliseconds to keep objects in the cache or 0 for no default.

useLookupKeyFlag - true to use the "keyStr" parameter (when adding) as a table-lookup key (which forces cache entries to have unique "keyStr" values).

IstiTimeObjectCache

public IstiTimeObjectCache(LogFile logObj,
                           long tolerance,
                           long removeAge)

Constructs a time object cache with a default remove age. The cache is setup to use the "keyStr" parameter (when adding) as a table-lookup key (which forces cache entries to have unique "keyStr" values).

Parameters:

logObj - log file object to use or null for no logging.

tolerance - number of milliseconds for time tolerance that is used with time checks

removeAge - number of milliseconds to keep objects in the cache or 0 for no default.

IstiTimeObjectCache

public IstiTimeObjectCache(LogFile logObj,
                           long tolerance,
                           boolean useLookupKeyFlag)

Constructs a time object cache.

Parameters:

logObj - log file object to use or null for no logging.

tolerance - number of milliseconds for time tolerance that is used with time checks

useLookupKeyFlag - true to use the "keyStr" parameter (when adding) as a table-lookup key (which forces cache entries to have unique "keyStr" values).

IstiTimeObjectCache

public IstiTimeObjectCache(LogFile logObj,
                           long tolerance)

Constructs a time object cache. The cache is setup to use the "keyStr" parameter (when adding) as a table-lookup key (which forces cache entries to have unique "keyStr" values).

Parameters:

logObj - log file object to use or null for no logging.

tolerance - number of milliseconds for time tolerance that is used with time checks

Method Detail

add

public void add(long timeGenerated,
                java.lang.Object dataObj,
                java.lang.String keyStr)

Adds the time entry.

Parameters:

timeGenerated - the time the message was generated

dataObj - data object.

keyStr - message string.

getAllObjects

public java.util.Vector getAllObjects()

Retrieves a copy of all of the objects.

Returns:

A new vector of objects (TimeObjectEntry).

getFirstObjects

public java.util.Vector getFirstObjects(int numObjects)

Retrieves a copy of the first 'n' objects.

Parameters:

numObjects - the maximum number of objects to return.

Returns:

A new vector of objects (TimeObjectEntry).

getFirstObject

public IstiTimeObjectCache.TimeObjectEntry getFirstObject()

Returns the first object in the cache.

Returns:

The first ('TimeObjectEntry') object in the cache, or null if the cache is empty.

getLastObject

public IstiTimeObjectCache.TimeObjectEntry getLastObject()

Returns the last object in the cache.

Returns:

The last ('TimeObjectEntry') object in the cache, or null if the cache is empty.

getLogFile

public LogFile getLogFile()

Returns the log file.

Returns:

the log file object.

getUseLookupKeyFlag

public boolean getUseLookupKeyFlag()

Returns the 'useLookupKeyFlag' flag value.

Returns:

true if the "keyStr" parameter is to be used (when adding) as a table-lookup key (which forces cache entries to have unique "keyStr" values); false if not.

getNewerObjects

public IstiTimeObjectCache.VectorWithCount getNewerObjects(long time,
                                                           int maxCount)

Retrieves a copy of objects that are newer or equal to the specified time.

Parameters:

time - time in milliseconds included, false otherwise

maxCount - the maximum number of objects to be returned, or 0 for no limit.

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

getNewerObjects

public IstiTimeObjectCache.VectorWithCount getNewerObjects(long time)

Retrieves a copy of objects that are newer or equal to the specified time.

Parameters:

time - time in milliseconds included, false otherwise

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

getObjects

public IstiTimeObjectCache.VectorWithCount getObjects(long beginTime,
                                                      long endTime,
                                                      int maxCount)

Retrieves a copy of objects in the specified time range (inclusive).

Parameters:

beginTime - begin time in milliseconds or 0 for start of cache

endTime - end time in milliseconds or 0 for end of cache.

maxCount - the maximum number of objects to be returned, or 0 for no limit.

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

getObjects

public IstiTimeObjectCache.VectorWithCount getObjects(long beginTime,
                                                      long endTime)

Retrieves a copy of objects in the specified time range (inclusive).

Parameters:

beginTime - begin time in milliseconds or 0 for start of cache

endTime - end time in milliseconds or 0 for end of cache.

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

getOlderObjects

public IstiTimeObjectCache.VectorWithCount getOlderObjects(long time,
                                                           int maxCount)

Retrieves a copy of objects that are older or equal to the specified time.

Parameters:

time - time in milliseconds.

maxCount - the maximum number of objects to be returned, or 0 for no limit.

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

getOlderObjects

public IstiTimeObjectCache.VectorWithCount getOlderObjects(long time)

Retrieves a copy of objects that are older or equal to the specified time.

Parameters:

time - time in milliseconds.

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

removeOldObjects

public boolean removeOldObjects(long removeAge)

Removes old objects using the specified remove age.

Parameters:

removeAge - number of milliseconds to keep objects in the cache.

Returns:

true if any objects were removed; false if no objects were removed.

removeOldObjects

public boolean removeOldObjects()

Removes old objects from the cache with the default remove age.

Returns:

true if any objects were removed; false if no objects were removed.

checkRemoveViaTotalDataSize

protected void checkRemoveViaTotalDataSize()

Checks if the total-data size for the cache is above the 'maximumTotalDataSize' limit and, if so, removes entries until the total-data size is under the limit. The thread-synchronization object for the cache should be held by the caller of this method.

clearCache

public void clearCache()

Clears all entries in the cache.

setDefaultRemoveAge

public void setDefaultRemoveAge(long ageVal)

Sets the remove-age value used by the no-parameter version of 'removeOldObjects()'.

Parameters:

ageVal - the remove-age values to use, in milliseconds.

setMaximumObjectCount

public void setMaximumObjectCount(int val)

Sets the maximum-object count for the cache. When the 'removeOldObjects()' method is called the cache size will be trimmed to this value as needed.

Parameters:

val - the maximum-object count for the cache, or 0 for no maximum-object count limit (the default).

getMaximumObjectCount

public int getMaximumObjectCount()

Returns the maximum-object count for the cache. When the 'removeOldObjects()' method is called the cache size will be trimmed to this value as needed.

Returns:

The maximum-object count for the cache, or 0 for no maximum-object count limit (the default).

setMaximumTotalDataSize

public void setMaximumTotalDataSize(long val)

Sets the maximum-total-data size for the cache. To calculate the total-data size the 'setDataSize()' method needs to have been called on each cache object. When the 'removeOldObjects()' method is called the cache size will be trimmed until the total-data size is under this value as needed.

Parameters:

val - the maximum-total-data size for the cache, or 0 for no maximum-total-data size limit (the default).

getMaximumTotalDataSize

public long getMaximumTotalDataSize()

Returns the maximum-total-data size for the cache. To calculate the total-data size the 'setDataSize()' method needs to have been called on each cache object. When the 'removeOldObjects()' method is called the cache size will be trimmed until the total-data size is under this value as needed.

Returns:

The maximum-total-data size for the cache, or 0 for no maximum-total-data size limit (the default).

getTotalCacheDataSize

public long getTotalCacheDataSize()

Returns the total-data size for the cache. To calculate the total-data size the 'setDataSize()' method needs to have been called on each cache object.

Returns:

The total-data size for the cache.

getMessageCount

public int getMessageCount()

Returns the number of objects in the cache.

Returns:

The number of objects in the cache.

getCacheInformation

public IstiTimeObjectCache.CacheInformation getCacheInformation()

Returns information about the cache.

Returns:

A new 'CacheInformation' object.

add

public void add(IstiTimeObjectCache.TimeObjectEntry entryObj)

Adds the time object entry.

Parameters:

entryObj - time-entry object.

containsKey

public boolean containsKey(java.lang.Object keyObj)

Returns true if the cache contains an entry with a 'keyStr' equal to the given object. For this method to work the cache must have been constructed setup to use the "keyStr" parameter (when adding) as a table-lookup key.

Parameters:

keyObj - the key object to use.

Returns:

true if the cache contains a matching object; false if not.

containsObjectKey

public boolean containsObjectKey(IstiTimeObjectCache.TimeObjectEntry entryObj)

Returns true if the cache contains an entry with a 'keyStr' equal to the 'keyStr' for the given entry-object. For this method to work the cache must have been constructed setup to use the "keyStr" parameter (when adding) as a table-lookup key.

Parameters:

entryObj - the entry-object to use.

Returns:

true if the cache contains a matching object; false if not.

containsEntry

public boolean containsEntry(IstiTimeObjectCache.TimeObjectEntry entryObj)

Returns true if the cache contains an entry equal to the given entry-object.

Parameters:

entryObj - the entry-object to use.

Returns:

true if the cache contains a matching object; false if not.

size

public int size()

Returns the number of entries in the cache.

Returns:

The number of entries in the cache.

isEmpty

public boolean isEmpty()

Returns the status of whether or not the cache is empty.

Returns:

true if the cache is empty, false if not.

getLogPrefixString

protected java.lang.String getLogPrefixString()

Gets the prefix to use for log output.

Returns:

the prefix to use for log output.

getObject

protected IstiTimeObjectCache.TimeObjectEntry getObject(int index)

Returns the entry at the given index.

Parameters:

index - index of the entry.

Returns:

The entry object.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is negative or not less than the current size of the cache.

subListVector

protected IstiTimeObjectCache.VectorWithCount subListVector(long beginTime,
                                                            long endTime,
                                                            int maxCount)

Retrieves a sub list of objects. The thread-sychronization lock for 'objectCache' should be held before this method is used.

Parameters:

beginTime - minimum time (in milliseconds, inclusive) for returned objects, or 0 for start of cache.

endTime - maximum time (in milliseconds, inclusive) for returned objects, or 0 for end of cache.

maxCount - the maximum number of objects to be returned, or 0 for no limit.

Returns:

A new 'VectorWithCount' of 'TimeObjectEntry' objects that also holds the requested number of items in its 'count' field.

close

public void close()

Deallocates resources associated with the cache.