com.bigdata.btree.proc
Interface IIndexProcedure

All Superinterfaces:

Serializable

All Known Subinterfaces:

IKeyArrayIndexProcedure, IKeyRangeIndexProcedure, IMutableRelationIndexWriteProcedure, IParallelizableIndexProcedure, ISimpleIndexProcedure

All Known Implementing Classes:

AbstractAtomicRowReadOrWrite, AbstractIndexProcedure, AbstractKeyArrayIndexProcedure, AbstractKeyRangeIndexProcedure, AtomicBlockAppendProc, AtomicBlockWriteProc, AtomicRowDelete, AtomicRowRead, AtomicRowWriteRead, BatchContains, BatchInsert, BatchLookup, BatchRemove, BlobsWriteProc, Id2TermWriteProc, JustIndexWriteProc, RangeCountProcedure, SPOIndexWriteProc, Term2IdWriteProc, TextIndexWriteProc

public interface IIndexProcedure
extends Serializable

An arbitrary procedure run against a single index.

There is a fairly direct correspondence between map / reduce processing and the use of index procedures. The "map" phase corresponds to the IIndexProcedure while the "reduce" phase corresponds to the IResultHandler. The main difference is that index procedures operate on ordered data. IIndexProcedures MAY use IParallelizableIndexProcedure to declare that they can be executed in parallel when mapped across multiple index partitions - parallelization is handled automatically by ClientIndexView. Otherwise it is assumed that the procedure requires sequential execution as it is applied to the relevant index partition(s) - again this is handled automatically.

There are basically three kinds of index procedures, each of which determines where an index procedure will be mapped in a different manner:

A single key, byte[] key

Examples are when reading a logical row from a SparseRowStore or performing a datum ISimpleBTree#lookup(Object). These procedures are always directed to a single index partition. Since they are never mapped across index partitions, there is no "aggregation" phase. Likewise, there is no AbstractKeyArrayIndexProcedureConstructor since the procedure instance is always created directly by the application.

A key range, byte[] toKey, byte[] fromKey

Examples are IRangeQuery.rangeCount(byte[], byte[]) and IRangeQuery#rangeIterator(byte[], byte[]). Since the same data is sent to each index partition there is no requirement for an object to construct instances of these procedures. However, the procedures do need a means to combine or aggregate the results from each index partition. See {@link IKeyRangeIndexProcedure}.

A set of keys, byte[][] keys

Examples are {@link BatchInsert}, {@link BatchLookup}, etc. For this case the procedure is not only mapped across one or more index partitions, but the procedure's data must be split such that each index partition is sent only the data that is relevant to that index partition. See {@link IKeyArrayIndexProcedure}.

Note: this interface extends {@link Serializable}, however that provides only for communicating state to the {@link IDataService}. If an instance of this procedure will cross a network interface, then the implementation class MUST be available to the {@link IDataService} on which it will execute. This can be as simple as bundling the procedure into a JAR that is part of the CLASSPATH used to start a {@link DataService} or you can use downloaded code with the JINI codebase mechanism (java.rmi.server.codebase).

Version:

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

Author:

Bryan Thompson

TODO:

add generic type for apply(IIndex) 's return value (much like Callable).

Method Summary

Object	apply(IIndex ndx) Run the procedure.
boolean	isReadOnly() Return true iff the procedure asserts that it will not write on the index.

Method Detail

isReadOnly

boolean isReadOnly()

Return true iff the procedure asserts that it will not write on the index. When true, the procedure may be run against a view of the index that is read-only or which allows concurrent processes to read on the same index object. When false the procedure will be run against a mutable view of the index (assuming that the procedure is executed in a context that has access to a mutable index view).

apply

Object apply(IIndex ndx)

Run the procedure.

Note: Unisolated procedures have "auto-commit" ACID properties for a local index only. In order for a distributed procedure to be ACID, the procedure MUST be executed within a fully isolated transaction.

Parameters:

ndx - The index.

Returns:

The result, which is entirely defined by the procedure implementation and which MAY be null. In general, this MUST be Serializable since it may have to pass across a network interface.