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, BavetGroupBridgeUniConstraintStream, BavetJoinBiConstraintStream, BavetJoinBridgeBiConstraintStream, BavetJoinBridgeUniConstraintStream, BavetJoinTriConstraintStream, BavetScoringBiConstraintStream, BavetScoringTriConstraintStream, BavetScoringUniConstraintStream, DroolsAbstractBiConstraintStream, DroolsAbstractConstraintStream, DroolsAbstractQuadConstraintStream, DroolsAbstractTriConstraintStream, DroolsAbstractUniConstraintStream, DroolsExistsBiConstraintStream, DroolsExistsQuadConstraintStream, DroolsExistsTriConstraintStream, DroolsExistsUniConstraintStream, DroolsFilterBiConstraintStream, DroolsFilterQuadConstraintStream, DroolsFilterTriConstraintStream, DroolsFilterUniConstraintStream, DroolsFromUniConstraintStream, DroolsGroupingBiConstraintStream, DroolsGroupingQuadConstraintStream, DroolsGroupingTriConstraintStream, DroolsGroupingUniConstraintStream, DroolsJoinBiConstraintStream, DroolsJoinQuadConstraintStream, DroolsJoinTriConstraintStream, DroolsScoringBiConstraintStream, DroolsScoringQuadConstraintStream, DroolsScoringTriConstraintStream, DroolsScoringUniConstraintStream

      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 `ScoreDirector.getConstraintMatchTotalMap()` 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 and Description
    --- | ---
    `ConstraintFactory` | `getConstraintFactory()` The `ConstraintFactory` that build this.
    `default Constraint` | `impact(String constraintName, Score<?> constraintWeight)` Positively or negatively impact the `Score` by the constraintWeight for each match.
    `Constraint` | `impact(String constraintPackage, String constraintName, Score<?> constraintWeight)` As defined by `impact(String, Score)`.
    `default Constraint` | `penalize(String constraintName, Score<?> constraintWeight)` Negatively impact the `Score`: subtract the constraintWeight for each match.
    `Constraint` | `penalize(String constraintPackage, String constraintName, Score<?> constraintWeight)` As defined by `penalize(String, Score)`.
    `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)`.
    `default Constraint` | `reward(String constraintName, Score<?> constraintWeight)` Positively impact the `Score`: add the constraintWeight for each match.
    `Constraint` | `reward(String constraintPackage, String constraintName, Score<?> constraintWeight)` As defined by `reward(String, Score)`.
    `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

Copyright © 2006–2021 JBoss by Red Hat. All rights reserved.