org.jdbdt

Class DataSetBuilder

java.lang.Object

org.jdbdt.DataSetBuilder

public final class DataSetBuilder
extends Object

Data set builder.

Objects of this kind provide a convenient manner to define data sets programmatically.

Data builders can be used as follows:

• They are created with calls to either JDBDT.builder(DataSource), to create a fresh data set, or to DataSet.build() to add data to an existing data set.
• Entries (rows) in the data set are specified by setting one column filler (ColumnFiller instance) per each column in the table, using the set(String, ColumnFiller) base method or one of several convenience methods e.g., the ones available for sequence or pseudo-random values.
• Each call to generate(int) causes a specified number of rows to be added to the underlying data set, in line with the current column fillers set.
• The data set instance for a builder can be retrieved using data().

Since:

1.0

See Also:

JDBDT.builder(DataSource), DataSet.build()

Field Summary

Fields

Modifier and Type	Field and Description
static long	MILLIS_PER_DAY Milliseconds per day.

Constructor Summary

Constructors

Constructor and Description
DataSetBuilder(DataSet data) Constructs a new data set builder backed by an existing data set.
DataSetBuilder(DataSource source) Constructs a new data set builder for the given data source.

Method Summary

Modifier and Type	Method and Description
DataSetBuilder	allColumnsNull() Set the NULL value filler for all columns.
DataSet	data() Get data set this builder associates to.
DataSetBuilder	generate(int count) Associate a number of rows to the data set, according to the current column fillers' configuration.
DataSetBuilder	nullValue(String column) Set the NULL value filler for a column.
DataSetBuilder	random(String column, Date min, Date max) Set random filler using Date values.
DataSetBuilder	random(String column, double min, double max) Set random filler using double values.
DataSetBuilder	random(String column, float min, float max) Set random filler using float values.
DataSetBuilder	random(String column, Function<Random,?> gen) Set customized random filler.
DataSetBuilder	random(String column, int min, int max) Set random filler using int values.
DataSetBuilder	random(String column, List<?> values) Set random filler for column using a list of values.
DataSetBuilder	random(String column, long min, long max) Set random filler using long values.
<T> DataSetBuilder	random(String column, T... values) Set random filler for column using an array of values.
DataSetBuilder	random(String column, Timestamp min, Timestamp max) Set random filler using Timestamp values.
DataSetBuilder	random(String column, Time min, Time max) Set random filler using Time values.
DataSetBuilder	remainingColumnsNull() Set the NULL value filler for all remaining columns.
void	reset() Disable all previous column filler settings.
DataSetBuilder	sequence(String column, BigInteger initial) Set BigInteger sequence filler for column.
DataSetBuilder	sequence(String column, BigInteger initial, BigInteger step) Set BigInteger sequence filler for column with a specified step.
DataSetBuilder	sequence(String column, Date initial, int step) Set Date sequence filler for column with a specified step in days.
DataSetBuilder	sequence(String column, double initial, double step) Set double sequence filler for column with a specified step.
DataSetBuilder	sequence(String column, float initial, float step) Set float sequence filler for column with a specified step.
DataSetBuilder	sequence(String column, int initial) Set int value sequence filler for column.
DataSetBuilder	sequence(String column, IntFunction<?> step) Set sequence filler using a index-based step-function.
DataSetBuilder	sequence(String column, IntFunction<?> step, int initial) Set sequence filler using a index-based step-function.
DataSetBuilder	sequence(String column, int initial, int step) Set int sequence filler for column with a specified step.
DataSetBuilder	sequence(String column, List<?> values) Set sequence filler using a list of values.
DataSetBuilder	sequence(String column, long initial) Set long value sequence filler for column.
DataSetBuilder	sequence(String column, long initial, long step) Set long sequence filler for column with a specified step.
<T> DataSetBuilder	sequence(String column, T... values) Set sequence filler using array values.
DataSetBuilder	sequence(String column, Time initial, int step) Set Time sequence filler for column with a specified step in seconds.
DataSetBuilder	sequence(String column, Timestamp initial, long step) Set Timestamp sequence filler for column with a specified step in milliseconds.
<T> DataSetBuilder	sequence(String column, T initial, UnaryOperator<T> step) Set a sequence filler using a step-function.
DataSetBuilder	set(String column, ColumnFiller<?> filler) Set filler for column.
<E extends Enum<?>> DataSetBuilder	value(String column, E enumConstant) Set a constant enum value for a column, converting the enumeration constant to a string.
<T> DataSetBuilder	value(String column, T constant) Set a constant value filler for a column.

Methods inherited from class java.lang.Object

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

Field Detail

MILLIS_PER_DAY

public static final long MILLIS_PER_DAY

Milliseconds per day.

See Also:

Constant Field Values

Constructor Detail

DataSetBuilder

public DataSetBuilder(DataSource source)

Constructs a new data set builder for the given data source.

The builder will be backed by a fresh data set for the given source.

Parameters:

source - Data source.

DataSetBuilder

public DataSetBuilder(DataSet data)

Constructs a new data set builder backed by an existing data set.

New rows generated using the builder will be added to the given data set. without clearing previously existing rows in it.

Parameters:

data - Data set associated to builder.

Method Detail

data

public DataSet data()

Get data set this builder associates to.

Returns:

Data set instance.

generate

public DataSetBuilder generate(int count)

Associate a number of rows to the data set, according to the current column fillers' configuration.

Parameters:

count - Number of rows (a positive integer)

Returns:

The data set instance (for chained calls).

Throws:

ColumnFillerException - if there is an error evaluating a column filler.

InvalidOperationException - for an invalid row count, or if there are columns with no associated fillers.

set

public DataSetBuilder set(String column,
                          ColumnFiller<?> filler)

Set filler for column.

Parameters:

column - Column name.

filler - Column filler.

Returns:

The builder instance (for chained calls).

reset

public void reset()

Disable all previous column filler settings.

After a call to this method, no column will have an associated filler.

nullValue

public DataSetBuilder nullValue(String column)

Set the NULL value filler for a column.

Parameters:

column - Column name.

Returns:

The builder instance (for chained calls).

See Also:

value(String, Object)

remainingColumnsNull

public DataSetBuilder remainingColumnsNull()

Set the NULL value filler for all remaining columns.

A call to this method sets the nullValue(java.lang.String) filler for all columns without an associated filler.

Returns:

The builder instance (for chained calls).

See Also:

nullValue(String), allColumnsNull()

allColumnsNull

public DataSetBuilder allColumnsNull()

Set the NULL value filler for all columns.

A call to this method sets the nullValue(java.lang.String) filler for all columns.

Returns:

The builder instance (for chained calls).

See Also:

nullValue(String), remainingColumnsNull()

value

public <T> DataSetBuilder value(String column,
                                T constant)

Set a constant value filler for a column.

Type Parameters:

T - Type of object.

Parameters:

column - Column name.

constant - Value of the constant .

Returns:

The builder instance (for chained calls).

value

public <E extends Enum<?>> DataSetBuilder value(String column,
                                                E enumConstant)

Set a constant enum value for a column, converting the enumeration constant to a string.

A call to this method is shorthand for value(column, enumConstant.toString()).

Type Parameters:

E - Enumeration type.

Parameters:

column - Column name.

enumConstant - Value of the constant.

Returns:

The builder instance (for chained calls).

sequence

public <T> DataSetBuilder sequence(String column,
                                   T initial,
                                   UnaryOperator<T> step)

Set a sequence filler using a step-function.

The sequence of values generated by the filler starts with the specified initial value, and subsequent values are generated using the step function which takes as input the previous value. The sequence will then be s(0), s(1), ... where s(0) = initial and s(n+1) = step.apply(s(n)) for all n >= 0 .

Type Parameters:

T - Column datum type.

Parameters:

column - Column name.

initial - Initial value.

step - Step function.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, IntFunction)

sequence

public DataSetBuilder sequence(String column,
                               IntFunction<?> step)

Set sequence filler using a index-based step-function.

A call to this method is equivalent to sequence(column, step, 0).

Parameters:

column - Column name.

step - Step function.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, IntFunction, int)

sequence

public DataSetBuilder sequence(String column,
                               IntFunction<?> step,
                               int initial)

Set sequence filler using a index-based step-function.

The sequence of values generated by the filler starts with the specified initial value, and subsequent values are generated using the step function which takes as input the index of the row being generated, starting from the initial value. The sequence will then be s(start), s(start+1), ... where s(i) = step.apply(i) for all i >= start.

Parameters:

column - Column name.

step - Step function.

initial - Initial value fed to step function.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator)

sequence

@SafeVarargs
public final <T> DataSetBuilder sequence(String column,
                                                      T... values)

Set sequence filler using array values.

A call to this method is shorthand for sequence(column, i -> values[i % values.length]).

Type Parameters:

T - Type of data.

Parameters:

column - Column name.

values - Sequence of values to use.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, List), sequence(String,IntFunction)

sequence

public DataSetBuilder sequence(String column,
                               List<?> values)

Set sequence filler using a list of values.

A call to this method is shorthand for sequence(column, i -> values.get(i % values.size())).

Parameters:

column - Column name.

values - Sequence of values to use.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String,IntFunction)

sequence

public DataSetBuilder sequence(String column,
                               int initial)

Set int value sequence filler for column.

A call to this method is shorthand for sequence(column, initial, 1).

Parameters:

column - Column name.

initial - Initial sequence value.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, int, int)

sequence

public DataSetBuilder sequence(String column,
                               int initial,
                               int step)

Set int sequence filler for column with a specified step.

A call to this method is shorthand for sequence(column, initial, n -> n + step).

Parameters:

column - Column name.

initial - Initial sequence value.

step - Sequence step.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, int)

sequence

public DataSetBuilder sequence(String column,
                               long initial)

Set long value sequence filler for column.

A call to this method is shorthand for sequence(column, initial, 1L).

Parameters:

column - Column name.

initial - Initial sequence value.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, long, long)

sequence

public DataSetBuilder sequence(String column,
                               long initial,
                               long step)

Set long sequence filler for column with a specified step.

A call to this method is shorthand for sequence(column, initial, n -> n + step).

Parameters:

column - Column name.

initial - Initial sequence value.

step - Sequence step.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, long)

sequence

public DataSetBuilder sequence(String column,
                               BigInteger initial)

Set BigInteger sequence filler for column.

A call to this method is shorthand for sequence(column, initial, BigInteger.ONE).

Parameters:

column - Column name.

initial - Initial sequence value.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, BigInteger, BigInteger)

sequence

public DataSetBuilder sequence(String column,
                               BigInteger initial,
                               BigInteger step)

Set BigInteger sequence filler for column with a specified step.

A call to this method is shorthand for sequence(column, initial, n -> n.add(step)).

Parameters:

column - Column name.

initial - Initial sequence value.

step - Sequence step.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, BigInteger)

sequence

public DataSetBuilder sequence(String column,
                               float initial,
                               float step)

Set float sequence filler for column with a specified step.

A call to this method is shorthand for sequence(column, initial, x -> x + step).

Parameters:

column - Column name.

initial - Initial sequence value.

step - Sequence step.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, double, double)

sequence

public DataSetBuilder sequence(String column,
                               double initial,
                               double step)

Set double sequence filler for column with a specified step.

A call to this method is shorthand for sequence(column, initial, x -> x + step).

Parameters:

column - Column name.

initial - Initial sequence value.

step - Sequence step.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Object, UnaryOperator), sequence(String, float, float)

sequence

public DataSetBuilder sequence(String column,
                               Date initial,
                               int step)

Set Date sequence filler for column with a specified step in days.

A call to this method is shorthand for sequence(column, initial, d -> new Date(x.getTime() + step * MILLIS_PER_DAY)).

Parameters:

column - Column day.

initial - Initial date.

step - Step in days.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Time, int), sequence(String, Timestamp, long), sequence(String, Object, UnaryOperator)

sequence

public DataSetBuilder sequence(String column,
                               Time initial,
                               int step)

Set Time sequence filler for column with a specified step in seconds.

A call to this method is shorthand for sequence(column, initial, t -> new Time(t.getTime() + step * 1000L)) .

Parameters:

column - Column day.

initial - Initial date.

step - Step in seconds.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Date, int), sequence(String, Timestamp, long), sequence(String, Object, UnaryOperator)

sequence

public DataSetBuilder sequence(String column,
                               Timestamp initial,
                               long step)

Set Timestamp sequence filler for column with a specified step in milliseconds.

A call to this method is shorthand for sequence(column, initial, ts -> new Timestamp(ts.getTime() + step)).

Parameters:

column - Column day.

initial - Initial date.

step - Step in milliseconds.

Returns:

The builder instance (for chained calls).

See Also:

sequence(String, Date, int), sequence(String, Time, int), sequence(String, Object, UnaryOperator)

random

@SafeVarargs
public final <T> DataSetBuilder random(String column,
                                                    T... values)

Set random filler for column using an array of values.

The specified column will be filled with values that are uniformly sampled from the given array.

Type Parameters:

T - Type of data.

Parameters:

column - Column name.

values - Values to use.

Returns:

The builder instance (for chained calls).

See Also:

random(String, List), sequence(String, Object...)

random

public DataSetBuilder random(String column,
                             List<?> values)

Set random filler for column using a list of values.

The specified column will be filled with values that are uniformly sampled from the given list.

Parameters:

column - Column name.

values - Values to use.

Returns:

The builder instance (for chained calls).

See Also:

random(String, Object...), sequence(String, List)

random

public DataSetBuilder random(String column,
                             int min,
                             int max)

Set random filler using int values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, long, long), random(String, float, float), random(String, double, double)

random

public DataSetBuilder random(String column,
                             long min,
                             long max)

Set random filler using long values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, int, int), random(String, float, float), random(String, double, double)

random

public DataSetBuilder random(String column,
                             float min,
                             float max)

Set random filler using float values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, int, int), random(String, long, long), random(String, double, double)

random

public DataSetBuilder random(String column,
                             double min,
                             double max)

Set random filler using double values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, int, int), random(String, long, long), random(String, float, float)

random

public DataSetBuilder random(String column,
                             Date min,
                             Date max)

Set random filler using Date values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, Time, Time), random(String, Timestamp, Timestamp)

random

public DataSetBuilder random(String column,
                             Time min,
                             Time max)

Set random filler using Time values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, Timestamp, Timestamp), random(String, Date, Date)

random

public DataSetBuilder random(String column,
                             Timestamp min,
                             Timestamp max)

Set random filler using Timestamp values.

The specified column will be filled with values that are uniformly sampled from the interval [min,max].

Parameters:

column - Column name.

min - Minimum value.

max - Maximum value.

Returns:

The builder instance (for chained calls).

See Also:

random(String, Time, Time), random(String, Date, Date)

random

public DataSetBuilder random(String column,
                             Function<Random,?> gen)

Set customized random filler.

The specified column will be filled with values that are obtained from a generator function. The generator function takes a Random instance as an argument and returns a value: it should use the generator to produce column values in deterministic fashion (in particular, the random number generator argument should not be re-seeded).

Illustration of use

The filler below will yield strings "ID_0", ..., "ID_9" with an uniform distribution:

 DataSet ds = ...;
 ...
 ds.random("SomeColumn", rng -> "ID_" + rng.nextInt(10));
 

Parameters:

column - Column name.

gen - Generator function.

Returns:

The builder instance (for chained calls).

See Also:

Random, random(String, int, int), random(String, long, long), random(String, float, float), random(String, double, double), random(String, Date, Date), random(String, Time, Time), random(String, Timestamp, Timestamp)