com.squareup.tape

Class QueueFile

java.lang.Object

com.squareup.tape.QueueFile

All Implemented Interfaces:

Closeable, AutoCloseable

public class QueueFile
extends Object
implements Closeable

A reliable, efficient, file-based, FIFO queue. Additions and removals are O(1). All operations are atomic. Writes are synchronous; data will be written to disk before an operation returns. The underlying file is structured to survive process and even system crashes. If an I/O exception is thrown during a mutating change, the change is aborted. It is safe to continue to use a QueueFile instance after an exception.

All operations are synchronized. In a traditional queue, the remove operation returns an element. In this queue, peek() and remove() are used in conjunction. Use peek to retrieve the first element, and then remove to remove it after successful processing. If the system crashes after peek and during processing, the element will remain in the queue, to be processed when the system restarts.

NOTE: The current implementation is built for file systems that support atomic segment writes (like YAFFS). Most conventional file systems don't support this; if the power goes out while writing a segment, the segment will contain garbage and the file will be corrupt. We'll add journaling support so this class can be used with more file systems later.

Author:

Bob Lee (bob@squareup.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	QueueFile.ElementReader Deprecated. use QueueFile.ElementVisitor instead.
static interface	QueueFile.ElementVisitor Reads queue elements.

Constructor Summary

Constructors

Constructor and Description
QueueFile(File file) Constructs a new queue backed by the given file.

Method Summary

Modifier and Type	Method and Description
void	add(byte[] data) Adds an element to the end of the queue.
void	add(byte[] data, int offset, int count) Adds an element to the end of the queue.
void	clear() Clears this queue.
void	close() Closes the underlying file.
void	forEach(QueueFile.ElementReader reader) Deprecated. use forEach(ElementVisitor)
int	forEach(QueueFile.ElementVisitor reader) Invokes the given reader once for each element in the queue, from eldest to most recently added.
boolean	isEmpty() Returns true if this queue contains no entries.
byte[]	peek() Reads the eldest element.
void	peek(QueueFile.ElementReader reader) Deprecated. use peek(ElementVisitor)
void	peek(QueueFile.ElementVisitor visitor) Invokes visitor with the eldest element, if an element is available.
void	remove() Removes the eldest element.
void	remove(int n) Removes the eldest n elements.
int	size() Returns the number of elements in this queue.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

QueueFile

public QueueFile(File file)
          throws IOException

Constructs a new queue backed by the given file. Only one instance should access a given file at a time.

Throws:

IOException

Method Detail

add

public void add(byte[] data)
         throws IOException

Adds an element to the end of the queue.

Parameters:

data - to copy bytes from

Throws:

IOException

add

public void add(byte[] data,
                int offset,
                int count)
         throws IOException

Adds an element to the end of the queue.

Parameters:

data - to copy bytes from

offset - to start from in buffer

count - number of bytes to copy

Throws:

IndexOutOfBoundsException - if offset < 0 or count < 0, or if offset + count is bigger than the length of buffer.

IOException

isEmpty

public boolean isEmpty()

Returns true if this queue contains no entries.

peek

public byte[] peek()
            throws IOException

Reads the eldest element. Returns null if the queue is empty.

Throws:

IOException

peek

@Deprecated
public void peek(QueueFile.ElementReader reader)
                      throws IOException

Deprecated. use peek(ElementVisitor)

Invokes reader with the eldest element, if an element is available.

Throws:

IOException

peek

public void peek(QueueFile.ElementVisitor visitor)
          throws IOException

Invokes visitor with the eldest element, if an element is available.

Throws:

IOException

forEach

@Deprecated
public void forEach(QueueFile.ElementReader reader)
                         throws IOException

Deprecated. use forEach(ElementVisitor)

Invokes the given reader once for each element in the queue, from eldest to most recently added.

Throws:

IOException

forEach

public int forEach(QueueFile.ElementVisitor reader)
            throws IOException

Invokes the given reader once for each element in the queue, from eldest to most recently added. Continues until all elements are read or reader.read() returns false.

Returns:

number of elements visited

Throws:

IOException

size

public int size()

Returns the number of elements in this queue.

remove

public void remove()
            throws IOException

Removes the eldest element.

Throws:

NoSuchElementException - if the queue is empty

IOException

remove

public void remove(int n)
            throws IOException

Removes the eldest n elements.

Throws:

NoSuchElementException - if the queue is empty

IOException

clear

public void clear()
           throws IOException

Clears this queue. Truncates the file to the initial size.

Throws:

IOException

close

public void close()
           throws IOException

Closes the underlying file.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object