Package nz.co.gregs.dbvolution

Class DBMigration<M extends DBRow>

    • Method Detail

      • using

        public static <MAPPER extends DBRow> DBMigration<MAPPER> using​(DBDatabase database,
                                                               MAPPER migrationMapper)
        Create a migration that uses the mapper provided.

        Mapper uses a subclass of a particular DBRow to create rows for that DBRow and insert them into the table.

        Central to this concept is using other existing data in table, represented by their own DBRow classes, transformed using DBvolution expressions

         public static class MigrateToFight extends Fight {
 public Villain baddy = new Villain();
 public Hero goody = new Hero();
 {
 baddy.name.permittedPattern("Dr%");
 hero = goody.column(goody.name).asExpressionColumn();
 villain = baddy.column(baddy.name).asExpressionColumn();
 }
 }
 database.createTable(new Fight());
 DBMigration migration = DBMigration.using(new MigrateToFight());
 migration.createAllRows(database);
        Type Parameters:
        MAPPER - the transformation to apply
        Parameters:
        database - the database to work with
        migrationMapper - the transformation class
        Returns:
        a DBMigration object

      • getRows

        public List<M> getRows​(DBRow... rows)
                throws SQLException,
                       AccidentalCartesianJoinException,
                       AccidentalBlankQueryException
        Gets all the report rows of the migration limited by the supplied example rows.

        All supplied rows should be using 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:
        rows - rows
        Returns:
        a list of DBReport instances representing the results of the report query. 1 Database exceptions may be thrown
        Throws:
        SQLException - java.sql.SQLException
        AccidentalBlankQueryException - thrown if no conditions have been set and blank queries have not been explicitly allowed
        AccidentalCartesianJoinException

      • getRowsHaving

        public List<M> getRowsHaving​(DBRow[] rows,
                             BooleanExpression... conditions)
                      throws SQLException,
                             AccidentalCartesianJoinException,
                             AccidentalBlankQueryException
        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 using 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:
        rows - rows example rows that provide extra criteria
        conditions - the conditions that will be supplied to the WHERE or HAVING clause of the query
        Returns:
        a list of DBReport instances representing the results of the report query
        Throws:
        SQLException - Database exceptions may be thrown
        AccidentalBlankQueryException - thrown if no conditions have been set and blank queries have not been explicitly allowed
        AccidentalCartesianJoinException

      • getSQLForQuery

        public String getSQLForQuery​(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.DBRow...)

        Parameters:
        rows - additional conditions to apply to the report.
        Returns:
        a String of the SQL that will be used by this DBQuery. 1 Database exceptions may be thrown

      • getSQLForInsert

        public String getSQLForInsert​(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.DBRow...)

        Parameters:
        rows - additional conditions to apply to the report.
        Returns:
        a String of the SQL that will be used by this DBQuery. 1 Database exceptions may be thrown

      • getSQLForCount

        public String getSQLForCount​(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:
        rows - additional conditions to be applied.
        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

      • addAsOptionalTables

        public void addAsOptionalTables​(DBRow... examples)
        Add the rows as optional tables in the query.

        Optional tables are joined to the query using an outer join and results are returned regardless of whether there is a matching row in the optional table.

        Optional rows may contain only DBNull values, that is there getValue() method will return NULL and isDBNull() will be true.

        Parameters:
        examples - additional tables to include in the query if possible.

      • getSortColumns

        public SortProvider[] getSortColumns()
        Returns the list of sort columns
        Returns:
        the sortColumns

      • setCartesianJoinAllowed

        public DBMigration<M> setCartesianJoinAllowed​(Boolean setting)
        Suppresses Cartesian join error protection.

        DBvolution protects you using 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.
        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 accidentally 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.
        Returns:
        this DBQueryInsert instance

      • validateAllRows

        public DBMigrationValidation.Results validateAllRows​(DBRow... extraExamples)
                                              throws SQLException
        Perform a migration validation using DBMigrationValidation.

        Validation will process all the available rows and try migrate them or to identify why they were not migrated. FAILURE TO MIGRATE MAY BE CORRECT BEHAVIOUR. Carefully check the results to determine if there are issues with the migration or the data.

        Parameters:
        extraExamples - extra examples
        Returns:
        result from the migration validation
        Throws:
        SQLException - if the database has an issue with the validation script

      • getCartesianJoinsAllowed

        public boolean getCartesianJoinsAllowed()

      • getBlankQueryAllowed

        public boolean getBlankQueryAllowed()

      • getMapper

        public M getMapper()

      • getOptionalTables

        public List<DBRow> getOptionalTables()