CompositeDataSet

CompositeDataSet combines multiple datasets into a single logical dataset.

FilteredDataSet

FilteredDataSet is a decorator that exposes only some tables from a decorated dataset, pluggable with different filtering strategies. Some strategies include/ exclude tables without altering their order, while others expose tables in a different order.

This page covers SequenceTableFilter, an ordering decoration you construct directly with FilteredDataSet. The other table filter strategies (IncludeTableFilter, ExcludeTableFilter, and the auto-ordering DatabaseSequenceFilter) are covered in full, alongside column and row filters, in Filters.

SequenceTableFilter exposes a configured table sequence — the original filtering strategy from dbUnit 1.x, useful for imposing an explicit insert/comparison order:

ITableFilter filter = new SequenceTableFilter(new String[] {"FOO", "BAR"});
IDataSet orderedDataSet = new FilteredDataSet(filter, dataSet);

SortedDataSet / SortedTable

By default, a database table snapshot taken by dbUnit is sorted by primary key. If a table has no primary key, or its primary key is database-generated, row ordering is not predictable and comparisons against it may fail spuriously.

SortedTable decorates a single ITable with a sorted view, without copying the underlying data:

Assertion.assertEquals(new SortedTable(expected),
      new SortedTable(actual, expected.getTableMetaData()));

SortedDataSet does the same for every table in an IDataSet:

IDataSet sortedDataSet = new SortedDataSet(dataSet);

Note that SortedTable uses the string value of each column for sorting by default, so a numeric column sorts like 1, 10, 11, 12, 2, 3, 4. To sort using the column’s data type instead (1, 2, 3, 4, 10, 11, 12):

SortedTable sortedTable1 = new SortedTable(table1, new String[]{"COLUMN1"});
sortedTable1.setUseComparable(true); // must be invoked immediately after the constructor
SortedTable sortedTable2 = new SortedTable(table2, new String[]{"COLUMN1"});
sortedTable2.setUseComparable(true); // must be invoked immediately after the constructor
Assertion.assertEquals(sortedTable1, sortedTable2);

ReplacementDataSet

ReplacementDataSet is a decorator that replaces placeholder objects from the decorated dataset with replacement objects. Substring substitution is also possible.

This provides a declarative way to specify null values in flat XML datasets. For example, use a placeholder value like [NULL] in the flat XML dataset and replace it with null at runtime.

<?xml version="1.0"?>
<dataset>
    <TEST_TABLE COL0="row 0 col 0" COL1="[NULL]"/>
    <TEST_TABLE COL1="row 1 col 0" COL2="row 1 col 1"/>
</dataset>

Loading the flat XML dataset:

ReplacementDataSet dataSet = new ReplacementDataSet(new FlatXmlDataSet());
dataSet.addReplacementObject("[NULL]", null);

You can choose to use a fail-fast replacement to ensure that all placeholders are actually set and no one is missing in the replacement map. If one is missing the replacement will fail immediately throwing an exception. (Note that the default behaviour is to leave the non-replaced placeholder there and proceeding work silently):

replacementDataSet.setStrictReplacement(true);

Data File Loader's DataFileLoader implementations wrap every loaded dataset in a ReplacementDataSet automatically, applying whatever replacement objects/substrings were configured on the loader.

TableDecoratorDataSet

TableDecoratorDataSet is a decorator that allows `ITable`s (and `ITableMetaData`s, by extension) to be wrapped. This is intended for use cases like filtering out columns from a table.

For example, if your database supports generated (computed) columns, you could filter them out like so:

dataset = new TableDecoratorDataSet(dataset, table -> new ColumnFilterTable(table, new GeneratedColumnFilter()));

See Filters for GeneratedColumnFilter and the other column filters.

CachedDataSet

CachedDataSet holds an in-memory copy of another dataset, or of a consumed `IDataSetProducer’s content — decoupling the rest of your code from a one-shot/forward-only source such as a StreamingDataSet.

IDataSet snapshot = new CachedDataSet(sourceDataSet);