# Class DiskBackedQueue<E>

java.lang.Object
htsjdk.samtools.util.DiskBackedQueue<E>

All Implemented Interfaces:
  `Iterable<E>, Collection<E>, Queue<E>`

public class DiskBackedQueue<E> extends Object implements Queue<E>
A single-ended FIFO queue. Writes elements to temporary files when the queue gets too big. External references to elements in this queue are NOT guaranteed to be valid, due to the disk write/read

NB: The queue becomes read-only after the first time that an on-disk record is "next up" to be read (i.e. has been loaded into headRecord). Max size is therefore non-deterministic. This avoids issues arising from conflicts between the input and output streams. This could perhaps be avoided by creating a version of BAMRecordCodec that operates on RandomAccessFiles or channels.

Created by bradt on 4/28/14.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`add(E record)`
Add the record to the tail of the queue, spilling to disk if necessary Must check that (canAdd() == true) before calling this method
`boolean`
`addAll(Collection<? extends E> c)`
Add all elements from collection c to this DiskBackedQueue Must check that (canAdd() == true) before calling this method
`boolean`
`canAdd()`
`void`
`clear()`
`boolean`
`contains(Object o)`
Not supported.
`boolean`
`containsAll(Collection<?> c)`
Not supported.
`E`
`element()`
`protected void`
`finalize()`
Clean up disk resources in case clear() has not been explicitly called (as would be preferable) Closes the input and output streams associated with this DiskBackedQueue and deletes the temporary file
`int`
`getNumRecordsOnDisk()`
`boolean`
`headRecordIsFromDisk()`
`boolean`
`isEmpty()`
`Iterator<E>`
`iterator()`
Not supported at this time
`static <T> DiskBackedQueue<T>`
`newInstance(SortingCollection.Codec<T> codec, int maxRecordsInRam, List<File> tmpDir)`
Syntactic sugar around the ctor, to save some typing of type parameters
`static <T> DiskBackedQueue<T>`
`newInstanceFromPaths(SortingCollection.Codec<T> codec, int maxRecordsInRam, List<Path> tmpDir)`
Syntactic sugar around the ctor, to save some typing of type parameters
`boolean`
`offer(E e)`
`E`
`peek()`
`E`
`poll()`
`E`
`remove()`
`boolean`
`remove(Object o)`
Not supported.
`boolean`
`removeAll(Collection<?> c)`
Not supported.
`boolean`
`retainAll(Collection<?> c)`
Not supported.
`int`
`size()`
Return the total number of elements in the queue, both in memory and on disk
`Object[]`
`toArray()`
Not supported at this time
`<T1> T1[]`
`toArray(T1[] a)`
Not supported at this time

### Methods inherited from class Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface Collection

`equals, hashCode, parallelStream, removeIf, spliterator, stream, toArray`

### Methods inherited from interface Iterable

`forEach`

## Method Details

### newInstance

public static <T> DiskBackedQueue<T> newInstance(SortingCollection.Codec<T> codec, int maxRecordsInRam, List<File> tmpDir)
Syntactic sugar around the ctor, to save some typing of type parameters

Parameters:
  `codec` - For writing records to file and reading them back into RAM
  `maxRecordsInRam` - how many records to accumulate in memory before spilling to disk
  `tmpDir` - Where to write files of records that will not fit in RAM

### newInstanceFromPaths

public static <T> DiskBackedQueue<T> newInstanceFromPaths(SortingCollection.Codec<T> codec, int maxRecordsInRam, List<Path> tmpDir)
Syntactic sugar around the ctor, to save some typing of type parameters

Parameters:
  `codec` - For writing records to file and reading them back into RAM
  `maxRecordsInRam` - how many records to accumulate in memory before spilling to disk
  `tmpDir` - Where to write files of records that will not fit in RAM

### canAdd

public boolean canAdd()

### getNumRecordsOnDisk

public int getNumRecordsOnDisk()

### headRecordIsFromDisk

public boolean headRecordIsFromDisk()

### add

public boolean add(E record) throws IllegalStateException
Add the record to the tail of the queue, spilling to disk if necessary Must check that (canAdd() == true) before calling this method

Specified by:
  `add` in interface `Collection<E>`
Specified by:
  `add` in interface `Queue<E>`
Parameters:
  `record` - The record to be added to the queue
Returns:
  true (if add successful)
Throws:
  `IllegalStateException` - if the queue cannot be added to

### offer

public boolean offer(E e)

Specified by:
  `offer` in interface `Queue<E>`

### remove

public E remove()

Specified by:
  `remove` in interface `Queue<E>`

### poll

public E poll()

Specified by:
  `poll` in interface `Queue<E>`

### element

public E element()

Specified by:
  `element` in interface `Queue<E>`

### peek

public E peek()

Specified by:
  `peek` in interface `Queue<E>`

### size

public int size()
Return the total number of elements in the queue, both in memory and on disk

Specified by:
  `size` in interface `Collection<E>`

### isEmpty

public boolean isEmpty()

Specified by:
  `isEmpty` in interface `Collection<E>`

### addAll

public boolean addAll(Collection<? extends E> c)
Add all elements from collection c to this DiskBackedQueue Must check that (canAdd() == true) before calling this method

Specified by:
  `addAll` in interface `Collection<E>`
Parameters:
  `c` - the collection of elements to add
Returns:
  true if this collection changed as a result of the call
Throws:
  `IllegalStateException` - if the queue cannot be added to

### clear

public void clear()

Specified by:
  `clear` in interface `Collection<E>`

### finalize

protected void finalize() throws Throwable
Clean up disk resources in case clear() has not been explicitly called (as would be preferable) Closes the input and output streams associated with this DiskBackedQueue and deletes the temporary file

Overrides:
  `finalize` in class `Object`
Throws:
  `Throwable`

### remove

public boolean remove(Object o)
Not supported. Cannot access particular elements, as some elements may have been written to disk

Specified by:
  `remove` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### removeAll

public boolean removeAll(Collection<?> c)
Not supported. Cannot access particular elements, as some elements may have been written to disk

Specified by:
  `removeAll` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### retainAll

public boolean retainAll(Collection<?> c)
Not supported. Cannot access particular elements, as some elements may have been written to disk

Specified by:
  `retainAll` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### contains

public boolean contains(Object o)
Not supported. It is not possible to check for the presence of a particular element, as some elements may have been written to disk

Specified by:
  `contains` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### containsAll

public boolean containsAll(Collection<?> c)
Not supported. It is not possible to check for the presence of a particular element, as some elements may have been written to disk

Specified by:
  `containsAll` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### iterator

public Iterator<E> iterator()
Not supported at this time

Specified by:
  `iterator` in interface `Collection<E>`
Specified by:
  `iterator` in interface `Iterable<E>`
Throws:
  `UnsupportedOperationException`

### toArray

public Object[] toArray()
Not supported at this time

Specified by:
  `toArray` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### toArray

public <T1> T1[] toArray(T1[] a)
Not supported at this time

Specified by:
  `toArray` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`