QueueFile (tape 2.0.0-beta1 API)

java.lang.Object
- com.squareup.tape2.QueueFile

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<byte[]>
```
public final class QueueFile
extends java.lang.Object
implements java.io.Closeable, java.lang.Iterable<byte[]>
```
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.
Note that this implementation is not 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. Construct instances with QueueFile.Builder.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class QueueFile.Builder
Fluent API for creating QueueFile instances.

Nested Classes
Modifier and Type	Class and Description
`static class`	`QueueFile.Builder` Fluent API for creating `QueueFile` instances.

Method Summary

All Methods Instance Methods Concrete Methods
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()`
`java.io.File`	`file()` The underlying `File` backing this queue.
`boolean`	`isEmpty()` Returns true if this queue contains no entries.
`java.util.Iterator<byte[]>`	`iterator()` Returns an iterator over elements in this QueueFile.
`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

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- 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
```
@Nullable
public byte[] peek()
                      throws java.io.IOException
```
    Reads the eldest element. Returns null if the queue is empty.
    
    Throws:
    
    java.io.IOException
  - iterator
```
public java.util.Iterator<byte[]> iterator()
```
    Returns an iterator over elements in this QueueFile.
    The iterator disallows modifications to be made to the QueueFile during iteration. Removing elements from the head of the QueueFile is permitted during iteration using Iterator.remove().
    The iterator may throw an unchecked IOException during Iterator.next() or Iterator.remove().
    
    Specified by:
    
    iterator in interface java.lang.Iterable<byte[]>
  - 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
  - file
```
public java.io.File file()
```
    The underlying File backing this queue.
  - close
```
public void close()
           throws java.io.IOException
```
    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

Class QueueFile

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Method Detail

add

add

isEmpty

peek

iterator

size

remove

remove

clear

file

close

toString