liquibase.sqlgenerator.SqlGenerator Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of liquibase-core Show documentation
Liquibase is a tool for managing and executing database changes.
There is a newer version: 4.29.2
package liquibase.sqlgenerator;

import liquibase.database.Database;
import liquibase.exception.ValidationErrors;
import liquibase.exception.Warnings;
import liquibase.servicelocator.PrioritizedService;
import liquibase.sql.Sql;
import liquibase.statement.SqlStatement;

/**
 * SqlGenerator implementations take a database-independent SqlStatement interface and create a
 * database-specific Sql object.
 * SqlGenerators are registered with the SqlGeneratorFactory, which is used to determine the correct generator to
 * use for a given statement/database combination.
 * 
 * The SqlGenerator implementations are responsible for determining whether the data contained in the SqlStatement
 * method is valid using the validate method.
 * 

 * Naming Conventions:

 * Default SqlGenerators for a particular SqlStatement use the same name as the SqlStatement class, replacing
 * "Statement" with "Generator" (e.g.: CreateTableStatement -> CreateTableGenerator).
 * Database-specific or alternate SqlGenerators append a description of what makes them different appended
 * (e.g. CreateTableStatement -> CreateTableGeneratorOracle)
 * 

 * NOTE: There is only one instance of each SqlGenerator implementation created, and they must be thread safe.
 * 

 * Lifecycle:

 * 

 * Instance of SqlGenerator subclass is created when registered with SqlGeneratorFactory
 * For each SqlStatement to execute, SqlGeneratorFactory calls supports() to determine if the given SqlGenerator
 * will work for the current SqlStatement/Database combination
 * SqlGeneratorFactory calls getPriority to determine which of all the SqlGenerators that support a given
 * SqlStatement/Database combination is the best to use.
 * Liquibase calls validate() on the best SqlGenerator to determine if the data contained in the SqlStatement is
 * correct and complete for the given Database
 * If validate returns a no-error ValidationErrors object, Liquibase will call the generateSql() method and
 * execute the resulting SQL against the database.
 * 
 * @param  Used to specify which type of SqlStatement this generator supports.
 * If it supports multiple SqlStatement types, pass SqlStatement.  The SqlGeneratorFactory will use this parameter
 *                       to augment the response from the supports() method
 *
 * @see SqlGeneratorFactory
 * @see liquibase.statement.SqlStatement
 * @see liquibase.sql.Sql
 */
public interface SqlGenerator extends PrioritizedService {
    int PRIORITY_DEFAULT = 1;
    int PRIORITY_DATABASE = 5;

    /**
     * Represent an empty array of {@link Sql}.
     */
    Sql[] EMPTY_SQL = {};

    /**
     * Of all the SqlGenerators that "support" a given SqlStatement/Database, SqlGeneratorFactory will return the one
     * with the highest priority.
     */
    @Override
    int getPriority();

    /**
     * Does this generator support the given statement/database combination? Do not validate the statement with this
     * method, only return if it can support it.
     */
    boolean supports(T statement, Database database);

    /**
     * Does this change require access to the database metadata?  If true, the change cannot be used in an
     * updateSql-style command.
     */
    boolean generateStatementsIsVolatile(Database database);

    boolean generateRollbackStatementsIsVolatile(Database database);
    /**
     * Validate the data contained in the SqlStatement.  If there are no errors, return an empty ValidationErrors
     * object, not a null value.
     * Liquibase will inspect the ValidationErrors result before attempting to call generateSql.
     */
    ValidationErrors validate(T statement, Database database, SqlGeneratorChain sqlGeneratorChain);

    Warnings warn(T statementType, Database database, SqlGeneratorChain sqlGeneratorChain);

    /**
     * Generate the actual Sql for the given statement and database.
     */
    Sql[] generateSql(T statement, Database database, SqlGeneratorChain sqlGeneratorChain);
}