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 ScoreManager.explainScore(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.

Method Summary

Modifier and Type	Method	Description
ConstraintFactory	getConstraintFactory()	The ConstraintFactory that build this.
Constraint	impact(String constraintPackage, String constraintName, Score<?> constraintWeight)	As defined by impact(String, Score).
default Constraint	impact(String constraintName, Score<?> constraintWeight)	Positively or negatively impact the Score by the constraintWeight for each match.
Constraint	penalize(String constraintPackage, String constraintName, Score<?> constraintWeight)	As defined by penalize(String, Score).
default Constraint	penalize(String constraintName, Score<?> constraintWeight)	Negatively impact the Score: subtract the constraintWeight for each match.
default Constraint	penalizeConfigurable(String constraintName)	Negatively impact the Score: subtract the ConstraintWeight for each match.
Constraint	penalizeConfigurable(String constraintPackage, String constraintName)	As defined by penalizeConfigurable(String).
Constraint	reward(String constraintPackage, String constraintName, Score<?> constraintWeight)	As defined by reward(String, Score).
default Constraint	reward(String constraintName, Score<?> constraintWeight)	Positively impact the Score: add the constraintWeight for each match.
default Constraint	rewardConfigurable(String constraintName)	Positively impact the Score: add the ConstraintWeight for each match.
Constraint	rewardConfigurable(String constraintPackage, String constraintName)	As defined by rewardConfigurable(String).

Method Detail

getConstraintFactory

ConstraintFactory getConstraintFactory()

The ConstraintFactory that build this.

Returns:

never null

penalize

default Constraint penalize(String constraintName,
                            Score<?> constraintWeight)

Negatively impact the Score: subtract the constraintWeight for each match.

To avoid hard-coding the constraintWeight, to allow end-users to tweak it, use penalizeConfigurable(String) and a ConstraintConfiguration instead.

The Constraint.getConstraintPackage() defaults to the package of the PlanningSolution class.

Parameters:

constraintName - never null, shows up in ConstraintMatchTotal during score justification

constraintWeight - never null

Returns:

never null

penalize

Constraint penalize(String constraintPackage,
                    String constraintName,
                    Score<?> constraintWeight)

As defined by penalize(String, Score).

Parameters:

constraintPackage - never null

constraintName - never null

constraintWeight - never null

Returns:

never null

penalizeConfigurable

default Constraint penalizeConfigurable(String constraintName)

Negatively impact the Score: subtract the ConstraintWeight for each match.

The constraintWeight comes from an ConstraintWeight annotated member on the ConstraintConfiguration, so end users can change the constraint weights dynamically. This constraint may be deactivated if the ConstraintWeight is zero. If there is no ConstraintConfiguration, use penalize(String, Score) instead.

The Constraint.getConstraintPackage() defaults to ConstraintConfiguration.constraintPackage().

Parameters:

constraintName - never null, shows up in ConstraintMatchTotal during score justification

Returns:

never null

penalizeConfigurable

Constraint penalizeConfigurable(String constraintPackage,
                                String constraintName)

As defined by penalizeConfigurable(String).

Parameters:

constraintPackage - never null

constraintName - never null

Returns:

never null

reward

default Constraint reward(String constraintName,
                          Score<?> constraintWeight)

Positively impact the Score: add the constraintWeight for each match.

To avoid hard-coding the constraintWeight, to allow end-users to tweak it, use penalizeConfigurable(String) and a ConstraintConfiguration instead.

The Constraint.getConstraintPackage() defaults to the package of the PlanningSolution class.

Parameters:

constraintName - never null, shows up in ConstraintMatchTotal during score justification

constraintWeight - never null

Returns:

never null

reward

Constraint reward(String constraintPackage,
                  String constraintName,
                  Score<?> constraintWeight)

As defined by reward(String, Score).

Parameters:

constraintPackage - never null

constraintName - never null

constraintWeight - never null

Returns:

never null

rewardConfigurable

default Constraint rewardConfigurable(String constraintName)

Positively impact the Score: add the ConstraintWeight for each match.

The constraintWeight comes from an ConstraintWeight annotated member on the ConstraintConfiguration, so end users can change the constraint weights dynamically. This constraint may be deactivated if the ConstraintWeight is zero. If there is no ConstraintConfiguration, use reward(String, Score) instead.

The Constraint.getConstraintPackage() defaults to ConstraintConfiguration.constraintPackage().

Parameters:

constraintName - never null, shows up in ConstraintMatchTotal during score justification

Returns:

never null

rewardConfigurable

Constraint rewardConfigurable(String constraintPackage,
                              String constraintName)

As defined by rewardConfigurable(String).

Parameters:

constraintPackage - never null

constraintName - never null

Returns:

never null

impact

default Constraint impact(String constraintName,
                          Score<?> constraintWeight)

Positively or negatively impact the Score by the constraintWeight for each match.

Use penalize(...) or reward(...) instead, unless this constraint can both have positive and negative weights.

The Constraint.getConstraintPackage() defaults to the package of the PlanningSolution class.

Parameters:

constraintName - never null, shows up in ConstraintMatchTotal during score justification

constraintWeight - never null

Returns:

never null

impact

Constraint impact(String constraintPackage,
                  String constraintName,
                  Score<?> constraintWeight)

As defined by impact(String, Score).

Parameters:

constraintPackage - never null

constraintName - never null

constraintWeight - never null

Returns:

never null