htsjdk.samtools.util

Class SortingCollection<T>

java.lang.Object

htsjdk.samtools.util.SortingCollection<T>

All Implemented Interfaces:

java.lang.Iterable<T>

public class SortingCollection<T>
extends java.lang.Object
implements java.lang.Iterable<T>

Collection to which many records can be added. After all records are added, the collection can be iterated, and the records will be returned in order defined by the comparator. Records may be spilled to a temporary directory if there are more records added than will fit in memory. As a result of this, the objects returned may not be identical to the objects added to the collection, but they should be equal as determined by the codec used to write them to disk and read them back. When iterating over the collection, the number of file handles required is numRecordsInCollection/maxRecordsInRam. If this becomes a limiting factor, a file handle cache could be added. If Snappy DLL is available and snappy.disable system property is not set to true, then Snappy is used to compress temporary files.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SortingCollection.Codec<T> Client must implement this class, which defines the way in which records are written to and read from file.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(T rec)
void	cleanup() Delete any temporary files.
void	doneAdding() This method can be called after caller is done adding to collection, in order to possibly free up memory.
boolean	isDestructiveIteration()
CloseableIterator<T>	iterator() Prepare to iterate through the records in order.
static <T> SortingCollection<T>	newInstance(java.lang.Class<T> componentType, SortingCollection.Codec<T> codec, java.util.Comparator<T> comparator, int maxRecordsInRAM) Syntactic sugar around the ctor, to save some typing of type parameters.
static <T> SortingCollection<T>	newInstance(java.lang.Class<T> componentType, SortingCollection.Codec<T> codec, java.util.Comparator<T> comparator, int maxRecordsInRAM, java.util.Collection<java.io.File> tmpDirs) Syntactic sugar around the ctor, to save some typing of type parameters
static <T> SortingCollection<T>	newInstance(java.lang.Class<T> componentType, SortingCollection.Codec<T> codec, java.util.Comparator<T> comparator, int maxRecordsInRAM, java.io.File... tmpDir) Syntactic sugar around the ctor, to save some typing of type parameters
void	setDestructiveIteration(boolean destructiveIteration) Tell this collection that it is allowed to discard data during iteration in order to reduce memory footprint, precluding a second iteration.

Methods inherited from class java.lang.Object

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

Method Detail

add

public void add(T rec)

doneAdding

public void doneAdding()

This method can be called after caller is done adding to collection, in order to possibly free up memory. If iterator() is called immediately after caller is done adding, this is not necessary, because iterator() triggers the same freeing.

isDestructiveIteration

public boolean isDestructiveIteration()

Returns:

True if this collection is allowed to discard data during iteration in order to reduce memory footprint, precluding a second iteration over the collection.

setDestructiveIteration

public void setDestructiveIteration(boolean destructiveIteration)

Tell this collection that it is allowed to discard data during iteration in order to reduce memory footprint, precluding a second iteration. This is true by default.

iterator

public CloseableIterator<T> iterator()

Prepare to iterate through the records in order. This method may be called more than once, but add() may not be called after this method has been called.

Specified by:

iterator in interface java.lang.Iterable<T>

cleanup

public void cleanup()

Delete any temporary files. After this method is called, iterator() may not be called.

newInstance

public static <T> SortingCollection<T> newInstance(java.lang.Class<T> componentType,
                                   SortingCollection.Codec<T> codec,
                                   java.util.Comparator<T> comparator,
                                   int maxRecordsInRAM,
                                   java.io.File... tmpDir)

Syntactic sugar around the ctor, to save some typing of type parameters

Parameters:

componentType - Class of the record to be sorted. Necessary because of Java generic lameness.

codec - For writing records to file and reading them back into RAM

comparator - Defines output sort order

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

newInstance

public static <T> SortingCollection<T> newInstance(java.lang.Class<T> componentType,
                                   SortingCollection.Codec<T> codec,
                                   java.util.Comparator<T> comparator,
                                   int maxRecordsInRAM,
                                   java.util.Collection<java.io.File> tmpDirs)

Syntactic sugar around the ctor, to save some typing of type parameters

Parameters:

componentType - Class of the record to be sorted. Necessary because of Java generic lameness.

codec - For writing records to file and reading them back into RAM

comparator - Defines output sort order

maxRecordsInRAM - how many records to accumulate in memory before spilling to disk

tmpDirs - Where to write files of records that will not fit in RAM

newInstance

public static <T> SortingCollection<T> newInstance(java.lang.Class<T> componentType,
                                   SortingCollection.Codec<T> codec,
                                   java.util.Comparator<T> comparator,
                                   int maxRecordsInRAM)

Syntactic sugar around the ctor, to save some typing of type parameters. Writes files to java.io.tmpdir

Parameters:

componentType - Class of the record to be sorted. Necessary because of Java generic lameness.

codec - For writing records to file and reading them back into RAM

comparator - Defines output sort order

maxRecordsInRAM - how many records to accumulate in memory before spilling to disk