Package org.optaplanner.core.api.score.stream

Interface ConstraintStream

All Known Subinterfaces:
BiConstraintStream<A,B>, QuadConstraintStream<A,B,C,D>, TriConstraintStream<A,B,C>, UniConstraintStream<A>
public interface ConstraintStream
A constraint stream is a declaration on how to match one, two or more objects. Constraint streams are similar to a declaration of a JDK Stream or an SQL query, but they support incremental score calculation and SolutionManager.explain(Object) score justification}.

An object that passes through constraint streams is called a fact. It's either a problem fact or a planning entity.

A constraint stream is typically created with ConstraintFactory.forEach(Class) or UniConstraintStream.join(UniConstraintStream, BiJoiner) by joining another constraint stream}. Constraint streams form a directed, non-cyclic graph, with multiple start nodes (which listen to fact changes) and one end node per Constraint (which affect the Score).

Throughout this documentation, we will be using the following terminology:

Constraint Stream
A chain of different operations, originated by ConstraintFactory.forEach(Class) (or similar methods) and terminated by a penalization or reward operation.
Operation
Operations (implementations of ConstraintStream) are parts of a constraint stream which mutate it. They may remove tuples from further evaluation, expand or contract streams. Every constraint stream has a terminal operation, which is either a penalization or a reward.
Fact
Object instance entering the constraint stream.
Genuine Fact
Fact that enters the constraint stream either through a from(...) call or through a join(...) call. Genuine facts are either planning entities (see PlanningEntity) or problem facts (see ProblemFactProperty or ProblemFactCollectionProperty).
Inferred Fact
Fact that enters the constraint stream through a computation. This would typically happen through an operation such as groupBy(...).
Tuple
A collection of facts that the constraint stream operates on, propagating them from operation to operation. For example, UniConstraintStream operates on single-fact tuples {A} and BiConstraintStream operates on two-fact tuples {A, B}. Putting facts into a tuple implies a relationship exists between these facts.
Match
Match is a tuple that reached the terminal operation of a constraint stream and is therefore either penalized or rewarded.
Cardinality
The number of facts in a tuple. Uni constraint streams have a cardinality of 1, bi constraint streams have a cardinality of 2, etc.
Conversion
An operation that changes the cardinality of a constraint stream. This typically happens through join(...) or a groupBy(...) operations.