com.gaborcselle.persistent
Class PersistentQueue<E extends java.io.Serializable>

java.lang.Object
  extended by com.gaborcselle.persistent.PersistentQueue<E>

public class PersistentQueue<E extends java.io.Serializable>
extends java.lang.Object

A concurrent persistent queue. It keeps a copy of its status in a file on disk which is updated every time the queue contents are modified. Therefore, the data in the queue can survive program or system crashes. The name of the status file is given when calling the constructor.

The type of elements held in the queue are determined by the type parameter E of this class. The type E has to extend the java.io.Serializable interface so that the entries can be written to the file underlying each instance.

Defragmentation: When the first element of the queue is deleted, not the entire file is written. Instead, a PersistentQueueDeleteMarker is appended to the end of the file to signal that the first element has been deleted. However, after some number of remove operations (by default, this is 50, but that can be changed via an optional parameter at instantiation), the entire file is defragmented: a temporary file is written with all contents of the queue. It is then renamed to match the name of the original file. The name of the temporary file is the original filename plus '.temp'.

More information can be found at the author's website.

Version:
1.0
Author:
Gabor Cselle

Constructor Summary
PersistentQueue(java.lang.String filename)
          Create a persistent queue.
PersistentQueue(java.lang.String filename, int defragmentInterval)
          Create a persistent queue.
 
Method Summary
 void add(E element)
          Adds an element to the tail of the queue.
 void clear()
          Clears the entire queue and forces the underlying file to be rewritten.
 boolean isEmpty()
          Returns true if the queue contains no elements.
 E peek()
          Retrieves, but does not remove, the head of this queue, returning null if this queue is empty.
 E remove()
          Removes and returns the head element of the persistent queue.
 int size()
          Returns the number of elements in this queue.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PersistentQueue

public PersistentQueue(java.lang.String filename)
                throws java.io.IOException
Create a persistent queue.

Parameters:
filename - the file to use for keeping the persistent state
Throws:
java.io.IOException - if an I/O error occurs

PersistentQueue

public PersistentQueue(java.lang.String filename,
                       int defragmentInterval)
                throws java.io.IOException
Create a persistent queue. The state of the queue should be kept in a file with filename.

Parameters:
filename - filename the file to use for keeping the persistent state
defragmentInterval - number of deletes after which defragment operation should start
Throws:
java.io.IOException - if an I/O error occurs
Method Detail

clear

public void clear()
           throws java.io.IOException
Clears the entire queue and forces the underlying file to be rewritten.

Throws:
java.io.IOException - if an I/O error occurs

isEmpty

public boolean isEmpty()
Returns true if the queue contains no elements.

Returns:
true if the queue contains no elements.

size

public int size()
Returns the number of elements in this queue.

Returns:
the number of elements in this queue

peek

public E peek()
Retrieves, but does not remove, the head of this queue, returning null if this queue is empty.

Returns:
the head of this queue, or null if this queue is empty.

remove

public E remove()
                                      throws java.io.IOException
Removes and returns the head element of the persistent queue.

Returns:
head element of this queue, or null if queue is empty.
Throws:
java.io.IOException - if an I/O error occurs

add

public void add(E element)
         throws java.io.IOException
Adds an element to the tail of the queue.

Parameters:
element - the element to add
Throws:
java.io.IOException - if an I/O error occurs