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 statment/database combination.
 * <p>
 * The SqlGenerator implementations are responsible for determining whether the data contained in the SqlStatement method is valid using the validate method.
 * <p>
 * <b>Naming Conventions:</b><br>
 * 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 descrition of what makes them different appended (e.g. CreateTableStatement -> CreateTableGeneratorOracle)
 * <p>
 * <b>NOTE:</b> There is only one instance of each SqlGenerator implementation created, and they must be thread safe.
 * <p>
 * <b>Lifecycle:</b><br>
 * <ol>
 * <li>Instance of SqlGenerator subclass is created when registered with SqlGeneratorFactory</li>
 * <li>For each SqlStatement to execute, SqlGeneratorFactory calls supports() to determine if the given SqlGenerator will work for the current SqlStatement/Database combination</li>
 * <li>SqlGeneratorFactory calls getPriority to determine which of all the SqlGenerators that support a given SqlStatement/Database combination is the best to use.</li>
 * <li>Liquibase calls validate() on the best SqlGenerator to determine if the data contained in the SqlStatement is correct and complete for the given Database</li>
 * <li>If validate returns a no-error ValidationErrors object, Liquibase will call the generateSql() method and execute the resuling SQL against the database.</li>
 * </ol>
 * @param <StatementType> Used to specify which type of SqlStatement this generator supports.
 * If it supports multiple SqlStatement types, pass SqlStatement.  The SqlGeneratorFactory will use this paramter to augment the response from the supports() method
 *
 * @see SqlGeneratorFactory
 * @see liquibase.statement.SqlStatement
 * @see liquibase.sql.Sql
 */
public interface SqlGenerator<StatementType extends SqlStatement> extends PrioritizedService {

    public static final int PRIORITY_DEFAULT = 1;
    public static final int PRIORITY_DATABASE = 5;

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

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

    /**
     * Does this change require access to the database metadata?  If true, the change cannot be used in an updateSql-style command.
     */
    public boolean requiresUpdatedDatabaseMetadata(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.
     */
    public ValidationErrors validate(StatementType statement, Database database, SqlGeneratorChain sqlGeneratorChain);

    public Warnings warn(StatementType statementType, Database database, SqlGeneratorChain sqlGeneratorChain);

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