com.bigdata.service.ndx
Interface IScaleOutClientIndex

All Superinterfaces:

IAsynchronousWriteBufferFactory, IAutoboxBTree, IClientIndex, IIndex, IRangeQuery, ISimpleBTree, ISplitter

All Known Implementing Classes:

AbstractScaleOutClientIndexView, AbstractScaleOutClientIndexView2, ClientIndexView, ClientIndexViewRefactor

public interface IScaleOutClientIndex
extends IClientIndex, ISplitter, IAsynchronousWriteBufferFactory

A client-side view of a scale-out index.

Version:

$Id: IScaleOutClientIndex.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Field Summary

Fields inherited from interface com.bigdata.btree.IRangeQuery

ALL, CURSOR, DEFAULT, DELETED, FIXED_LENGTH_SUCCESSOR, KEYS, NONE, PARALLEL, READONLY, REMOVEALL, REVERSE, VALS

Method Summary

IDataService	getDataService(PartitionLocator pmd) Resolve the data service to which the index partition is mapped.
AbstractScaleOutFederation	getFederation() Return the object used to access the services in the connected federation.
AtomicInteger	getRecursionDepth() Return a ThreadLocal AtomicInteger whose value is the recursion depth of the current Thread.
Iterator<PartitionLocator>	locatorScan(long ts, byte[] fromKey, byte[] toKey, boolean reverseScan) Returns an iterator that will visit the PartitionLocators for the specified scale-out index key range.
void	staleLocator(long ts, PartitionLocator locator, StaleLocatorException cause) Notifies the client that a StaleLocatorException was received.

Methods inherited from interface com.bigdata.service.ndx.IClientIndex

getCounter, getName, getTimestamp

Methods inherited from interface com.bigdata.btree.IIndex

getCounters, getIndexMetadata, getResourceMetadata, submit, submit, submit

Methods inherited from interface com.bigdata.btree.ISimpleBTree

contains, insert, lookup, remove

Methods inherited from interface com.bigdata.btree.IAutoboxBTree

contains, insert, lookup, remove

Methods inherited from interface com.bigdata.btree.IRangeQuery

rangeCount, rangeCount, rangeCountExact, rangeCountExactWithDeleted, rangeIterator, rangeIterator, rangeIterator

Methods inherited from interface com.bigdata.service.ndx.ISplitter

splitKeys, splitKeys

Methods inherited from interface com.bigdata.service.ndx.IAsynchronousWriteBufferFactory

newWriteBuffer

Method Detail

getDataService

IDataService getDataService(PartitionLocator pmd)

Resolve the data service to which the index partition is mapped.

Parameters:

pmd - The index partition locator.

Returns:

The data service and never null.

Throws:

RuntimeException - if none of the data services identified in the index partition locator record could be discovered.

locatorScan

Iterator<PartitionLocator> locatorScan(long ts,
                                       byte[] fromKey,
                                       byte[] toKey,
                                       boolean reverseScan)

Returns an iterator that will visit the PartitionLocators for the specified scale-out index key range.

Parameters:

ts - The timestamp that will be used to visit the locators.

fromKey - The scale-out index first key that will be visited (inclusive). When null there is no lower bound.

toKey - The first scale-out index key that will NOT be visited (exclusive). When null there is no upper bound.

reverseScan - true if you need to visit the index partitions in reverse key order (this is done when the partitioned iterator is scanning backwards).

Returns:

The iterator. The value returned by ITuple.getValue() will be a serialized PartitionLocator object.

See Also:

AbstractScaleOutFederation.locatorScan(String, long, byte[], byte[], boolean)

staleLocator

void staleLocator(long ts,
                  PartitionLocator locator,
                  StaleLocatorException cause)

Notifies the client that a StaleLocatorException was received. The client will use this information to refresh the IMetadataIndex.

Parameters:

ts - The timestamp of the metadata index view from which the locator was obtained.

locator - The locator that was stale.

cause - The reason why the locator became stale (split, join, or move).

Throws:

RuntimeException - unless the timestamp given is ITx.UNISOLATED or ITx.READ_COMMITTED since stale locators do not occur for other views.

getRecursionDepth

AtomicInteger getRecursionDepth()

Return a ThreadLocal AtomicInteger whose value is the recursion depth of the current Thread. This is initially zero when the task is submitted by the application. The value incremented when a task results in a StaleLocatorException and is decremented when returning from the recursive handling of the StaleLocatorException.

The recursion depth is used:

1. to limit the #of retries due to StaleLocatorExceptions for a split of a task submitted by the application
2. to force execution of retried tasks in the caller's thread.

The latter point is critical - if the retry tasks are run in the client thread pool then all threads in the pool can rapidly become busy awaiting retry tasks with the result that the client is essentially deadlocked.

Returns:

The recursion depth.

getFederation

AbstractScaleOutFederation getFederation()

Return the object used to access the services in the connected federation.