com.bigdata.btree.proc

Interface IIndexProcedure<T>

All Superinterfaces:

IReadOnly, Serializable

All Known Subinterfaces:

IKeyArrayIndexProcedure<T>, IKeyRangeIndexProcedure<T>, IMutableRelationIndexWriteProcedure<T>, IParallelizableIndexProcedure<T>, ISimpleIndexProcedure<T>

All Known Implementing Classes:

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

public interface IIndexProcedure<T>
extends IReadOnly, 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).

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
T	apply(IIndex ndx) Run the procedure.

Methods inherited from interface com.bigdata.journal.IReadOnly

isReadOnly

Method Detail

apply

T 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.