com.segment.analytics

Class QueueFile

java.lang.Object

com.segment.analytics.QueueFile

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class QueueFile
extends java.lang.Object
implements java.io.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.

Constructor Summary

Constructors

Constructor and Description
QueueFile(java.io.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.
int	forEach(com.segment.analytics.PayloadQueue.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	remove() Removes the eldest element.
void	remove(int n) Removes the eldest n elements.
int	size() Returns the number of elements in this queue.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

QueueFile

public QueueFile(java.io.File file)
          throws java.io.IOException

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

Throws:

java.io.IOException

Method Detail

add

public void add(byte[] data)
         throws java.io.IOException

Adds an element to the end of the queue.

Parameters:

data - to copy bytes from

Throws:

java.io.IOException

add

public void add(byte[] data,
                int offset,
                int count)
         throws java.io.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:

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

java.io.IOException

isEmpty

public boolean isEmpty()

Returns true if this queue contains no entries.

peek

public byte[] peek()
            throws java.io.IOException

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

Throws:

java.io.IOException

forEach

public int forEach(com.segment.analytics.PayloadQueue.ElementVisitor reader)
            throws java.io.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:

java.io.IOException

size

public int size()

Returns the number of elements in this queue.

remove

public void remove()
            throws java.io.IOException

Removes the eldest element.

Throws:

java.util.NoSuchElementException - if the queue is empty

java.io.IOException

remove

public void remove(int n)
            throws java.io.IOException

Removes the eldest n elements.

Throws:

java.util.NoSuchElementException - if the queue is empty

java.io.IOException

clear

public void clear()
           throws java.io.IOException

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

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Closes the underlying file.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object