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

## Interface ConstraintStream

- All Known Subinterfaces:
    `BiConstraintStream<A,​B>`, `InnerBiConstraintStream<A,​B>`, `InnerQuadConstraintStream<A,​B,​C,​D>`, `InnerTriConstraintStream<A,​B,​C>`, `InnerUniConstraintStream<A>`, `QuadConstraintStream<A,​B,​C,​D>`, `TriConstraintStream<A,​B,​C>`, `UniConstraintStream<A>`
  All Known Implementing Classes:
    `AbstractConstraintStream`, `BavetAbstractBiConstraintStream`, `BavetAbstractConstraintStream`, `BavetAbstractTriConstraintStream`, `BavetAbstractUniConstraintStream`, `BavetFilterBiConstraintStream`, `BavetFilterTriConstraintStream`, `BavetFilterUniConstraintStream`, `BavetFromUniConstraintStream`, `BavetGroupBiConstraintStream`, `BavetGroupBridgeBiConstraintStream`, `BavetGroupBridgeUniConstraintStream`, `BavetJoinBiConstraintStream`, `BavetJoinBridgeBiConstraintStream`, `BavetJoinBridgeUniConstraintStream`, `BavetJoinTriConstraintStream`, `BavetScoringBiConstraintStream`, `BavetScoringTriConstraintStream`, `BavetScoringUniConstraintStream`, `DroolsAbstractBiConstraintStream`, `DroolsAbstractConstraintStream`, `DroolsAbstractQuadConstraintStream`, `DroolsAbstractTriConstraintStream`, `DroolsAbstractUniConstraintStream`, `DroolsExistsBiConstraintStream`, `DroolsExistsQuadConstraintStream`, `DroolsExistsTriConstraintStream`, `DroolsExistsUniConstraintStream`, `DroolsFilterBiConstraintStream`, `DroolsFilterQuadConstraintStream`, `DroolsFilterTriConstraintStream`, `DroolsFilterUniConstraintStream`, `DroolsFlatteningBiConstraintStream`, `DroolsFlatteningQuadConstraintStream`, `DroolsFlatteningTriConstraintStream`, `DroolsFlatteningUniConstraintStream`, `DroolsFromUniConstraintStream`, `DroolsGroupingBiConstraintStream`, `DroolsGroupingQuadConstraintStream`, `DroolsGroupingTriConstraintStream`, `DroolsGroupingUniConstraintStream`, `DroolsJoinBiConstraintStream`, `DroolsJoinQuadConstraintStream`, `DroolsJoinTriConstraintStream`, `DroolsMappingUniConstraintStream`

      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.from(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.from(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

    All Methods Instance Methods Abstract Methods Default Methods
    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