/*
 * Copyright 2004-2019 H2 Group. Multiple-Licensed under the MPL 2.0,
 * and the EPL 1.0 (http://h2database.com/html/license.html).
 * Initial Developer: H2 Group
 */
package org.h2.index;

import org.h2.command.dml.AllColumnsForPlan;
import org.h2.engine.Session;
import org.h2.result.Row;
import org.h2.result.SearchRow;
import org.h2.result.SortOrder;
import org.h2.schema.SchemaObject;
import org.h2.table.Column;
import org.h2.table.IndexColumn;
import org.h2.table.Table;
import org.h2.table.TableFilter;

An index. Indexes are used to speed up searching data.
/**
 * An index. Indexes are used to speed up searching data.
 */
public interface Index extends SchemaObject {

    
Get the message to show in a EXPLAIN statement.
Returns:
the plan/**
     * Get the message to show in a EXPLAIN statement.
     *
     * @return the plan
     */
    String getPlanSQL();

    
Close this index.
Params:
session – the session used to write data/**
     * Close this index.
     *
     * @param session the session used to write data
     */
    void close(Session session);

    
Add a row to the index.
Params:
session – the session to use
row – the row to add/**
     * Add a row to the index.
     *
     * @param session the session to use
     * @param row the row to add
     */
    void add(Session session, Row row);

    
Remove a row from the index.
Params:
session – the session
row – the row/**
     * Remove a row from the index.
     *
     * @param session the session
     * @param row the row
     */
    void remove(Session session, Row row);

    
Update index after row change.
Params:
session – the session
oldRow – row before the update
newRow – row after the update/**
     * Update index after row change.
     *
     * @param session the session
     * @param oldRow row before the update
     * @param newRow row after the update
     */
    void update(Session session, Row oldRow, Row newRow);

    
Returns true if find() implementation performs scan over all index, false if find() performs the fast lookup. 
Returns:
true if find() implementation performs scan over all index, false if find() performs the fast lookup/**
     * Returns {@code true} if {@code find()} implementation performs scan over all
     * index, {@code false} if {@code find()} performs the fast lookup.
     *
     * @return {@code true} if {@code find()} implementation performs scan over all
     *         index, {@code false} if {@code find()} performs the fast lookup
     */
    boolean isFindUsingFullTableScan();

    
Find a row or a list of rows and create a cursor to iterate over the
result.
Params:
session – the session
first – the first row, or null for no limit
last – the last row, or null for no limit
Returns:
the cursor to iterate over the results/**
     * Find a row or a list of rows and create a cursor to iterate over the
     * result.
     *
     * @param session the session
     * @param first the first row, or null for no limit
     * @param last the last row, or null for no limit
     * @return the cursor to iterate over the results
     */
    Cursor find(Session session, SearchRow first, SearchRow last);

    
Find a row or a list of rows and create a cursor to iterate over the
result.
Params:
filter – the table filter (which possibly knows about additional
           conditions)
first – the first row, or null for no limit
last – the last row, or null for no limit
Returns:
the cursor to iterate over the results/**
     * Find a row or a list of rows and create a cursor to iterate over the
     * result.
     *
     * @param filter the table filter (which possibly knows about additional
     *            conditions)
     * @param first the first row, or null for no limit
     * @param last the last row, or null for no limit
     * @return the cursor to iterate over the results
     */
    Cursor find(TableFilter filter, SearchRow first, SearchRow last);

    
Estimate the cost to search for rows given the search mask.
There is one element per column in the search mask.
For possible search masks, see IndexCondition.
Params:
session – the session
masks – per-column comparison bit masks, null means 'always false',
             see constants in IndexCondition
filters – all joined table filters
filter – the current table filter index
sortOrder – the sort order
allColumnsSet – the set of all columns
Returns:
the estimated cost/**
     * Estimate the cost to search for rows given the search mask.
     * There is one element per column in the search mask.
     * For possible search masks, see IndexCondition.
     *
     * @param session the session
     * @param masks per-column comparison bit masks, null means 'always false',
     *              see constants in IndexCondition
     * @param filters all joined table filters
     * @param filter the current table filter index
     * @param sortOrder the sort order
     * @param allColumnsSet the set of all columns
     * @return the estimated cost
     */
    double getCost(Session session, int[] masks, TableFilter[] filters, int filter,
            SortOrder sortOrder, AllColumnsForPlan allColumnsSet);

    
Remove the index.
Params:
session – the session/**
     * Remove the index.
     *
     * @param session the session
     */
    void remove(Session session);

    
Remove all rows from the index.
Params:
session – the session/**
     * Remove all rows from the index.
     *
     * @param session the session
     */
    void truncate(Session session);

    
Check if the index can directly look up the lowest or highest value of a
column.
Returns:
true if it can/**
     * Check if the index can directly look up the lowest or highest value of a
     * column.
     *
     * @return true if it can
     */
    boolean canGetFirstOrLast();

    
Check if the index can get the next higher value.
Returns:
true if it can/**
     * Check if the index can get the next higher value.
     *
     * @return true if it can
     */
    boolean canFindNext();

    
Find a row or a list of rows that is larger and create a cursor to
iterate over the result.
Params:
session – the session
higherThan – the lower limit (excluding)
last – the last row, or null for no limit
Returns:
the cursor/**
     * Find a row or a list of rows that is larger and create a cursor to
     * iterate over the result.
     *
     * @param session the session
     * @param higherThan the lower limit (excluding)
     * @param last the last row, or null for no limit
     * @return the cursor
     */
    Cursor findNext(Session session, SearchRow higherThan, SearchRow last);

    
Find the first (or last) value of this index. The cursor returned is
positioned on the correct row, or on null if no row has been found.
Params:
session – the session
first – true if the first (lowest for ascending indexes) or last
           value should be returned
Returns:
a cursor (never null)/**
     * Find the first (or last) value of this index. The cursor returned is
     * positioned on the correct row, or on null if no row has been found.
     *
     * @param session the session
     * @param first true if the first (lowest for ascending indexes) or last
     *            value should be returned
     * @return a cursor (never null)
     */
    Cursor findFirstOrLast(Session session, boolean first);

    
Check if the index needs to be rebuilt.
This method is called after opening an index.
Returns:
true if a rebuild is required./**
     * Check if the index needs to be rebuilt.
     * This method is called after opening an index.
     *
     * @return true if a rebuild is required.
     */
    boolean needRebuild();

    
Get the row count of this table, for the given session.
Params:
session – the session
Returns:
the row count/**
     * Get the row count of this table, for the given session.
     *
     * @param session the session
     * @return the row count
     */
    long getRowCount(Session session);

    
Get the approximated row count for this table.
Returns:
the approximated row count/**
     * Get the approximated row count for this table.
     *
     * @return the approximated row count
     */
    long getRowCountApproximation();

    
Get the used disk space for this index.
Returns:
the estimated number of bytes/**
     * Get the used disk space for this index.
     *
     * @return the estimated number of bytes
     */
    long getDiskSpaceUsed();

    
Compare two rows.
Params:
rowData – the first row
compare – the second row
Returns:
0 if both rows are equal, -1 if the first row is smaller,
        otherwise 1/**
     * Compare two rows.
     *
     * @param rowData the first row
     * @param compare the second row
     * @return 0 if both rows are equal, -1 if the first row is smaller,
     *         otherwise 1
     */
    int compareRows(SearchRow rowData, SearchRow compare);

    
Get the index of a column in the list of index columns
Params:
col – the column
Returns:
the index (0 meaning first column)/**
     * Get the index of a column in the list of index columns
     *
     * @param col the column
     * @return the index (0 meaning first column)
     */
    int getColumnIndex(Column col);

    
Check if the given column is the first for this index
Params:
column – the column
Returns:
true if the given columns is the first/**
     * Check if the given column is the first for this index
     *
     * @param column the column
     * @return true if the given columns is the first
     */
    boolean isFirstColumn(Column column);

    
Get the indexed columns as index columns (with ordering information).
Returns:
the index columns/**
     * Get the indexed columns as index columns (with ordering information).
     *
     * @return the index columns
     */
    IndexColumn[] getIndexColumns();

    
Get the indexed columns.
Returns:
the columns/**
     * Get the indexed columns.
     *
     * @return the columns
     */
    Column[] getColumns();

    
Get the index type.
Returns:
the index type/**
     * Get the index type.
     *
     * @return the index type
     */
    IndexType getIndexType();

    
Get the table on which this index is based.
Returns:
the table/**
     * Get the table on which this index is based.
     *
     * @return the table
     */
    Table getTable();

    
Get the row with the given key.
Params:
session – the session
key – the unique key
Returns:
the row/**
     * Get the row with the given key.
     *
     * @param session the session
     * @param key the unique key
     * @return the row
     */
    Row getRow(Session session, long key);

    
Does this index support lookup by row id?
Returns:
true if it does/**
     * Does this index support lookup by row id?
     *
     * @return true if it does
     */
    boolean isRowIdIndex();

    
Can this index iterate over all rows?
Returns:
true if it can/**
     * Can this index iterate over all rows?
     *
     * @return true if it can
     */
    boolean canScan();

    
Enable or disable the 'sorted insert' optimizations (rows are inserted in
ascending or descending order) if applicable for this index
implementation.
Params:
sortedInsertMode – the new value/**
     * Enable or disable the 'sorted insert' optimizations (rows are inserted in
     * ascending or descending order) if applicable for this index
     * implementation.
     *
     * @param sortedInsertMode the new value
     */
    void setSortedInsertMode(boolean sortedInsertMode);

    
Creates new lookup batch. Note that returned IndexLookupBatch instance can be used multiple times. 
Params:
filters – the table filters
filter – the filter index (0, 1,...)
Returns:
created batch or null if batched lookup is not supported by this index./**
     * Creates new lookup batch. Note that returned {@link IndexLookupBatch}
     * instance can be used multiple times.
     *
     * @param filters the table filters
     * @param filter the filter index (0, 1,...)
     * @return created batch or {@code null} if batched lookup is not supported
     *         by this index.
     */
    IndexLookupBatch createLookupBatch(TableFilter[] filters, int filter);
}