nz.co.gregs.dbvolution

Class DBMigration<M extends DBRow>

java.lang.Object

nz.co.gregs.dbvolution.query.RowDefinition

nz.co.gregs.dbvolution.DBMigration<M>

All Implemented Interfaces:

Serializable

public class DBMigration<M extends DBRow>
extends RowDefinition

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
DBMigration(DBDatabase db, M migrationMapper)

Method Summary

Methods

Modifier and Type	Method and Description
void	addAsOptionalTables(DBRow... examples) Add the rows as optional tables in the query.
Long	count(DBDatabase database, DBRow... rows) Count the rows on the database without retrieving the rows.
List<M>	getAllRows() Gets all the migrated rows using only conditions supplied within the supplied DBMigration.
List<M>	getAllRows(DBRow... extraExamples) Gets all the migrated rows using conditions in the DBMigration and the supplied examples.
List<M>	getRows(DBDatabase database, DBRow... rows) Gets all the report rows of the migration limited by the supplied example rows.
List<M>	getRowsHaving(DBDatabase database, DBRow[] rows, BooleanExpression... conditions) Gets all the report rows of this DBMigration limited by the supplied example rows but reduce the result to only those that match the conditions.
protected ColumnProvider[]	getSortColumns() Returns the list of sort columns Support DBvolution at Patreon
String	getSQLForCount(DBDatabase database, DBRow... rows) Returns the SQL query that will used to count the rows returned for the supplied DBReport
String	getSQLForInsert(DBDatabase database, DBRow... rows) Generates and returns the actual SQL to be used by this DBQueryInsert to insert the queried rows.
String	getSQLForQuery(DBDatabase database, DBRow... rows) Generates and returns the actual SQL to be used by this DBQueryInsert to select the rows to insert.
void	insertAllRows(DBRow... extraExamples)
DBMigration<M>	setBlankQueryAllowed(Boolean setting) Change the Default Setting of Disallowing Blank Queries
DBMigration<M>	setCartesianJoinAllowed(Boolean setting) Suppresses Cartesian join error protection.
DBMigration<M>	setSortOrder(ColumnProvider... columns) Sets the sort order of DBReport (field and/or method) by the given column providers.
DBMigration<M>	setSortOrder(QueryableDatatype<?>... columns) Sets the sort order of DBReport (field and/or method) by the given column providers.
String	toString()
DBMigrationValidation.Results	validateAllRows(DBRow... extraExamples)

Methods inherited from class nz.co.gregs.dbvolution.query.RowDefinition

column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, column, getAutoFillingPropertyWrappers, getColumnPropertyWrapperDefinitions, getColumnPropertyWrappers, getDBExpression, getFieldNames, getFieldValues, getPropertyWrapperOf, getReturnColumns, getWrapper, setReturnColumns

Methods inherited from class java.lang.Object

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

Constructor Detail

DBMigration

public DBMigration(DBDatabase db,
           M migrationMapper)

Method Detail

getAllRows

public List<M> getAllRows()
                                 throws SQLException

Gets all the migrated rows using only conditions supplied within the supplied DBMigration.

Use this method to retrieve all rows when the criteria have been supplied as part of the DBMigration subclass.

If you require extra criteria to be add to the DBMigration, limiting the results to a subset, use the other getAllRows method.

Support DBvolution at Patreon

Returns:

a list of DBReport instances representing the results of the report query. Database exceptions may be thrown

Throws:

SQLException - java.sql.SQLException

getAllRows

public List<M> getAllRows(DBRow... extraExamples)
                                 throws SQLException

Gets all the migrated rows using conditions in the DBMigration and the supplied examples.

Parameters:

extraExamples - extra rows defining additional criteria

Support DBvolution at Patreon

Returns:

a list of DBReport instances representing the results of the report query. 1 Database exceptions may be thrown

Throws:

SQLException - java.sql.SQLException

toString

public String toString()

Overrides:

toString in class RowDefinition

getRows

public List<M> getRows(DBDatabase database,
              DBRow... rows)
                              throws SQLException

Gets all the report rows of the migration limited by the supplied example rows.

All supplied rows should be from a DBRow subclass that is included in the report.

Builtin report limitation will be used, the example rows supply further details for constraining the report.

This method allows you to create generic reports and apply dynamic limitations such as date ranges, department name, and other highly variable parameters.

Parameters:

database - database

rows - rows

Support DBvolution at Patreon

Returns:

a list of DBReport instances representing the results of the report query. 1 Database exceptions may be thrown

Throws:

SQLException - java.sql.SQLException

getRowsHaving

public List<M> getRowsHaving(DBDatabase database,
                    DBRow[] rows,
                    BooleanExpression... conditions)
                                    throws SQLException

Gets all the report rows of this DBMigration limited by the supplied example rows but reduce the result to only those that match the conditions.

All conditions should only reference the fields/column of the DBMigration.

All supplied rows should be from a DBRow subclass that is included in the report.

Built-in report limitation will be used, the example rows supply further details for constraining the report.

This method allows you to create generic reports and apply dynamic limitations such as date ranges, department name, and other highly variable parameters.

Parameters:

database - database

rows - rows example rows that provide extra criteria

conditions - the conditions that will be supplied to the WHERE or HAVING clause of the query

Support DBvolution at Patreon

Returns:

a list of DBReport instances representing the results of the report query

Throws:

SQLException - Database exceptions may be thrown

getSQLForQuery

public String getSQLForQuery(DBDatabase database,
                    DBRow... rows)

Generates and returns the actual SQL to be used by this DBQueryInsert to select the rows to insert.

Good for debugging and great for DBAs, this is how you find out what DBvolution is really doing.

Generates the SQL query for retrieving the objects but does not execute the SQL. Use the getAllRows method to retrieve the rows.

See also #getSQLForCount(nz.co.gregs.dbvolution.DBDatabase, nz.co.gregs.dbvolution.DBRow...)

Parameters:

database - the database the SQL will be run against.

rows - additional conditions to apply to the report.

Support DBvolution at Patreon

Returns:

a String of the SQL that will be used by this DBQuery. 1 Database exceptions may be thrown

getSQLForInsert

public String getSQLForInsert(DBDatabase database,
                     DBRow... rows)

Generates and returns the actual SQL to be used by this DBQueryInsert to insert the queried rows.

Good for debugging and great for DBAs, this is how you find out what DBvolution is really doing.

Generates the SQL query for retrieving the objects but does not execute the SQL. Use the getAllRows method to retrieve the rows.

See also #getSQLForCount(nz.co.gregs.dbvolution.DBDatabase, nz.co.gregs.dbvolution.DBRow...)

Parameters:

database - the database the SQL will be run against.

rows - additional conditions to apply to the report.

Support DBvolution at Patreon

Returns:

a String of the SQL that will be used by this DBQuery. 1 Database exceptions may be thrown

getSQLForCount

public String getSQLForCount(DBDatabase database,
                    DBRow... rows)
                      throws SQLException

Returns the SQL query that will used to count the rows returned for the supplied DBReport

Use this method to check the SQL that will be executed during the count method

Parameters:

database - the database to format the query for.

rows - additional conditions to be applied.

Support DBvolution at Patreon

Returns:

a String of the SQL query that will be used to count the rows returned by this report 1 Database exceptions may be thrown

Throws:

SQLException - java.sql.SQLException

count

public Long count(DBDatabase database,
         DBRow... rows)
           throws SQLException

Count the rows on the database without retrieving the rows.

Creates a count query for the report and conditions and retrieves the number of rows that would have been returned had getAllRows method been called.

Parameters:

database - the database to format the query for.

rows - additional conditions for the query.

Support DBvolution at Patreon

Returns:

the number of rows that have or will be retrieved. 1 Database exceptions may be thrown

Throws:

SQLException - java.sql.SQLException

setSortOrder

public DBMigration<M> setSortOrder(ColumnProvider... columns)

Sets the sort order of DBReport (field and/or method) by the given column providers.

For example the following code snippet will sort by just the name column:

 CustomerReport customers = ...;
 customers.setSortOrder(customers.column(customers.name));
 

Parameters:

columns - a list of columns to sort the query by.

Support DBvolution at Patreon

Returns:

this DBReport instance

setSortOrder

public DBMigration<M> setSortOrder(QueryableDatatype<?>... columns)

Sets the sort order of DBReport (field and/or method) by the given column providers.

ONLY USE FIELDS FROM THE SAME INSTANCE.

For example the following code snippet will sort by the name and accountNumber columns:

 CustomerReport customers = ...;
 customers.setSortOrder(customers.name, customers.accountNumber);
 

Parameters:

columns - a list of columns to sort the query by.

Support DBvolution at Patreon

Returns:

this DBReport instance

addAsOptionalTables

public void addAsOptionalTables(DBRow... examples)

Add the rows as optional tables in the query.

Parameters:

examples -

getSortColumns

protected ColumnProvider[] getSortColumns()

Returns the list of sort columns

Support DBvolution at Patreon

Returns:

the sortColumns

setCartesianJoinAllowed

public DBMigration<M> setCartesianJoinAllowed(Boolean setting)

Suppresses Cartesian join error protection.

DBvolution protects you from accidental Cartesian joins but use this function if a Cartesian is required.

Cartesian joins occur when there is no connection between 2 (or more) tables. Normally all tables are connect by a chain of relationships, usually primary key to foreign key.

Sometimes a connection is missed: for instance 2 unrelated tables are being compared by price, but the price relating expression has not been added. In this case DBvolution will throw an AccidentalCartesianJoinException and abort the query. This exception avoids creating a probably massive dataset that will reduce database and network performance significantly.

However there are valid cases for a Cartesian join: finding all possible combinations of cake and coffee for instance.

If you are sure you need a Cartesian join, use this method to avoid the error-checking and the AccidentalCartesianJoinException

Parameters:

setting - True if you need a Cartesian join in this DBQueryInsert.

Support DBvolution at Patreon

Returns:

this DBQueryInsert object

setBlankQueryAllowed

public DBMigration<M> setBlankQueryAllowed(Boolean setting)

Change the Default Setting of Disallowing Blank Queries

A common mistake is creating a query without supplying criteria and accidently retrieving a huge number of rows.

DBvolution detects this situation and, by default, throws a AccidentalBlankQueryException when it happens.

To change this behaviour, and allow blank queries, call setBlankQueriesAllowed(true).

Parameters:

setting - - TRUE to allow blank queries, FALSE to return it to the default setting.

Support DBvolution at Patreon

Returns:

this DBQueryInsert instance

insertAllRows

public void insertAllRows(DBRow... extraExamples)
                   throws SQLException

Throws:

SQLException

validateAllRows

public DBMigrationValidation.Results validateAllRows(DBRow... extraExamples)
                                              throws SQLException

Throws:

SQLException