com.ninja_squad.dbsetup.operation
Class Insert.Builder

java.lang.Object
  com.ninja_squad.dbsetup.operation.Insert.Builder

Enclosing class:

Insert

public static final class Insert.Builder
extends java.lang.Object

A builder used to create an Insert operation. Such a builder may only be used once. Once it has built its Insert operation, all its methods throw an IllegalStateException.

See Also:

Insert, Insert.into(String)

columns

public Insert.Builder columns(@Nonnull
                              java.lang.String... columns)

Specifies the list of columns into which values will be inserted. The values must the be specified, after, using the values(Object...) method, or with the values(java.util.Map) method, or by adding a row with named columns fluently using row().

Parameters:

columns - the names of the columns to insert into.

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built, or if this method has already been called, or if one of the given columns is also specified as one of the generated value columns, or if the set of columns has already been defined by adding a first row to the builder.

values

public Insert.Builder values(@Nonnull
                             java.lang.Object... values)

Adds a row of values to insert.

Parameters:

values - the values to insert.

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built, or if the number of values doesn't match the number of columns.

repeatingValues

public Insert.RowRepeater repeatingValues(@Nonnull
                                          java.lang.Object... values)

Allows adding many rows with the same non-generated values to insert.

Parameters:

values - the values to insert.

Returns:

A RowRepeater, allowing to choose how many similar rows to add.

Throws:

java.lang.IllegalStateException - if the Insert has already been built, or if the number of values doesn't match the number of columns.

row

public Insert.RowBuilder row()

Starts building a new row with named columns to insert. If the row is the first one being added and the columns haven't been set yet by calling columns(), then the columns of this row constitute the column names (excluding the generated ones) of the Insert being built

Returns:

a Insert.RowBuilder instance, which, when built, will add a row (or several ones) to this insert builder.

Throws:

java.lang.IllegalStateException - if the Insert has already been built.

See Also:

Insert.RowBuilder

values

public Insert.Builder values(@Nonnull
                             java.util.Map<java.lang.String,?> row)

Adds a row to this builder. If no row has been added yet and the columns haven't been set yet by calling columns(), then the keys of this map constitute the column names (excluding the generated ones) of the Insert being built, in the order of the keys in the map (which is arbitrary unless an ordered or sorted map is used).

Parameters:

row - the row to add. The keys of the map are the column names, which must match with the column names specified in the call to columns(String...), or with the column names of the first added row. If a column name is not present in the map, null is inserted for this column.

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built.

java.lang.IllegalArgumentException - if a column name of the map doesn't match with any of the column names specified with columns(String...)

repeatingValues

public Insert.RowRepeater repeatingValues(@Nonnull
                                          java.util.Map<java.lang.String,?> row)

Allows adding many rows with the same non-generated values to insert.

Returns:

A RowRepeater, allowing to choose how many similar rows to add.

Throws:

java.lang.IllegalStateException - if the Insert has already been built.

See Also:

values(Map)

withBinder

public Insert.Builder withBinder(@Nonnull
                                 Binder binder,
                                 @Nonnull
                                 java.lang.String... columns)

Associates a Binder to one or several columns.

Parameters:

binder - the binder to use, regardless of the metadata, for the given columns

columns - the name of the columns to associate with the given Binder

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built,

java.lang.IllegalArgumentException - if any of the given columns is not part of the columns or "generated value" columns.

withDefaultValue

public Insert.Builder withDefaultValue(@Nonnull
                                       java.lang.String column,
                                       java.lang.Object value)

Specifies a default value to be inserted in a column for all the rows inserted by the Insert operation. Calling this method is equivalent to calling withGeneratedValue(column, ValueGenerators.constant(value))

Parameters:

column - the name of the column

value - the default value to insert into the column

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built, or if the given column is part of the columns to insert.

withGeneratedValue

public Insert.Builder withGeneratedValue(@Nonnull
                                         java.lang.String column,
                                         @Nonnull
                                         ValueGenerator<?> valueGenerator)

Allows the given column to be populated by a value generator, which will be called for every row of the Insert operation being built.

Parameters:

column - the name of the column

valueGenerator - the generator generating values for the given column of every row

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built, or if the given column is part of the columns to insert.

useMetadata

public Insert.Builder useMetadata(boolean useMetadata)

Determines if the metadata must be used to get the appropriate binder for each inserted column (except the ones which have been associated explicitly with a Binder). The default is true. The insert can be faster if set to false, but in this case, the binder used will be the one returned by the BinderConfiguration for a null metadata (which is, by default, the default binder), except the ones which have been associated explicitly with a Binder.
Before version 1.3.0, a SQLException was thrown if the database doesn't support parameter metadata and useMetadata(false) wasn't called. Since version 1.3.0, if useMetadata is true (the default) but the database doesn't support metadata, then the default binder configuration returns the default binder. Using this method is thus normally unnecessary as of 1.3.0.

Returns:

this Builder instance, for chaining.

Throws:

java.lang.IllegalStateException - if the Insert has already been built.

build

public Insert build()

Builds the Insert operation.

Returns:

the created Insert operation.

Throws:

java.lang.IllegalStateException - if the Insert has already been built, or if no column and no generated value column has been specified.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object