alma.acs.util.stringqueue

Class TimestampedStringQueue

java.lang.Object

java.lang.Thread

alma.acs.util.stringqueue.TimestampedStringQueue

All Implemented Interfaces:

java.lang.Runnable

public class TimestampedStringQueue
extends java.lang.Thread

Objects from this class implement a FIFO queue of strings. The strings stored in the queue must be timestamped i.e. they always contain a ISO timestamp in a definite position. Example of such strings in ACS are the XML logs and the alarms.
TimestampedStringQueue does not assume any format for the strings pushed in the queue. It assumes that the timestamp immediately follows a string, passed in the constructor.

The main purpose of this class is to write on files all the strings pushed in the queue and let the user able to reuse such files knowing the timestamps of the strings it contains. Implementors of TimestampedStringQueueFileHandler are notified of the min and max timestamps contained in each file of the cache through TimestampedStringQueueFileHandler.fileProcessed(File, String, String).

Users of this class pushes string by invoking push(String) and get strings out of the queue by calling pop(). The insertion of a new string is immediate. Getting a string returns immediately if the queue contains at least one string; otherwise it waits for a new element until a timeout happens.

The strings are written on disk by using a set of files: a new file is created whenever the dimension of the current file becomes greater then a fixed size. For each entry in the queue, a record is created and kept in a in-memory list.

When all the strings in a file have been red, the file is deleted to reduce the disk usage. The deletion of unused files is done by a thread.

The length of each file of cache can be customized by passing a parameter in the constructor or setting java property. If both those values are not given, a default length is used ().

files contains all the files used by the cache, identified by a key. When a file does not contain unread entries then its key is pushed into filesToDelete and deleted. The thread that deletes the files from disk, removes the QueueFile object from files too.

Life cycle: start() must be called at the beginning and close(boolean) at the end.

Author:

acaproni

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
TimestampedStringQueue(long size, java.lang.String timestampIdentifier) Build the cache with the passed maximum size for each file of the cache.
TimestampedStringQueue(java.lang.String timestampIdentifier) Build a cache with the default file handler DefaultQueueFileHandlerImpl
TimestampedStringQueue(TimestampedStringQueueFileHandler handler, java.lang.String timestampIdentifier) Build the cache with the passed file handler.

Method Summary

Modifier and Type	Method and Description
void	close(boolean sync) Close the cache: delete all the entries and all the files the exit.
int	getActiveFilesSize()
boolean	isEmpty()
java.lang.String	pop() Get and remove the next string from the cache.
void	push(java.lang.String string) Push an entry in the cache.
void	run() The method to get and delete unused files
void	setTimeout(int val) Set a new timeout when getting new element and the queue is empty.
int	size() Return the number of entries in cache.
void	start() Start the thread.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Constructor Detail

TimestampedStringQueue

public TimestampedStringQueue(java.lang.String timestampIdentifier)

Build a cache with the default file handler DefaultQueueFileHandlerImpl

Parameters:

timestampIdentifier - The string to find the timestamp in each pushed string

TimestampedStringQueue

public TimestampedStringQueue(long size,
                              java.lang.String timestampIdentifier)

Build the cache with the passed maximum size for each file of the cache.

This constructor must be used to instantiate the default file handler (DefaultQueueFileHandlerImpl) with a customized file size.

Parameters:

size - The max size of each file of the cache

timestampIdentifier - The string to find the timestamp in each pushed string

TimestampedStringQueue

public TimestampedStringQueue(TimestampedStringQueueFileHandler handler,
                              java.lang.String timestampIdentifier)

Build the cache with the passed file handler. This method should be used

1. when a custom implementation of StringQueueFileHandler
2. when the default handler with the default size of files must be instantiated. The default size means StringQueueFileHandler#DEFAULT_SIZE or whatever is set in the java property.

Parameters:

handler - The not null handler to create and delete the files.

timestampIdentifier - The string to find the timestamp in each pushed string

Method Detail

size

public int size()

Return the number of entries in cache.

Returns:

the number of entries in cache

isEmpty

public boolean isEmpty()

Returns:

true if the queue is empty; false otherwise.

getActiveFilesSize

public int getActiveFilesSize()

Returns:

The number of files used by the cache

push

public void push(java.lang.String string)
          throws java.io.IOException,
                 StringQueueException

Push an entry in the cache. If the current file is null or its size is greater then maxSize, then a new file is created.

Parameters:

string - The string to write in the cache

Throws:

java.io.IOException - In case of error writing the string on disk

StringQueueException

pop

public java.lang.String pop()
                     throws java.io.IOException

Get and remove the next string from the cache.

This method returns immediately if the queue is not empty otherwise waits until a new element is inserted in the queue or a timeout elapses (QueueEntry#maxWaitingTime). However, a timeout of 0 let this method return immediately even if the queue is empty.

Returns:

The next string entry in cache. null If the timeout happened

Throws:

java.io.IOException - In case of error reading from the file

start

public void start()

Start the thread.

Overrides:

start in class java.lang.Thread

close

public void close(boolean sync)

Close the cache: delete all the entries and all the files the exit.

Note: this must be the last operation executed by the cache

Parameters:

sync - true if must wait the termination of the threads before exiting

run

public void run()

The method to get and delete unused files

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

setTimeout

public void setTimeout(int val)

Set a new timeout when getting new element and the queue is empty.

If the timeout is 0, then pop() returns immediately if the queue is empty.

Parameters:

val - The new timeout (must be equal or greater then 0).

See Also:

pop()