// This Source Code is in the Public Domain per: http://unlicense.org
package org.litesoft.orsup.nonpublic;

import org.litesoft.db.*;
import org.litesoft.orsup.base.*;
import org.litesoft.orsup.selection.*;

public interface PersistenceHelper
{
    /**
     * @throws Error if the DB can NOT be initialized
     */
    public void initializeDB();

    public DBconnection createConnection()
            throws DBException;

    /**
     * @return Converted pIdentifier based on the "Caseing" of this DB.
     */
    public String normalizeIdentifier( String pIdentifier );

    /**
     * Determine all the tables that are made up of the 'pTableNameParts' where if only 1, then must be equal,
     * otherwise the found table names will: "start with" the first element of the pTableNameParts array &&
     * "end with" the last element of the pTableNameParts array && contain (in order with no overlap) all the
     * the middle elements of the pTableNameParts.
     *
     * @param pTableNameParts Non-null & not-empty list of strings that make up a pattern to match table names
     *
     * @return Non-null list of the matching table names - which may be empty.
     *
     * @throws DBException - Exception regarding the DB
     */
    public String[] getTables( String... pTableNameParts )
            throws DBException;

    /**
     * Determine all the columns for a table.
     *
     * @param pTableName Non-null & not-empty table name.
     *
     * @return Non-null list of the table's columns - which may be empty.
     *
     * @throws NoTableException        - No Table was found for the given pTableName
     * @throws MultipleTablesException - Multiple Tables were found for the given pTableName
     * @throws DBException             - Some other Exception regarding the DB
     */
    public DBtableColumn[] getColumns( String pTableName )
            throws NoTableException, MultipleTablesException, DBException;

    /**
     * Determine all the indexes for a table.
     *
     * @param pTableName Non-null & not-empty table name.
     *
     * @return Non-null list of the table's indexes - which may be empty.
     *
     * @throws NoTableException        - No Table was found for the given pTableName
     * @throws MultipleTablesException - Multiple Tables were found for the given pTableName
     * @throws DBException             - Some other Exception regarding the DB
     */
    public DBtableIndex[] getIndexes( String pTableName )
            throws NoTableException, MultipleTablesException, DBException;

    /**
     * Determine all the columns for a table.
     *
     * @param pSimpleFromIdentifier Non-null
     *
     * @return Non-null list of the table's columns - which may be empty.
     *
     * @throws NoTableException        - No Table was found for the given pTableName
     * @throws MultipleTablesException - Multiple Tables were found for the given pTableName
     * @throws DBException             - Some other Exception regarding the DB
     */
    public DBtableColumn[] getColumns( SimpleFromIdentifier pSimpleFromIdentifier )
            throws NoTableException, MultipleTablesException, DBException;

    /**
     * Determine all the indexes for a table.
     *
     * @param pSimpleFromIdentifier Non-null
     *
     * @return Non-null list of the table's indexes - which may be empty.
     *
     * @throws NoTableException        - No Table was found for the given pTableName
     * @throws MultipleTablesException - Multiple Tables were found for the given pTableName
     * @throws DBException             - Some other Exception regarding the DB
     */
    public DBtableIndex[] getIndexes( SimpleFromIdentifier pSimpleFromIdentifier )
            throws NoTableException, MultipleTablesException, DBException;

    /**
     * @return TRUE if table exists,
     *         FALSE if table appears to not exist
     *
     * @throws DBException - Exception regarding the DB
     */
    public boolean tableExists( SimpleFromIdentifier pSimpleFromIdentifier )
            throws DBException, MultipleTablesException;

    public boolean columnExists( SimpleFromIdentifier pSimpleFromIdentifier, String pColumnName )
            throws DBException, MultipleTablesException;

    /**
     * @return TRUE if index exists,
     *         FALSE if index appears to not exist
     */
    public boolean indexExists( SimpleFromIdentifier pSimpleFromIdentifier, String pIndexName )
            throws DBException;

    public long rawCount( SimpleFromIdentifier pSimpleFromIdentifier, WhereClause pSelectionWhereClause )
            throws DBException;

    public void deleteRows( SimpleFromIdentifier pSimpleFromIdentifier, WhereClause pSelectionWhereClause )
            throws DBException;

    public void deleteRows( DBconnection pDBconnection, SimpleFromIdentifier pSimpleFromIdentifier, WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pSimpleFromIdentifier - Normally the Table Identifier
     * @param pKeyCD                - The Unique Key Column of the table
     * @param pSnagCD               - The Snag Column of the table
     * @param pUniqueSnagValue      - The Unique Value for the Snag Column, that if set will be unique in the table
     * @param pSelectionWhereClause - null means all, which will only succeed if the table only has one entry
     * @param pOrderBy              - null means order immaterial
     * @param pUpdateValuePairs     - additional columns to set
     *
     * @return true if row 'snaged'
     *
     * @throws DBException - Exception regarding the DB
     */
    public boolean snagOne( SimpleFromIdentifier pSimpleFromIdentifier, SimpleColumnDefinition pKeyCD, SimpleColumnDefinition pSnagCD, Long pUniqueSnagValue, WhereClause pSelectionWhereClause, OrderBy pOrderBy, ColumnUpdateValuePair[] pUpdateValuePairs )
            throws DBException;

    public void deleteAllRows( SimpleFromIdentifier pSimpleFromIdentifier )
            throws DBException;

    public void deleteAllRows( DBconnection pDBconnection, SimpleFromIdentifier pSimpleFromIdentifier )
            throws DBException;

    public void dropTable( TableManager pTableManager, SimpleFromIdentifier pSimpleFromIdentifier )
            throws DBException;

    public void addColumnToExistingTable( SimpleFromIdentifier pSimpleFromIdentifier, SimpleColumnDefinitionExtended pSCD )
            throws DBException;
}