jetbrains.exodus.entitystore

Interface EntityIterable

All Superinterfaces:

java.lang.Iterable<Entity>

public interface EntityIterable
extends java.lang.Iterable<Entity>

EntityIterable allows to lazily iterate over entities. It's a result of all StoreTransaction methods that query, sort and filter entities.

EntityIterable is valid only against particular database snapshot, so finishing transaction (commit() or abort) or moving it to the newest snapshot (flush() or revert()) breaks iteration.

See Also:

StoreTransaction, EntityIterator, Entity

Method Summary

Modifier and Type	Method and Description
@NotNull EntityIterable	asSortResult() Marks this EntityIterable as sort result, so built-in sort engine can recognize custom sorting for stable sorting.
@NotNull EntityIterable	concat(@NotNull EntityIterable right) Returns concatenation of this EntityIterable and the right EntityIterable.
boolean	contains(@NotNull Entity entity) Returns true if the EntityIterable contains specified entity.
long	count() Returns the number of entities in the EntityIterable, or -1 if it cannot be calculated immediately.
@NotNull EntityIterable	distinct()
@Nullable Entity	getFirst()
@Nullable Entity	getLast()
long	getRoughCount() Returns rough number of entities in the EntityIterable, or -1 if the size of the EntityIterable was never calculated.
long	getRoughSize() Returns the same value as getRoughCount(), but in the worst case it returns size() instead of -1.
@NotNull StoreTransaction	getTransaction()
int	indexOf(@NotNull Entity entity) Returns index of specified entity in the EntityIterable, or -1 if there is no such entity.
@NotNull EntityIterable	intersect(@NotNull EntityIterable right) Returns intersection of this EntityIterable and the right EntityIterable.
@NotNull EntityIterable	intersectSavingOrder(@NotNull EntityIterable right) Returns same result as intersect(EntityIterable), but also guarantees that the order in the result corresponds to the order of the right EntityIterable.
boolean	isEmpty()
boolean	isSortResult() Custom sorting algorithms can mark their results as sort results.
EntityIterator	iterator() Creates new instance of EntityIterator.
@NotNull EntityIterable	minus(@NotNull EntityIterable right) Returns relative complement of the right EntityIterable in this EntityIterable, i.e.
@NotNull EntityIterable	reverse()
@NotNull EntityIterable	selectDistinct(@NotNull java.lang.String linkName) Returns entities which the source entities (this EntityIterable) are linked with by the link with specified name.
@NotNull EntityIterable	selectManyDistinct(@NotNull java.lang.String linkName) Returns entities which the source entities (this EntityIterable) are linked with by the link with specified name.
long	size() Returns the number of entities in the EntityIterable.
@NotNull EntityIterable	skip(int number) Returns EntityIterable that skips specified number of entities from the beginning of this EntityIterable.
@NotNull EntityIterable	take(int number) Returns EntityIterable that returns specified number of entities from this EntityIterable.
@NotNull EntityIterable	union(@NotNull EntityIterable right) Returns union of this EntityIterable and the right EntityIterable.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

iterator

EntityIterator iterator()

Creates new instance of EntityIterator.

Specified by:

iterator in interface java.lang.Iterable<Entity>

Returns:

new instance of EntityIterator

See Also:

EntityIterator

getTransaction

@NotNull
@NotNull StoreTransaction getTransaction()

Returns:

StoreTransaction instance in which the EntityIterable was created

See Also:

StoreTransaction

isEmpty

boolean isEmpty()

Returns:

true if the EntityIterable has no elements

See Also:

size(), count(), getRoughCount(), getRoughSize()

size

long size()

Returns the number of entities in the EntityIterable. This method can be slow.

Returns:

the number of entities in the EntityIterable

See Also:

isEmpty(), count(), getRoughCount(), getRoughSize()

count

long count()

Returns the number of entities in the EntityIterable, or -1 if it cannot be calculated immediately. If it returns -1, it starts background calculation of size(), so deferred call to this method should eventually return a value different from -1 and equal to size().

Returns:

the number of entities in the EntityIterable, or -1 if it cannot be calculated immediately

See Also:

isEmpty(), size(), getRoughCount(), getRoughSize()

getRoughCount

long getRoughCount()

Returns rough number of entities in the EntityIterable, or -1 if the size of the EntityIterable was never calculated. In other words, it returns the same value as size() if it can be calculated immediately, or last known size, or -1 in the worst case. This method is eventually consistent, i.e. its result (different form -1) can differ from result of size() and count().

Returns:

rough number of entities in the EntityIterable

See Also:

isEmpty(), size(), count(), getRoughSize()

getRoughSize

long getRoughSize()

Returns the same value as getRoughCount(), but in the worst case it returns size() instead of -1. So it never returns -1, but it is still eventually consistent as its result can differ from the result of size().

Returns:

rough number of entities in the EntityIterable

See Also:

isEmpty(), size(), count(), getRoughCount()

indexOf

int indexOf(@NotNull
            @NotNull Entity entity)

Returns index of specified entity in the EntityIterable, or -1 if there is no such entity. The index can be defined as follows: if int i = indexOf(entity) and i is not equal to -1 then the value of skip(i).getFirst() should be not-null and equal to entity.

Parameters:

entity - entity to search for

Returns:

index of an entity in the EntityIterable, or -1 if there is no such entity

See Also:

contains(Entity)

contains

boolean contains(@NotNull
                 @NotNull Entity entity)

Returns true if the EntityIterable contains specified entity. In short, it just returns value of indexOf(entity) != -1.

Parameters:

entity - entity whose presence in the EntityIterable is to be tested

Returns:

true if the EntityIterable contains specified entity

See Also:

indexOf(Entity)

intersect

@NotNull
@NotNull EntityIterable intersect(@NotNull
                                            @NotNull EntityIterable right)

Returns intersection of this EntityIterable and the right EntityIterable.

Parameters:

right - EntityIterable that should be intersected with this EntityIterable

Returns:

intersected EntityIterable

See Also:

union(EntityIterable), minus(EntityIterable), concat(EntityIterable)

intersectSavingOrder

@NotNull
@NotNull EntityIterable intersectSavingOrder(@NotNull
                                                       @NotNull EntityIterable right)

Returns same result as intersect(EntityIterable), but also guarantees that the order in the result corresponds to the order of the right EntityIterable.

Parameters:

right - EntityIterable which order is preserved in the result

Returns:

intersected EntityIterable

See Also:

intersect(EntityIterable)

union

@NotNull
@NotNull EntityIterable union(@NotNull
                                        @NotNull EntityIterable right)

Returns union of this EntityIterable and the right EntityIterable.

Parameters:

right - EntityIterable that should be joined with this EntityIterable

Returns:

joined EntityIterable

See Also:

intersect(EntityIterable), minus(EntityIterable), concat(EntityIterable)

minus

@NotNull
@NotNull EntityIterable minus(@NotNull
                                        @NotNull EntityIterable right)

Returns relative complement of the right EntityIterable in this EntityIterable, i.e. set-theoretic difference of this EntityIterable and the right EntityIterable.

Parameters:

right - EntityIterable which entities will excluded (subtracted) from this EntityIterable

Returns:

relative complement of the right EntityIterable in this EntityIterable

See Also:

intersect(EntityIterable), union(EntityIterable), concat(EntityIterable)

concat

@NotNull
@NotNull EntityIterable concat(@NotNull
                                         @NotNull EntityIterable right)

Returns concatenation of this EntityIterable and the right EntityIterable. Unlike other binary operations, result can have duplicate entities.

Parameters:

right - EntityIterable that should be concatenated to this EntityIterable

Returns:

concatenated EntityIterable

See Also:

intersect(EntityIterable), union(EntityIterable), minus(EntityIterable)

skip

@NotNull
@NotNull EntityIterable skip(int number)

Returns EntityIterable that skips specified number of entities from the beginning of this EntityIterable.

Parameters:

number - entities to skip

Returns:

EntityIterable with the number of skipped entities

See Also:

take(int)

take

@NotNull
@NotNull EntityIterable take(int number)

Returns EntityIterable that returns specified number of entities from this EntityIterable.

Parameters:

number - number of entities

Returns:

EntityIterable with the number of entities

See Also:

skip(int)

distinct

@NotNull
@NotNull EntityIterable distinct()

Returns:

only distinct entities from this EntityIterable

selectDistinct

@NotNull
@NotNull EntityIterable selectDistinct(@NotNull
                                                 @NotNull java.lang.String linkName)

Returns entities which the source entities (this EntityIterable) are linked with by the link with specified name. In order words, if target = source.getLink(linkName) for each source from this EntityIterable, then target is a part of the result. It is implied that the link should be single, i.e. targets should be set using method Entity.setLink(String, Entity), so only one target for each source can be. Order of linked entities is undefined.

Parameters:

linkName - name of the link

Returns:

entities linked by the link

See Also:

Entity.getLink(String), Entity.setLink(String, Entity)

selectManyDistinct

@NotNull
@NotNull EntityIterable selectManyDistinct(@NotNull
                                                     @NotNull java.lang.String linkName)

Returns entities which the source entities (this EntityIterable) are linked with by the link with specified name. In order words, if targets = source.getLinks(linkName) for each source from this EntityIterable, then each target amongst targets is a part of the result. It is implied that the link can me multiple, i.e. targets can be set using any method updating links, Entity.setLink(String, Entity)or Entity.addLink(String, Entity), so there can be arbitrary number of targets for each source. Order of linked entities is undefined.

Parameters:

linkName - name of the link

Returns:

entities linked by the link

See Also:

Entity.getLink(String), Entity.addLink(String, Entity)

getFirst

@Nullable
@Nullable Entity getFirst()

Returns:

the first entity of the EntityIterable, or null is it is empty

getLast

@Nullable
@Nullable Entity getLast()

Returns:

the last entity of the EntityIterable, or null is it is empty

reverse

@NotNull
@NotNull EntityIterable reverse()

Returns:

the same entities as the EntityIterable returns, but in reverse order

isSortResult

boolean isSortResult()

Custom sorting algorithms can mark their results as sort results. Built-in sort engine recognizes intermediate results as sort results in order to make sorting stable when sorting by several fields, or even using custom sorting algorithms.

Returns:

true if this EntityIterable is a result of sorting

See Also:

asSortResult(), StoreTransaction.sort(String, String, EntityIterable, boolean), StoreTransaction.sortLinks(String, EntityIterable, boolean, String, EntityIterable), StoreTransaction.mergeSorted(List, Comparator)

asSortResult

@NotNull
@NotNull EntityIterable asSortResult()

Marks this EntityIterable as sort result, so built-in sort engine can recognize custom sorting for stable sorting. E.g., in the following sample custom sorting will be lost:

     final EntityIterable customSorting = myCustomSorting();
     return txn.sort("User", "loginTime", customSorting, true);
 

To fix it, just mark custom sorting result as sort result:

     final EntityIterable customSorting = myCustomSorting();
     return txn.sort("User", "loginTime", customSorting.asSortResult(), true);
 

Returns:

EntityIterable marked as sort result

See Also:

isSortResult(), StoreTransaction.sort(String, String, EntityIterable, boolean), StoreTransaction.sortLinks(String, EntityIterable, boolean, String, EntityIterable), StoreTransaction.mergeSorted(List, Comparator)