com.bigdata.relation.accesspath
Interface IAccessPath<R>

Type Parameters:

R - The generic type of the [R]elation elements of the IRelation.

All Superinterfaces:

Iterable<R>

All Known Implementing Classes:

AbstractAccessPath, AccessPathFusedView, BackchainAccessPath, EmptyAccessPath, MagicAccessPath, SPOAccessPath

public interface IAccessPath<R>
extends Iterable<R>

An abstraction for efficient reads on an IRelation using the index selected by an IPredicate constraint. Like their iterator(), implementations of this interface are NOT required to be thread-safe. They are designed for a single-threaded consumer.

Version:

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

Author:

Bryan Thompson

Method Summary

IIndex	getIndex() The index selected for the access path.
IKeyOrder<R>	getKeyOrder() The order in which the elements will be visited.
IPredicate<R>	getPredicate() The constraints on the IAccessPath.
boolean	isEmpty() True iff the access path is empty (there are no matches for the IPredicate) This is more conclusive than #rangeCount() since you MAY have a non-zero range count when the key range is in fact empty (there may be "deleted" index entries within the key range).
IChunkedOrderedIterator<R>	iterator() An iterator visiting elements using the natural order of the index selected for the IPredicate.
IChunkedOrderedIterator<R>	iterator(int limit, int capacity) Deprecated. by iterator(long, long, int). Also, [limit] should have been a long, not an int.
IChunkedOrderedIterator<R>	iterator(long offset, long limit, int capacity) An iterator visiting elements using the natural order of the index selected for the IPredicate.
long	rangeCount(boolean exact) Return the maximum #of elements spanned by the IPredicate.
ITupleIterator<R>	rangeIterator() The raw iterator for traversing the selected index within the key range implied by IPredicate.
long	removeAll() Remove all elements selected by the IPredicate (optional operation).

Method Detail

getPredicate

IPredicate<R> getPredicate()

The constraints on the IAccessPath.

getKeyOrder

IKeyOrder<R> getKeyOrder()

The order in which the elements will be visited.

isEmpty

boolean isEmpty()

True iff the access path is empty (there are no matches for the IPredicate) This is more conclusive than #rangeCount() since you MAY have a non-zero range count when the key range is in fact empty (there may be "deleted" index entries within the key range).

rangeCount

long rangeCount(boolean exact)

Return the maximum #of elements spanned by the IPredicate.

Parameters:

exact - When true, the result will be an exact count and may require a key-range scan. When false, the result will be an upper bound IFF delete markers are provisioned for the backing index (delete markers are required for transactions and for scale-out indices).

See Also:

IRangeQuery

getIndex

IIndex getIndex()

The index selected for the access path.

Note: The access path may incorporate additional constraints from the specified IPredicate that are not present on the IIndex returned by this method.

rangeIterator

ITupleIterator<R> rangeIterator()

The raw iterator for traversing the selected index within the key range implied by IPredicate.

Note: The access path may incorporate additional constraints from the specified IPredicate that are not present on the raw ITupleIterator returned by this method.

iterator

IChunkedOrderedIterator<R> iterator()

An iterator visiting elements using the natural order of the index selected for the IPredicate. This is equivalent to

 iterator(0L, 0L, 0)
 

since an offset of ZERO (0L) means no offset, a limit of ZERO (0L) means no limit and a capacity of ZERO (0) means whatever is the default capacity.

Note: Filters should be specified when the IAccessPath is constructed so that they will be evaluated on the IDataService rather than materializing the elements and then filtering then. This can be accomplished by adding the filter as an IElementFilter on the IPredicate when requesting IAccessPath.

Specified by:

iterator in interface Iterable<R>

Returns:

The iterator.

See Also:

IRelation.getAccessPath(IPredicate)

iterator

IChunkedOrderedIterator<R> iterator(int limit,
                                    int capacity)

Deprecated. by iterator(long, long, int). Also, [limit] should have been a long, not an int.

An iterator visiting elements using the natural order of the index selected for the IPredicate.

Parameters:

limit - The maximum #of elements that will be visited -or- ZERO (0) if there is no limit.

capacity - The maximum capacity for the buffer used by the iterator. When ZERO(0), a default capacity will be used. When a limit is specified, the capacity will never exceed the limit.

Returns:

The iterator.

iterator

IChunkedOrderedIterator<R> iterator(long offset,
                                    long limit,
                                    int capacity)

An iterator visiting elements using the natural order of the index selected for the IPredicate.

The offset and limit together describe an optional slice that will be visited by the iterator. When a slice is specified, the iterator will count off the elements accepted by the IPredicate up to the offset, but not materialize them. Elements by the IPredicate starting with the offset and up to (but not including) offset+limit will be materialized for the client. The iterator will halt processing after observing offset+limit accepted elements. Note that slices for JOINs (vs a simple IAccessPath scan) are handled by IQueryOptions for an IRule.

The meaning of "accepted" is that: (a) the elements lie in the key-range constraint implied by the IPredicate; and (b) the elements pass any optional constraints that the IPredicate imposes.

Parameters:

offset - The first element accepted by the iterator that it will visit (materialize for the client). The offset must be non-negative. This is ZERO (0L) to visit all accepted elements.

limit - The last element accepted by the iterator that it will visit (materialize for the client). The limit must be non-negative. This is ZERO (0L) to visit all accepted elements (the value Long.MAX_VALUE is interpreted exactly like ZERO(0L)).

capacity - The maximum capacity for the buffer used by the iterator. When ZERO(0), a default capacity will be used. When a limit is specified, the capacity will never exceed the limit.

Returns:

The iterator. FIXME The offset and limit should probably be rolled into the predicate and removed from the IAccessPath. This way they will be correctly applied when isEmpty() is implemented using the iterator() to determine if any elements can be visited.

removeAll

long removeAll()

Remove all elements selected by the IPredicate (optional operation).

Returns:

The #of elements that were removed.