com.isti.util
Class IstiMessageCachedArchive

java.lang.Object
  com.isti.util.IstiMessageCachedArchive

public class IstiMessageCachedArchive

extends java.lang.Object

Class IstiMessageCachedArchive implements an ArchiveManager with a front-end cache. The 'removeOldObjects()' method should be called on a periodic basis to remove old objects from the cache and archive.

Nested Class Summary

class	IstiMessageCachedArchive.AddMessageWorkerThread Class AddMessageWorkerThread fetches message objects from the queue and adds them to the cache and archive.
static interface	IstiMessageCachedArchive.ArchivableMsgObjEntry Interface ArchivableMsgObjEntry combines the MessageObjectEntry and Archivable interfaces.
static class	IstiMessageCachedArchive.BasicArchivableMsgObjEntry Abstract class BasicArchivableMsgObjEntry is an extension of the message- object-entry class that also implements the 'Archivable' interface.

Field Summary

protected java.util.Vector	addMessageQueueVec
protected IstiMessageCachedArchive.AddMessageWorkerThread	addMessageWorkerThreadObj
protected ArchiveManager	archiveMgrObj
protected long	archiveRemoveAgeMilliSecs
protected long	cacheRemoveAgeMilliSecs
protected boolean	closingCacheArchiveFlag
protected java.lang.Object	dataAccessSyncObj
protected LogFile	logObj
protected long	maxRequestAgeMilliSecs
protected IstiMessageObjectCache	messageCacheObj

Constructor Summary

IstiMessageCachedArchive(ArchiveManager archiveMgrObj, LogFile logObj, long tolerance, int cacheRemoveAgeSecs, int archiveRemoveAgeSecs, int maxRequestAgeSecs)
Constructs a cached-archive object.

IstiMessageCachedArchive(ArchiveManager archiveMgrObj, LogFile logObj, long tolerance, int cacheRemoveAgeSecs, int archiveRemoveAgeSecs, int maxRequestAgeSecs, boolean useLookupKeyFlag)
Constructs a cached-archive object.

IstiMessageCachedArchive(ArchiveManager archiveMgrObj, LogFile logObj, long tolerance, int cacheRemoveAgeSecs, int cacheMaxObjectCount, long cacheMaxTotalDataSize, int archiveRemoveAgeSecs, int maxRequestAgeSecs)
Constructs a cached-archive object.

IstiMessageCachedArchive(ArchiveManager archiveMgrObj, LogFile logObj, long tolerance, int cacheRemoveAgeSecs, int cacheMaxObjectCount, long cacheMaxTotalDataSize, int archiveRemoveAgeSecs, int maxRequestAgeSecs, boolean useLookupKeyFlag)
Constructs a cached-archive object.

Method Summary

void	addArchivableMsgObj(IstiMessageCachedArchive.ArchivableMsgObjEntry archivableMsgObj) Adds the given message object to the cache and to the archive.
boolean	cacheContains(IstiMessageCachedArchive.ArchivableMsgObjEntry archivableMsgObj) Determines whether or not a message object "equal" to the given message object is contained in the cache.
void	close() Closes the archive and cache.
protected void	doAddArchivableMsgObj(IstiMessageCachedArchive.ArchivableMsgObjEntry archivableMsgObj) Performs the work of adding the given message object to the cache and to the archive.
int	getCacheSize() Returns the number of entries in the cache.
java.lang.Object	getDataAccessSyncObj() Returns the Object used to thread-synchronize the cached and archived data.
IstiMessageCachedArchive.ArchivableMsgObjEntry	getLastArchiveMessageObj() Returns the newest message object entered into the archive.
long	getLastArchiveMsgNum() Returns the message number for the newest message entered into the archive.
IstiMessageCachedArchive.ArchivableMsgObjEntry	getLastCacheMessageObj() Returns the newest message object entered into the cache.
long	getLastCacheMsgNum() Returns the message number for the newest message entered into the cache.
IstiMessageCachedArchive.ArchivableMsgObjEntry	getLastMessageObj() Returns the newest message object entered into the cache or archive.
long	getLastMsgNumber() Returns the message number for the newest message entered into the cache or archive.
protected java.lang.String	getLogPrefixString() Returns the prefix to use for log output.
IstiMessageObjectCache	getMessageCacheObj() Returns the message cache.
IstiTimeObjectCache.VectorWithCount	getMessages(long beginTime, long beginMsgNum, long endTime, long endMsgNum) Retrieves a copy of messages in the specified time range (inclusive).
IstiTimeObjectCache.VectorWithCount	getMessages(long beginTime, long beginMsgNum, long endTime, long endMsgNum, int maxCount) Retrieves a copy of messages in the specified time range (inclusive).
IstiTimeObjectCache.VectorWithCount	getNewerMessages(long time, long msgNum) Returns a list of messages newer or equal to the specified time value or later than the specified message number.
IstiTimeObjectCache.VectorWithCount	getNewerMessages(long time, long msgNum, int maxCount) Returns a list of messages newer or equal to the specified time value or later than the specified message number.
IstiTimeObjectCache.VectorWithCount	getOlderMessages(long time, long msgNum) Returns a list of messages older or equal to the specified time value or sooner than the specified message number.
IstiTimeObjectCache.VectorWithCount	getOlderMessages(long time, long msgNum, int maxCount) Returns a list of messages older or equal to the specified time value or sooner than the specified message number.
boolean	isAddMessageQueueEmpty() Returns the is-empty status of the add-message queue.
boolean	isCacheEmpty() Returns the status of whether or not the cache is empty.
void	preloadCacheFromArchive() Performs the initial loading of the cache from existing items in the archive.
boolean	removeOldObjects() Removes old objects from the cache and archive.
void	setArchiveRemoveAgeSecs(int ageInSecs) Modifies the remove-from-archive age used by the 'removeOldObjects()' method.
void	setCacheMaxObjectCount(int val) Modifies the maximum-object count for the cache.
void	setCacheMaxTotalDataSize(long val) Modifies the maximum-total-data size for the cache.
void	setCacheRemoveAgeSecs(int ageInSecs) Modifies the remove-from-cache age used by the 'removeOldObjects()' and 'preloadCacheFromArchive()' methods.
void	setMaxRequestAgeSecs(int ageInSecs) Modifies the max-request age used by the 'get...Messages()' methods.
boolean	waitForAddMessageQueueEmpty(long maxWaitMs) Waits for the add-message queue to be empty, up to the specified amount of time.

Methods inherited from class java.lang.Object

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

Field Detail

messageCacheObj

protected final IstiMessageObjectCache messageCacheObj

archiveMgrObj

protected final ArchiveManager archiveMgrObj

cacheRemoveAgeMilliSecs

protected long cacheRemoveAgeMilliSecs

archiveRemoveAgeMilliSecs

protected long archiveRemoveAgeMilliSecs

maxRequestAgeMilliSecs

protected long maxRequestAgeMilliSecs

logObj

protected final LogFile logObj

dataAccessSyncObj

protected final java.lang.Object dataAccessSyncObj

addMessageQueueVec

protected final java.util.Vector addMessageQueueVec

addMessageWorkerThreadObj

protected final IstiMessageCachedArchive.AddMessageWorkerThread addMessageWorkerThreadObj

closingCacheArchiveFlag

protected boolean closingCacheArchiveFlag

Constructor Detail

IstiMessageCachedArchive

public IstiMessageCachedArchive(ArchiveManager archiveMgrObj,
                                LogFile logObj,
                                long tolerance,
                                int cacheRemoveAgeSecs,
                                int cacheMaxObjectCount,
                                long cacheMaxTotalDataSize,
                                int archiveRemoveAgeSecs,
                                int maxRequestAgeSecs,
                                boolean useLookupKeyFlag)

Constructs a cached-archive object. If 'useLookupKeyFlag'==true then the cache is setup to use the "dataStr" parameter (when adding) as a table-lookup key (which forces cache entries to have unique "dataStr" values).

Parameters:

archiveMgrObj - an ArchiveManager object configured to archive a subclass of 'ArchivableMsgObjEntry'.

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

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

cacheRemoveAgeSecs - the number of seconds to keep objects in the cache.

cacheMaxObjectCount - the maximum-object count for the cache, or 0 for no limit.

cacheMaxTotalDataSize - the maximum-total-data size for the cache, or 0 for no limit.

archiveRemoveAgeSecs - the number of seconds to keep objects in the archive, or 0 for "infinity".

maxRequestAgeSecs - maximum age (in seconds) for messages returned via the 'get...Messages()' methods, or 0 for no limit.

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

IstiMessageCachedArchive

public IstiMessageCachedArchive(ArchiveManager archiveMgrObj,
                                LogFile logObj,
                                long tolerance,
                                int cacheRemoveAgeSecs,
                                int archiveRemoveAgeSecs,
                                int maxRequestAgeSecs,
                                boolean useLookupKeyFlag)

Constructs a cached-archive object. If 'useLookupKeyFlag'==true then the cache is setup to use the "dataStr" parameter (when adding) as a table-lookup key (which forces cache entries to have unique "dataStr" values).

Parameters:

archiveMgrObj - an ArchiveManager object configured to archive a subclass of 'ArchivableMsgObjEntry'.

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

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

cacheRemoveAgeSecs - the number of seconds to keep objects in the cache.

archiveRemoveAgeSecs - the number of seconds to keep objects in the archive, or 0 for "infinity".

maxRequestAgeSecs - maximum age (in seconds) for messages returned via the 'get...Messages()' methods, or 0 for no limit.

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

IstiMessageCachedArchive

public IstiMessageCachedArchive(ArchiveManager archiveMgrObj,
                                LogFile logObj,
                                long tolerance,
                                int cacheRemoveAgeSecs,
                                int cacheMaxObjectCount,
                                long cacheMaxTotalDataSize,
                                int archiveRemoveAgeSecs,
                                int maxRequestAgeSecs)

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

Parameters:

archiveMgrObj - an ArchiveManager object configured to archive a subclass of 'ArchivableMsgObjEntry'.

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

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

cacheRemoveAgeSecs - the number of seconds to keep objects in the cache.

cacheMaxObjectCount - the maximum-object count for the cache, or 0 for no limit.

cacheMaxTotalDataSize - the maximum-total-data size for the cache, or 0 for no limit.

archiveRemoveAgeSecs - the number of seconds to keep objects in the archive, or 0 for "infinity".

maxRequestAgeSecs - maximum age (in seconds) for messages returned via the 'get...Messages()' methods, or 0 for no limit.

IstiMessageCachedArchive

public IstiMessageCachedArchive(ArchiveManager archiveMgrObj,
                                LogFile logObj,
                                long tolerance,
                                int cacheRemoveAgeSecs,
                                int archiveRemoveAgeSecs,
                                int maxRequestAgeSecs)

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

Parameters:

archiveMgrObj - an ArchiveManager object configured to archive a subclass of 'ArchivableMsgObjEntry'.

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

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

cacheRemoveAgeSecs - the number of seconds to keep objects in the cache.

archiveRemoveAgeSecs - the number of seconds to keep objects in the archive, or 0 for "infinity".

maxRequestAgeSecs - maximum age (in seconds) for messages returned via the 'get...Messages()' methods, or 0 for no limit.

Method Detail

addArchivableMsgObj

public void addArchivableMsgObj(IstiMessageCachedArchive.ArchivableMsgObjEntry archivableMsgObj)

Adds the given message object to the cache and to the archive. If the cache was constructed to use the "dataStr" parameter (when adding) as a table-lookup key and a message with a matching key is already in the cache then the given message object is not added. The message object is queued and then added via a worker thread.

Parameters:

archivableMsgObj - an 'ArchivableMsgObjEntry' object containing the message data to be added.

doAddArchivableMsgObj

protected void doAddArchivableMsgObj(IstiMessageCachedArchive.ArchivableMsgObjEntry archivableMsgObj)
                              throws java.io.IOException

Performs the work of adding the given message object to the cache and to the archive. If the cache was constructed to use the "dataStr" parameter (when adding) as a table-lookup key and a message with a matching key is already in the cache then the given message object is not added.

Parameters:

archivableMsgObj - an 'ArchivableMsgObjEntry' object containing the message data to be added.

Throws:

java.io.IOException - if the archive file can not be written to.

getMessages

public IstiTimeObjectCache.VectorWithCount getMessages(long beginTime,
                                                       long beginMsgNum,
                                                       long endTime,
                                                       long endMsgNum,
                                                       int maxCount)

Retrieves a copy of messages in the specified time range (inclusive). If a message-count limit ('maxCount') is given and the number of messages returned is less than the number requested then the 'count' value in the returned 'VectorWithCount' object will be greater than the 'maxCount' value.

Parameters:

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

beginMsgNum - begin message number.

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

endMsgNum - end message number.

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

Returns:

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

getMessages

public IstiTimeObjectCache.VectorWithCount getMessages(long beginTime,
                                                       long beginMsgNum,
                                                       long endTime,
                                                       long endMsgNum)

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

Parameters:

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

beginMsgNum - begin message number.

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

endMsgNum - end message number.

Returns:

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

getNewerMessages

public IstiTimeObjectCache.VectorWithCount getNewerMessages(long time,
                                                            long msgNum,
                                                            int maxCount)

Returns a list of messages newer or equal to the specified time value or later than the specified message number. If a non-zero message number is given and the given time value matches then messages with message numbers greater than the given message number are returned; otherwise messages newer or equal to the specified time value are returned (within a tolerance value).

Parameters:

time - time in milliseconds.

msgNum - message number.

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

Returns:

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

getNewerMessages

public IstiTimeObjectCache.VectorWithCount getNewerMessages(long time,
                                                            long msgNum)

Returns a list of messages newer or equal to the specified time value or later than the specified message number. If a non-zero message number is given and the given time value matches then messages with message numbers greater than the given message number are returned; otherwise messages newer or equal to the specified time value are returned (within a tolerance value).

Parameters:

time - time in milliseconds.

msgNum - message number.

Returns:

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

getOlderMessages

public IstiTimeObjectCache.VectorWithCount getOlderMessages(long time,
                                                            long msgNum,
                                                            int maxCount)

Returns a list of messages older or equal to the specified time value or sooner than the specified message number. If a non-zero message number is given and the given time value matches then messages with message numbers less than the given message number are returned; otherwise messages older or equal to the specified time value are returned (within a tolerance value).

Parameters:

time - time in milliseconds.

msgNum - message number.

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

Returns:

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

getOlderMessages

public IstiTimeObjectCache.VectorWithCount getOlderMessages(long time,
                                                            long msgNum)

Returns a list of messages older or equal to the specified time value or sooner than the specified message number. If a non-zero message number is given and the given time value matches then messages with message numbers less than the given message number are returned; otherwise messages older or equal to the specified time value are returned (within a tolerance value).

Parameters:

time - time in milliseconds.

msgNum - message number.

Returns:

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

preloadCacheFromArchive

public void preloadCacheFromArchive()

Performs the initial loading of the cache from existing items in the archive.

removeOldObjects

public boolean removeOldObjects()

Removes old objects from the cache and archive. This method should be called on a periodic basis.

Returns:

true if any objects were removed from the cache; false if no objects were removed from the cache.

cacheContains

public boolean cacheContains(IstiMessageCachedArchive.ArchivableMsgObjEntry archivableMsgObj)

Determines whether or not a message object "equal" to the given message object is contained in the cache. Equality is determined using the 'dataStr' member of the objects. The message-queue is also checked to see if any waiting messages are "equal".

Parameters:

archivableMsgObj - an 'ArchivableMsgObjEntry' object to use.

Returns:

true if a message object "equal" to the given message object is contained in the cache.

isCacheEmpty

public boolean isCacheEmpty()

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

Returns:

true if the cache is empty, false if not.

getCacheSize

public int getCacheSize()

Returns the number of entries in the cache.

Returns:

The number of entries in the cache.

getLastCacheMessageObj

public IstiMessageCachedArchive.ArchivableMsgObjEntry getLastCacheMessageObj()

Returns the newest message object entered into the cache.

Returns:

The newest 'ArchivableMsgObjEntry' object entered into the cache, or null if none have been entered.

getLastArchiveMessageObj

public IstiMessageCachedArchive.ArchivableMsgObjEntry getLastArchiveMessageObj()

Returns the newest message object entered into the archive.

Returns:

The newest 'ArchivableMsgObjEntry' object entered into the archive, or null if none have been entered.

getLastMessageObj

public IstiMessageCachedArchive.ArchivableMsgObjEntry getLastMessageObj()

Returns the newest message object entered into the cache or archive.

Returns:

The newest 'ArchivableMsgObjEntry' object entered into the cache or archive, or null if none have been entered.

getLastCacheMsgNum

public long getLastCacheMsgNum()

Returns the message number for the newest message entered into the cache.

Returns:

The message number for the newest message entered into the cache, or 0 if none have been entered.

getLastArchiveMsgNum

public long getLastArchiveMsgNum()

Returns the message number for the newest message entered into the archive.

Returns:

The message number for the newest message entered into the archive, or 0 if none have been entered.

getLastMsgNumber

public long getLastMsgNumber()

Returns the message number for the newest message entered into the cache or archive.

Returns:

The message number for the newest message entered into the cache or archive, or 0 if none have been entered.

setCacheRemoveAgeSecs

public void setCacheRemoveAgeSecs(int ageInSecs)

Modifies the remove-from-cache age used by the 'removeOldObjects()' and 'preloadCacheFromArchive()' methods.

Parameters:

ageInSecs - the age to use, in seconds.

setCacheMaxObjectCount

public void setCacheMaxObjectCount(int val)

Modifies 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).

setCacheMaxTotalDataSize

public void setCacheMaxTotalDataSize(long val)

Modifies 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).

setArchiveRemoveAgeSecs

public void setArchiveRemoveAgeSecs(int ageInSecs)

Modifies the remove-from-archive age used by the 'removeOldObjects()' method.

Parameters:

ageInSecs - the age to use, in seconds.

setMaxRequestAgeSecs

public void setMaxRequestAgeSecs(int ageInSecs)

Modifies the max-request age used by the 'get...Messages()' methods.

Parameters:

ageInSecs - the age to use, in seconds.

isAddMessageQueueEmpty

public boolean isAddMessageQueueEmpty()

Returns the is-empty status of the add-message queue.

Returns:

true if the add-message queue is empty, false if messages are waiting to be added to the cache and archive.

waitForAddMessageQueueEmpty

public boolean waitForAddMessageQueueEmpty(long maxWaitMs)

Waits for the add-message queue to be empty, up to the specified amount of time.

Parameters:

maxWaitMs - the maximum number of milliseconds to wait for the queue to be empty, or 0 to wait indefinitely.

Returns:

true if the add-message queue is empty, false if messages are waiting to be added and the max-wait-time was reached

getDataAccessSyncObj

public java.lang.Object getDataAccessSyncObj()

Returns the Object used to thread-synchronize the cached and archived data.

Returns:

The Object used to thread-synchronize the cached and archived data.

getMessageCacheObj

public IstiMessageObjectCache getMessageCacheObj()

Returns the message cache. Access to the cache should be thread- synchronized to the 'dataAccessSyncObj' object.

Returns:

The IstiMessageObjectCache object used by this object.

close

public void close()

Closes the archive and cache.

getLogPrefixString

protected java.lang.String getLogPrefixString()

Returns the prefix to use for log output.