Package ai.timefold.solver.core.impl.neighborhood.stream.enumerating.uni

Class AbstractUniEnumeratingStream<Solution_,A>

java.lang.Object

ai.timefold.solver.core.impl.neighborhood.stream.enumerating.common.AbstractEnumeratingStream<Solution_>

ai.timefold.solver.core.impl.neighborhood.stream.enumerating.uni.AbstractUniEnumeratingStream<Solution_,A>

All Implemented Interfaces:

BavetStream, EnumeratingStream, UniEnumeratingStream<Solution_,A>

Direct Known Subclasses:

AftBridgeUniEnumeratingStream, ForEachIncludingPinnedEnumeratingStream, ForeBridgeUniEnumeratingStream

@NullMarked
public abstract class AbstractUniEnumeratingStream<Solution_,A>
extends AbstractEnumeratingStream<Solution_>
implements UniEnumeratingStream<Solution_,A>

Field Summary

Fields inherited from class ai.timefold.solver.core.impl.neighborhood.stream.enumerating.common.AbstractEnumeratingStream

childStreamList, enumeratingStreamFactory, parent

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractUniEnumeratingStream(EnumeratingStreamFactory<Solution_> enumeratingStreamFactory)
protected	AbstractUniEnumeratingStream(EnumeratingStreamFactory<Solution_> enumeratingStreamFactory, @Nullable AbstractEnumeratingStream<Solution_> parent)

Method Summary

Modifier and Type	Method	Description
UniLeftDataset<Solution_,A>	createLeftDataset()
<Other_> UniRightDataset<Solution_,Other_,A>	createRightDataset(BiNeighborhoodsJoinerComber<Solution_,Other_,A> joinerComber)
AbstractUniEnumeratingStream<Solution_,A>	distinct()	Transforms the stream in such a way that all the tuples going through it are distinct.
final UniEnumeratingStream<Solution_,A>	filter(UniNeighborhoodsPredicate<Solution_,A> filter)	Exhaustively test each fact against the UniNeighborhoodsPredicate and match if UniNeighborhoodsPredicate.test(SolutionView, Object) returns true.
protected <GroupKey_> AbstractUniEnumeratingStream<Solution_,GroupKey_>	groupBy(Function<A,GroupKey_> groupKeyMapping)	Convert the UniEnumeratingStream to a different UniEnumeratingStream, containing the set of tuples resulting from applying the group key mapping function on all tuples of the original stream.
final <B> UniEnumeratingStream<Solution_,A>	ifExists(UniEnumeratingStream<Solution_,B> otherStream, BiNeighborhoodsJoiner<A,B>... joiners)	Create a new UniEnumeratingStream for every A where B exists for which all BiNeighborhoodsJoiners are true (for the properties it extracts from both facts).
final <B> UniEnumeratingStream<Solution_,A>	ifExists(Class<B> otherClass, BiNeighborhoodsJoiner<A,B>... joiners)	Create a new UniEnumeratingStream for every A where B exists for which all BiNeighborhoodsJoiners are true (for the properties they extract from both facts).
final <B> UniEnumeratingStream<Solution_,A>	ifNotExists(UniEnumeratingStream<Solution_,B> otherStream, BiNeighborhoodsJoiner<A,B>... joiners)	Create a new UniEnumeratingStream for every A where B does not exist for which the BiNeighborhoodsJoiners are true (for the properties they extract from both facts).
final <B> UniEnumeratingStream<Solution_,A>	ifNotExists(Class<B> otherClass, BiNeighborhoodsJoiner<A,B>... joiners)	Create a new UniEnumeratingStream for every A where B does not exist for which the BiNeighborhoodsJoiners are true (for the properties they extract from both facts).
<B> BiEnumeratingStream<Solution_,A,B>	join(UniEnumeratingStream<Solution_,B> otherStream, BiNeighborhoodsJoiner<A,B>... joiners)	Create a new BiEnumeratingStream for every combination of A and B for which the BiNeighborhoodsJoiner is true (for the properties it extracts from both facts).
<B> BiEnumeratingStream<Solution_,A,B>	join(Class<B> otherClass, BiNeighborhoodsJoiner<A,B>... joiners)	Create a new BiEnumeratingStream for every combination of A and B for which the BiNeighborhoodsJoiner is true (for the properties it extracts from both facts).
<ResultA_> UniEnumeratingStream<Solution_,ResultA_>	map(UniNeighborhoodsMapper<Solution_,A,ResultA_> mapping)	Transforms the stream in such a way that tuples are remapped using the given function.
<ResultA_, ResultB_> BiEnumeratingStream<Solution_,ResultA_,ResultB_>	map(UniNeighborhoodsMapper<Solution_,A,ResultA_> mappingA, UniNeighborhoodsMapper<Solution_,A,ResultB_> mappingB)	As defined by UniEnumeratingStream.map(UniNeighborhoodsMapper), only resulting in BiEnumeratingStream.

Methods inherited from class ai.timefold.solver.core.impl.neighborhood.stream.enumerating.common.AbstractEnumeratingStream

assertEmptyChildStreamList, buildNode, collectActiveEnumeratingStreams, getChildStreamList, getParent, getTupleSource, guaranteesDistinct, shareAndAddChild

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ai.timefold.solver.core.impl.bavet.common.BavetStream

getLocationSet

Methods inherited from interface ai.timefold.solver.core.preview.api.neighborhood.stream.enumerating.UniEnumeratingStream

ifExists, ifExists, ifExists, ifExists, ifExists, ifExists, ifExists, ifExists, ifExists, ifExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, ifNotExists, join, join, join, join, join, join, join, join, join, join

Constructor Details

AbstractUniEnumeratingStream

protected AbstractUniEnumeratingStream(EnumeratingStreamFactory<Solution_> enumeratingStreamFactory)

AbstractUniEnumeratingStream

protected AbstractUniEnumeratingStream(EnumeratingStreamFactory<Solution_> enumeratingStreamFactory,
 @Nullable AbstractEnumeratingStream<Solution_> parent)

Method Details

filter

public final UniEnumeratingStream<Solution_,A> filter(UniNeighborhoodsPredicate<Solution_,A> filter)

Description copied from interface: UniEnumeratingStream

Exhaustively test each fact against the UniNeighborhoodsPredicate and match if UniNeighborhoodsPredicate.test(SolutionView, Object) returns true.

Specified by:

filter in interface UniEnumeratingStream<Solution_,A>

join

public <B> BiEnumeratingStream<Solution_,A,B> join(UniEnumeratingStream<Solution_,B> otherStream,
 BiNeighborhoodsJoiner<A,B>... joiners)

Description copied from interface: UniEnumeratingStream

Create a new BiEnumeratingStream for every combination of A and B for which the BiNeighborhoodsJoiner is true (for the properties it extracts from both facts).

Important: Joining is faster and more scalable than a filter, because it applies hashing and/or indexing on the properties, so it doesn't create nor checks every combination of A and B.

Specified by:

join in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

B - the type of the second matched fact

Returns:

a stream that matches every combination of A and B for which the BiNeighborhoodsJoiner is true

join

public <B> BiEnumeratingStream<Solution_,A,B> join(Class<B> otherClass,
 BiNeighborhoodsJoiner<A,B>... joiners)

Description copied from interface: UniEnumeratingStream

Create a new BiEnumeratingStream for every combination of A and B for which the BiNeighborhoodsJoiner is true (for the properties it extracts from both facts). The stream will include all facts or entities of the given class, regardless of their pinning status.

Important: Joining is faster and more scalable than a filter, because it applies hashing and/or indexing on the properties, so it doesn't create nor checks every combination of A and B.

Specified by:

join in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

B - the type of the second matched fact

Returns:

a stream that matches every combination of A and B for which the BiNeighborhoodsJoiner is true

ifExists

@SafeVarargs
public final <B> UniEnumeratingStream<Solution_,A> ifExists(Class<B> otherClass,
 BiNeighborhoodsJoiner<A,B>... joiners)

Description copied from interface: UniEnumeratingStream

Create a new UniEnumeratingStream for every A where B exists for which all BiNeighborhoodsJoiners are true (for the properties they extract from both facts).

Specified by:

ifExists in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

B - the type of the second matched fact

Returns:

a stream that matches every A where B exists for which the BiNeighborhoodsJoiners are true

ifExists

@SafeVarargs
public final <B> UniEnumeratingStream<Solution_,A> ifExists(UniEnumeratingStream<Solution_,B> otherStream,
 BiNeighborhoodsJoiner<A,B>... joiners)

Description copied from interface: UniEnumeratingStream

Create a new UniEnumeratingStream for every A where B exists for which all BiNeighborhoodsJoiners are true (for the properties it extracts from both facts).

Specified by:

ifExists in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

B - the type of the second matched fact

Returns:

a stream that matches every A where B exists for which the BiNeighborhoodsJoiners are true

ifNotExists

@SafeVarargs
public final <B> UniEnumeratingStream<Solution_,A> ifNotExists(Class<B> otherClass,
 BiNeighborhoodsJoiner<A,B>... joiners)

Description copied from interface: UniEnumeratingStream

Create a new UniEnumeratingStream for every A where B does not exist for which the BiNeighborhoodsJoiners are true (for the properties they extract from both facts).

Specified by:

ifNotExists in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

B - the type of the second matched fact

Returns:

a stream that matches every A where B does not exist for which the BiNeighborhoodsJoiners are true

ifNotExists

@SafeVarargs
public final <B> UniEnumeratingStream<Solution_,A> ifNotExists(UniEnumeratingStream<Solution_,B> otherStream,
 BiNeighborhoodsJoiner<A,B>... joiners)

Description copied from interface: UniEnumeratingStream

Create a new UniEnumeratingStream for every A where B does not exist for which the BiNeighborhoodsJoiners are true (for the properties they extract from both facts).

Specified by:

ifNotExists in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

B - the type of the second matched fact

Returns:

a stream that matches every A where B does not exist for which the BiNeighborhoodsJoiners are true

groupBy

protected <GroupKey_>
AbstractUniEnumeratingStream<Solution_,GroupKey_> groupBy(Function<A,GroupKey_> groupKeyMapping)

Convert the UniEnumeratingStream to a different UniEnumeratingStream, containing the set of tuples resulting from applying the group key mapping function on all tuples of the original stream. Neither tuple of the new stream Objects.equals(Object, Object) any other.

Type Parameters:

GroupKey_ - the type of a fact in the destination UniEnumeratingStream's tuple; must honor the general contract of hashCode.

Parameters:

groupKeyMapping - mapping function to convert each element in the stream to a different element

map

public <ResultA_>
UniEnumeratingStream<Solution_,ResultA_> map(UniNeighborhoodsMapper<Solution_,A,ResultA_> mapping)

Description copied from interface: UniEnumeratingStream

Transforms the stream in such a way that tuples are remapped using the given function. This may produce a stream with duplicate tuples. See UniEnumeratingStream.distinct() for details.

There are several recommendations for implementing the mapping function:

• Purity. The mapping function should only depend on its input. That is, given the same input, it always returns the same output.
• Bijectivity. No two input tuples should map to the same output tuple, or to tuples that are equal. Not following this recommendation creates a enumerating stream with duplicate tuples, and may force you to use UniEnumeratingStream.distinct() later, which comes at a performance cost.
• Immutable data carriers. The objects returned by the mapping function should be identified by their contents and nothing else. If two of them have contents which equal, then they should likewise equal and preferably be the same instance. The objects returned by the mapping function should also be immutable, meaning their contents should not be allowed to change.

Simple example: assuming a enumerating stream of tuples of Persons [Ann(age = 20), Beth(age = 25), Cathy(age = 30)], calling map(Person::getAge) on such stream will produce a stream of Integers [20, 25, 30],

Example with a non-bijective mapping function: assuming a enumerating stream of tuples of Persons [Ann(age = 20), Beth(age = 25), Cathy(age = 30), David(age = 30), Eric(age = 20)], calling map(Person::getAge) on such stream will produce a stream of Integers [20, 25, 30, 30, 20].

Use with caution, as the increased memory allocation rates coming from tuple creation may negatively affect performance.

Specified by:

map in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

ResultA_ - the type of the only fact in the resulting UniEnumeratingStream's tuple

Parameters:

mapping - function to convert the original tuple into the new tuple

map

public <ResultA_,
ResultB_>
BiEnumeratingStream<Solution_,ResultA_,ResultB_> map(UniNeighborhoodsMapper<Solution_,A,ResultA_> mappingA,
 UniNeighborhoodsMapper<Solution_,A,ResultB_> mappingB)

Description copied from interface: UniEnumeratingStream

As defined by UniEnumeratingStream.map(UniNeighborhoodsMapper), only resulting in BiEnumeratingStream.

Specified by:

map in interface UniEnumeratingStream<Solution_,A>

Type Parameters:

ResultA_ - the type of the first fact in the resulting BiEnumeratingStream's tuple

ResultB_ - the type of the first fact in the resulting BiEnumeratingStream's tuple

Parameters:

mappingA - function to convert the original tuple into the first fact of a new tuple

mappingB - function to convert the original tuple into the second fact of a new tuple

distinct

public AbstractUniEnumeratingStream<Solution_,A> distinct()

Description copied from interface: UniEnumeratingStream

Transforms the stream in such a way that all the tuples going through it are distinct. (No two tuples will equal.)

By default, tuples going through an enumerating stream are distinct. However, operations such as UniEnumeratingStream.map(UniNeighborhoodsMapper) may create a stream which breaks that promise. By calling this method on such a stream, duplicate copies of the same tuple will be omitted at a performance cost.

Specified by:

distinct in interface UniEnumeratingStream<Solution_,A>

createLeftDataset

public UniLeftDataset<Solution_,A> createLeftDataset()

createRightDataset

public <Other_> UniRightDataset<Solution_,Other_,A> createRightDataset(BiNeighborhoodsJoinerComber<Solution_,Other_,A> joinerComber)