IndexCursorImpl.java
/*
Copyright (c) 2011 James Ahlborn
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package com.healthmarketscience.jackcess.impl;
import java.io.IOException;
import java.util.Collection;
import java.util.HashSet;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
import com.healthmarketscience.jackcess.Index;
import com.healthmarketscience.jackcess.IndexCursor;
import com.healthmarketscience.jackcess.Row;
import com.healthmarketscience.jackcess.RuntimeIOException;
import com.healthmarketscience.jackcess.impl.TableImpl.RowState;
import com.healthmarketscience.jackcess.util.CaseInsensitiveColumnMatcher;
import com.healthmarketscience.jackcess.util.ColumnMatcher;
import com.healthmarketscience.jackcess.util.EntryIterableBuilder;
import com.healthmarketscience.jackcess.util.SimpleColumnMatcher;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
* Cursor backed by an index with extended traversal options.
*
* @author James Ahlborn
*/
public class IndexCursorImpl extends CursorImpl implements IndexCursor
{
private static final Log LOG = LogFactory.getLog(IndexCursorImpl.class);
/** IndexDirHandler for forward traversal */
private final IndexDirHandler _forwardDirHandler =
new ForwardIndexDirHandler();
/** IndexDirHandler for backward traversal */
private final IndexDirHandler _reverseDirHandler =
new ReverseIndexDirHandler();
/** logical index which this cursor is using */
private final IndexImpl _index;
/** Cursor over the entries of the relevant index */
private final IndexData.EntryCursor _entryCursor;
/** column names for the index entry columns */
private Set<String> _indexEntryPattern;
private IndexCursorImpl(TableImpl table, IndexImpl index,
IndexData.EntryCursor entryCursor)
throws IOException
{
super(new IdImpl(table, index), table,
new IndexPosition(entryCursor.getFirstEntry()),
new IndexPosition(entryCursor.getLastEntry()));
_index = index;
_index.initialize();
_entryCursor = entryCursor;
}
/**
* Creates an indexed cursor for the given table, narrowed to the given
* range.
* <p>
* Note, index based table traversal may not include all rows, as certain
* types of indexes do not include all entries (namely, some indexes ignore
* null entries, see {@link Index#shouldIgnoreNulls}).
*
* @param table the table over which this cursor will traverse
* @param index index for the table which will define traversal order as
* well as enhance certain lookups
* @param startRow the first row of data for the cursor, or {@code null} for
* the first entry
* @param startInclusive whether or not startRow is inclusive or exclusive
* @param endRow the last row of data for the cursor, or {@code null} for
* the last entry
* @param endInclusive whether or not endRow is inclusive or exclusive
*/
public static IndexCursorImpl createCursor(TableImpl table, IndexImpl index,
Object[] startRow,
boolean startInclusive,
Object[] endRow,
boolean endInclusive)
throws IOException
{
if(table != index.getTable()) {
throw new IllegalArgumentException(
"Given index is not for given table: " + index + ", " + table);
}
if(index.getIndexData().getUnsupportedReason() != null) {
throw new IllegalArgumentException(
"Given index " + index +
" is not usable for indexed lookups due to " +
index.getIndexData().getUnsupportedReason());
}
IndexCursorImpl cursor = new IndexCursorImpl(
table, index, index.cursor(startRow, startInclusive,
endRow, endInclusive));
// init the column matcher appropriately for the index type
cursor.setColumnMatcher(null);
return cursor;
}
private Set<String> getIndexEntryPattern()
{
if(_indexEntryPattern == null) {
// init our set of index column names
_indexEntryPattern = new HashSet<String>();
for(IndexData.ColumnDescriptor col : getIndex().getColumns()) {
_indexEntryPattern.add(col.getName());
}
}
return _indexEntryPattern;
}
@Override
public IndexImpl getIndex() {
return _index;
}
@Override
public Row findRowByEntry(Object... entryValues)
throws IOException
{
if(findFirstRowByEntry(entryValues)) {
return getCurrentRow();
}
return null;
}
@Override
public boolean findFirstRowByEntry(Object... entryValues)
throws IOException
{
PositionImpl curPos = _curPos;
PositionImpl prevPos = _prevPos;
boolean found = false;
try {
found = findFirstRowByEntryImpl(toRowValues(entryValues), true,
_columnMatcher);
return found;
} finally {
if(!found) {
try {
restorePosition(curPos, prevPos);
} catch(IOException e) {
LOG.error("Failed restoring position", e);
}
}
}
}
@Override
public void findClosestRowByEntry(Object... entryValues)
throws IOException
{
PositionImpl curPos = _curPos;
PositionImpl prevPos = _prevPos;
boolean found = false;
try {
findFirstRowByEntryImpl(toRowValues(entryValues), false,
_columnMatcher);
found = true;
} finally {
if(!found) {
try {
restorePosition(curPos, prevPos);
} catch(IOException e) {
LOG.error("Failed restoring position", e);
}
}
}
}
@Override
public boolean currentRowMatchesEntry(Object... entryValues)
throws IOException
{
return currentRowMatchesEntryImpl(toRowValues(entryValues), _columnMatcher);
}
@Override
public EntryIterableBuilder newEntryIterable(Object... entryValues) {
return new EntryIterableBuilder(this, entryValues);
}
public Iterator<Row> entryIterator(EntryIterableBuilder iterBuilder) {
return new EntryIterator(iterBuilder.getColumnNames(),
toRowValues(iterBuilder.getEntryValues()),
iterBuilder.getColumnMatcher());
}
@Override
protected IndexDirHandler getDirHandler(boolean moveForward) {
return (moveForward ? _forwardDirHandler : _reverseDirHandler);
}
@Override
protected boolean isUpToDate() {
return(super.isUpToDate() && _entryCursor.isUpToDate());
}
@Override
protected void reset(boolean moveForward) {
_entryCursor.reset(moveForward);
super.reset(moveForward);
}
@Override
protected void restorePositionImpl(PositionImpl curPos, PositionImpl prevPos)
throws IOException
{
if(!(curPos instanceof IndexPosition) ||
!(prevPos instanceof IndexPosition)) {
throw new IllegalArgumentException(
"Restored positions must be index positions");
}
_entryCursor.restorePosition(((IndexPosition)curPos).getEntry(),
((IndexPosition)prevPos).getEntry());
super.restorePositionImpl(curPos, prevPos);
}
@Override
protected PositionImpl getRowPosition(RowIdImpl rowId) throws IOException
{
// we need to get the index entry which corresponds with this row
Row row = getTable().getRow(getRowState(), rowId, getIndexEntryPattern());
_entryCursor.beforeEntry(getTable().asRow(row));
return new IndexPosition(_entryCursor.getNextEntry());
}
@Override
protected boolean findAnotherRowImpl(
ColumnImpl columnPattern, Object valuePattern, boolean moveForward,
ColumnMatcher columnMatcher, Object searchInfo)
throws IOException
{
Object[] rowValues = (Object[])searchInfo;
if((rowValues == null) || !isAtBeginning(moveForward)) {
// use the default table scan if we don't have index data or we are
// mid-cursor
return super.findAnotherRowImpl(columnPattern, valuePattern, moveForward,
columnMatcher, rowValues);
}
// sweet, we can use our index
if(!findPotentialRow(rowValues, true)) {
return false;
}
// either we found a row with the given value, or none exist in the table
return currentRowMatchesImpl(columnPattern, valuePattern, columnMatcher);
}
/**
* Moves to the first row (as defined by the cursor) where the index entries
* match the given values. Caller manages save/restore on failure.
*
* @param rowValues the column values built from the index column values
* @param requireMatch whether or not an exact match is desired
* @return {@code true} if a valid row was found with the given values,
* {@code false} if no row was found
*/
protected boolean findFirstRowByEntryImpl(Object[] rowValues,
boolean requireMatch,
ColumnMatcher columnMatcher)
throws IOException
{
if(!findPotentialRow(rowValues, requireMatch)) {
return false;
} else if(!requireMatch) {
// nothing more to do, we have moved to the closest row
return true;
}
return currentRowMatchesEntryImpl(rowValues, columnMatcher);
}
@Override
protected boolean findAnotherRowImpl(
Map<String,?> rowPattern, boolean moveForward,
ColumnMatcher columnMatcher, Object searchInfo)
throws IOException
{
Object[] rowValues = (Object[])searchInfo;
if((rowValues == null) || !isAtBeginning(moveForward)) {
// use the default table scan if we don't have index data or we are
// mid-cursor
return super.findAnotherRowImpl(rowPattern, moveForward, columnMatcher,
rowValues);
}
// sweet, we can use our index
if(!findPotentialRow(rowValues, true)) {
// at end of index, no potential matches
return false;
}
// determine if the pattern columns exactly match the index columns
boolean exactColumnMatch = rowPattern.keySet().equals(
getIndexEntryPattern());
// there may be multiple rows which fit the pattern subset used by
// the index, so we need to keep checking until our index values no
// longer match
do {
if(!currentRowMatchesEntryImpl(rowValues, columnMatcher)) {
// there are no more rows which could possibly match
break;
}
// note, if exactColumnMatch, no need to do an extra comparison with the
// current row (since the entry match check above is equivalent to this
// check)
if(exactColumnMatch || currentRowMatchesImpl(rowPattern, columnMatcher)) {
// found it!
return true;
}
} while(moveToAnotherRow(moveForward));
// none of the potential rows matched
return false;
}
private boolean currentRowMatchesEntryImpl(Object[] rowValues,
ColumnMatcher columnMatcher)
throws IOException
{
// check the next row to see if it actually matches
Row row = getCurrentRow(getIndexEntryPattern());
for(IndexData.ColumnDescriptor col : getIndex().getColumns()) {
Object patValue = rowValues[col.getColumnIndex()];
if((patValue == IndexData.MIN_VALUE) ||
(patValue == IndexData.MAX_VALUE)) {
// all remaining entry values are "special" (used for partial lookups)
return true;
}
String columnName = col.getName();
Object rowValue = row.get(columnName);
if(!columnMatcher.matches(getTable(), columnName, patValue, rowValue)) {
return false;
}
}
return true;
}
private boolean findPotentialRow(Object[] rowValues, boolean requireMatch)
throws IOException
{
_entryCursor.beforeEntry(rowValues);
IndexData.Entry startEntry = _entryCursor.getNextEntry();
if(requireMatch && !startEntry.getRowId().isValid()) {
// at end of index, no potential matches
return false;
}
// move to position and check it out
restorePosition(new IndexPosition(startEntry));
return true;
}
@Override
protected Object prepareSearchInfo(ColumnImpl columnPattern, Object valuePattern)
{
// attempt to generate a lookup row for this index
return _entryCursor.getIndexData().constructPartialIndexRow(
IndexData.MIN_VALUE, columnPattern.getName(), valuePattern);
}
@Override
protected Object prepareSearchInfo(Map<String,?> rowPattern)
{
// attempt to generate a lookup row for this index
return _entryCursor.getIndexData().constructPartialIndexRow(
IndexData.MIN_VALUE, rowPattern);
}
@Override
protected boolean keepSearching(ColumnMatcher columnMatcher,
Object searchInfo)
throws IOException
{
if(searchInfo instanceof Object[]) {
// if we have a lookup row for this index, then we only need to continue
// searching while we are looking at rows which match the index lookup
// value(s). once we move past those rows, no other rows could possibly
// match.
return currentRowMatchesEntryImpl((Object[])searchInfo, columnMatcher);
}
// we are doing a full table scan
return true;
}
private Object[] toRowValues(Object[] entryValues)
{
return _entryCursor.getIndexData().constructPartialIndexRowFromEntry(
IndexData.MIN_VALUE, entryValues);
}
@Override
protected PositionImpl findAnotherPosition(
RowState rowState, PositionImpl curPos, boolean moveForward)
throws IOException
{
IndexDirHandler handler = getDirHandler(moveForward);
IndexPosition endPos = (IndexPosition)handler.getEndPosition();
IndexData.Entry entry = handler.getAnotherEntry();
return ((!entry.equals(endPos.getEntry())) ?
new IndexPosition(entry) : endPos);
}
@Override
protected ColumnMatcher getDefaultColumnMatcher() {
if(getIndex().isUnique()) {
// text indexes are case-insensitive, therefore we should always use a
// case-insensitive matcher for unique indexes.
return CaseInsensitiveColumnMatcher.INSTANCE;
}
return SimpleColumnMatcher.INSTANCE;
}
/**
* Handles moving the table index cursor in a given direction. Separates
* cursor logic from value storage.
*/
private abstract class IndexDirHandler extends DirHandler {
public abstract IndexData.Entry getAnotherEntry()
throws IOException;
}
/**
* Handles moving the table index cursor forward.
*/
private final class ForwardIndexDirHandler extends IndexDirHandler {
@Override
public PositionImpl getBeginningPosition() {
return getFirstPosition();
}
@Override
public PositionImpl getEndPosition() {
return getLastPosition();
}
@Override
public IndexData.Entry getAnotherEntry() throws IOException {
return _entryCursor.getNextEntry();
}
}
/**
* Handles moving the table index cursor backward.
*/
private final class ReverseIndexDirHandler extends IndexDirHandler {
@Override
public PositionImpl getBeginningPosition() {
return getLastPosition();
}
@Override
public PositionImpl getEndPosition() {
return getFirstPosition();
}
@Override
public IndexData.Entry getAnotherEntry() throws IOException {
return _entryCursor.getPreviousEntry();
}
}
/**
* Value object which maintains the current position of an IndexCursor.
*/
private static final class IndexPosition extends PositionImpl
{
private final IndexData.Entry _entry;
private IndexPosition(IndexData.Entry entry) {
_entry = entry;
}
@Override
public RowIdImpl getRowId() {
return getEntry().getRowId();
}
public IndexData.Entry getEntry() {
return _entry;
}
@Override
protected boolean equalsImpl(Object o) {
return getEntry().equals(((IndexPosition)o).getEntry());
}
@Override
public String toString() {
return "Entry = " + getEntry();
}
}
/**
* Row iterator (by matching entry) for this cursor, modifiable.
*/
private final class EntryIterator extends BaseIterator
{
private final Object[] _rowValues;
private EntryIterator(Collection<String> columnNames, Object[] rowValues,
ColumnMatcher columnMatcher)
{
super(columnNames, false, MOVE_FORWARD, columnMatcher);
_rowValues = rowValues;
try {
_hasNext = findFirstRowByEntryImpl(rowValues, true, _columnMatcher);
_validRow = _hasNext;
} catch(IOException e) {
throw new RuntimeIOException(e);
}
}
@Override
protected boolean findNext() throws IOException {
return (moveToNextRow() &&
currentRowMatchesEntryImpl(_rowValues, _colMatcher));
}
}
}