package com.akiban.cserver.store;

import java.util.List;

import com.akiban.cserver.RowData;
import com.akiban.cserver.RowDefCache;

/**
 * An abstraction for a layer that stores and retrieves data
 * 
 * @author peter
 * 
 */
public interface Store {

	void startUp() throws Exception;

	void shutDown() throws Exception;

	RowDefCache getRowDefCache();

	boolean isVerbose();

	void setVerbose(final boolean verbose);

	RowCollector getCurrentRowCollector();

	int writeRow(final RowData rowData) throws Exception;

	int deleteRow(final RowData rowData) throws Exception;

	int updateRow(final RowData oldRowData, final RowData newRowData)
			throws Exception;

	long getAutoIncrementValue(final int rowDefId) throws Exception;

	RowCollector newRowCollector(final int indexId, final RowData start,
			final RowData end, final byte[] columnBitMap) throws Exception;

	long getRowCount(final boolean exact, final RowData start,
			final RowData end, final byte[] columnBitMap) throws Exception;

	TableStatistics getTableStatistics(final int tableId) throws Exception;

	int dropTable(final int rowDefId) throws Exception;

	int truncateTable(final int rowDefId) throws Exception;

	int dropSchema(final String schemaName) throws Exception;

	void setOrdinals() throws Exception;

	/**
	 * <p>
	 * Fetch and return a List of RowData objects. This is a somewhat
	 * generalized interface to the core row-scanning logic suitable for
	 * object-level access by MemcacheD, for example. This method may returns
	 * rows of multiple types, depending on the parameters. For example, this
	 * method may be used to request a Customer by customer_id, along with all
	 * that customer's orders and order items.
	 * </p>
	 * 
	 * <p>
	 * The method supports selection from an index based on a range of values
	 * for one designated column. There must be an index on the specified
	 * column. Typically one would specify a primary key column and the PK index
	 * would be used, but any column with an index is permitted. The least and
	 * greatest values represent bounds on the column values in rows returned by
	 * this method; if least and greatest are the same then this method selects
	 * the all rows having that value; if the column specifies a unique index
	 * then just one matches.  For example, in the COI schema, if columnName="customer"
	 * and least and greatest are both equal to 123, then just the customer row
	 * for customer_id=123 is returned.
	 * </p>
	 * 
	 * <p>
	 * This method also supports selecting descendant rows from the specified
	 * table according the the natural join relationships inherent in the user
	 * table's group. The leafTableName controls this behavior. Specify:
	 * <dl>
	 * <dt>leafTableName = tableName</dt>
	 * <dd>to restrict the results to a single table</dd>
	 * <dt>leafTableName = childTableName</dt>
	 * <dd>to return rows from all tables in the group found on a path from
	 * tableName to childTableName. For example, in our COI schema specify
	 * tableName="customer" and leafTableName="order" to return customer row(s)
	 * plus all their contained orders.</dd>
	 * <dt>leafTableName = null</dt>
	 * <dd>for convenience, this method attempts to find a leaf table and
	 * follows the above logic with it. For example, with the COI schema,
	 * specifying leafTableName=null is equivalent to specifying
	 * leafTableName="item". In a "bushy" schema, like CAOI, the results are
	 * indeterminate.</dd>
	 * </p>
	 * 
	 * <p>
	 * The Object types for the least and greatest values should be chosen to
	 * match the data type of the column.  For numeric columns, use a numeric type
	 * (width does not matter: for example, you can specify Integer-valued least
	 * and greatest values for a BIGINT column), for date/timestamp/year columns specify
	 * java.util.Date, for char/varchar (and in some cases the blob-type columns),
	 * specify a String. For most common data types fetchRows can make the natural
	 * translation from a Java Object to the MySQL column value.
	 * </p>
	 * 
	 * @param schemaName
	 *            schema name
	 * @param tableName
	 *            table name - should be a user table, such as "Customer"
	 * @param columnName
	 *            column name on which index values are specified
	 * @param least
	 *            the low end of the retrieval range, inclusive for the column
	 *            specified by columnName.
	 * @param greatest
	 *            the high end of the retrieval range, inclusive, for the column
	 *            specified by columnName.
	 * @param leafTableName
	 *            optional user table name specifying the leafmost table to
	 *            retrieve from, e.g., "item" in the COI schema.
	 * @return
	 * @throws Exception
	 */
	List<RowData> fetchRows(final String schemaName, final String tableName,
			final String columnName, final Object least, final Object greatest,
			final String leafTableName) throws Exception;

}

@@ -1499,17 +1499,16 @@
 y return
-s
 %0A%09 * row
@@ -1682,20 +1682,20 @@
 ers and 
-orde
+thei
 r items.
@@ -2175,20 +2175,16 @@
 ects%0A%09 *
- the
  all row
@@ -2209,73 +2209,85 @@
 e; i
-f
+n
  the 
-column specifies a
+normal case that the index is
  unique
- index
+,
 %0A%09 * th
-en just one matches. 
+is will be at most one row.
  For
@@ -2317,16 +2317,20 @@
 hema, if
+%0A%09 *
  columnN
@@ -2343,20 +2343,16 @@
 ustomer%22
-%0A%09 *
  and lea
@@ -2394,16 +2394,20 @@
 23, then
+%0A%09 *
  just th
@@ -2420,20 +2420,16 @@
 omer row
-%0A%09 *
  for cus
@@ -2626,31 +2626,18 @@
 the 
-user%0A%09 * table's 
 group.
+%0A%09 *
  The
@@ -3427,24 +3427,34 @@
 inate.%3C/dd%3E%0A
+%09 * %3C/dl%3E%0A
 %09 * %3C/p%3E%0A%09 *
@@ -3576,17 +3576,16 @@
  column.
- 
  For num
@@ -3615,17 +3615,17 @@
 eric
+%0A%09 *
  type
-%0A%09 *
  (wi
@@ -3688,26 +3688,26 @@
 r-valued
+%0A%09 *
  least
-%0A%09 *
  and gre
@@ -3764,16 +3764,20 @@
 amp/year
+%0A%09 *
  columns
@@ -3784,20 +3784,16 @@
  specify
-%0A%09 *
  java.ut
@@ -3840,16 +3840,20 @@
 ases the
+%0A%09 *
  blob-ty
@@ -3864,20 +3864,16 @@
 olumns),
-%0A%09 *
  specify
@@ -3909,16 +3909,20 @@
 ta types
+%0A%09 *
  fetchRo
@@ -3944,20 +3944,16 @@
  natural
-%0A%09 *
  transla
@@ -3982,16 +3982,20 @@
 t to the
+%0A%09 *
  MySQL c

Improve documentation on fetchRows()