Package org.optaplanner.core.impl.score.stream.drools.common

## Class DroolsRuleStructure<PatternVar>

- java.lang.Object
- - org.optaplanner.core.impl.score.stream.drools.common.DroolsRuleStructure<PatternVar>

- Type Parameters:
    `PatternVar` - type of the variable of the primary pattern (see `getPrimaryPatternBuilder()`)
  Direct Known Subclasses:
    `DroolsBiRuleStructure`, `DroolsQuadRuleStructure`, `DroolsTriRuleStructure`, `DroolsUniRuleStructure`

      public abstract class DroolsRuleStructure<PatternVar>
      extends Object

  Represents the left-hand side of a Drools rule.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `DroolsRuleStructure​(LongSupplier variableIdSupplier)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<X> org.drools.model.Variable<? extends X>` | `createVariable​(Class<X> clz, String name)` | Declare a new `Variable` in this rule, with a given name and no declared source.
    `<X> org.drools.model.Variable<? extends X>` | `createVariable​(Class<X> clz, String name, org.drools.model.DeclarationSource source)` | Declare a new `Variable` in this rule, with a given name and a declaration source.
    `<X> org.drools.model.Variable<X>` | `createVariable​(String name)` | Declares a new `Object`-typed variable, see `createVariable(Class, String, DeclarationSource)` for details.
    `<X> org.drools.model.Variable<X>` | `createVariable​(String name, org.drools.model.DeclarationSource source)` | Declares a new `Object`-typed variable, see `createVariable(Class, String)` for details.
    `List<org.drools.model.RuleItemBuilder<?>>` | `finish​(org.drools.model.consequences.ConsequenceBuilder.AbstractValidBuilder<?> consequence)` |
    `abstract List<org.drools.model.view.ViewItemBuilder<?>>` | `getDependents()` | Patterns that follow up on the primary pattern, yet are not used for filtering or joining.
    `Class[]` | `getExpectedJustificationTypes()` | Determines the types we expect to see as the result of this rule.
    `abstract List<org.drools.model.view.ViewItemBuilder<?>>` | `getPrerequisites()` | See `getPrimaryPatternBuilder()` for a definition.
    `abstract DroolsPatternBuilder<PatternVar>` | `getPrimaryPatternBuilder()` | Primary pattern is the Drools pattern to which operations such as filter and join will be applied.
    `abstract List<org.drools.model.view.ViewItemBuilder<?>>` | `getShelvedRuleItems()` | Patterns that are no longer of any use to the primary pattern, yet are required for the Drools rule to function.
    `LongSupplier` | `getVariableIdSupplier()` |
    `protected abstract Class[]` | `getVariableTypes()` |
    `protected List<org.drools.model.view.ViewItemBuilder<?>>` | `mergeDependents​(org.drools.model.view.ViewItemBuilder<?>... newDependents)` |
    `protected List<org.drools.model.view.ViewItemBuilder<?>>` | `mergeShelved​(org.drools.model.view.ViewItemBuilder<?>... newShelvedItems)` |
    `<NewA> DroolsUniRuleStructure<NewA,​NewA>` | `recollect​(org.drools.model.Variable<NewA> newA, org.drools.model.view.ViewItem<?> accumulatePattern)` |
    `<NewA> DroolsUniRuleStructure<NewA,​NewA>` | `regroup​(org.drools.model.Variable<Collection<NewA>> newASource, org.drools.model.PatternDSL.PatternDef<Collection<NewA>> collectPattern, org.drools.model.view.ViewItem<?> accumulatePattern)` |
    `<NewA,​NewB> DroolsBiRuleStructure<NewA,​NewB,​BiTuple<NewA,​NewB>>` | `regroupBi​(org.drools.model.Variable<Collection<BiTuple<NewA,​NewB>>> newSource, org.drools.model.PatternDSL.PatternDef<Collection<BiTuple<NewA,​NewB>>> collectPattern, org.drools.model.view.ViewItem<?> accumulatePattern)` |
    `<NewA,​NewB,​NewC,​NewD> DroolsQuadRuleStructure<NewA,​NewB,​NewC,​NewD,​QuadTuple<NewA,​NewB,​NewC,​NewD>>` | `regroupBiToQuad​(org.drools.model.Variable<Set<QuadTuple<NewA,​NewB,​NewC,​NewD>>> newSource, org.drools.model.PatternDSL.PatternDef<Set<QuadTuple<NewA,​NewB,​NewC,​NewD>>> collectPattern, org.drools.model.view.ViewItem<?> accumulatePattern)` |
    `<NewA,​NewB,​NewC> DroolsTriRuleStructure<NewA,​NewB,​NewC,​TriTuple<NewA,​NewB,​NewC>>` | `regroupBiToTri​(org.drools.model.Variable<Set<TriTuple<NewA,​NewB,​NewC>>> newSource, org.drools.model.PatternDSL.PatternDef<Set<TriTuple<NewA,​NewB,​NewC>>> collectPattern, org.drools.model.view.ViewItem<?> accumulatePattern)` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DroolsRuleStructure

          protected DroolsRuleStructure​(LongSupplier variableIdSupplier)

  - ### Method Detail

    - #### createVariable

          public final <X> org.drools.model.Variable<? extends X> createVariable​(Class<X> clz,
                                                                                 String name)

      Declare a new `Variable` in this rule, with a given name and no declared source. Delegates to `DSL.declarationOf(Class, String)`. Creating variables via this method guarantees unique variable name within the context of a rule through the use of `DroolsConstraintFactory.getVariableIdSupplier()`.
      Type Parameters:
        `X` - Generic type of the variable.
      Parameters:
        `clz` - type of the variable. Using `Object` will work in all cases, but Drools will spend unnecessary amount of time looking up applicable instances of that variable, as it has to traverse instances of all types in the working memory. Therefore, it is desirable to be as specific as possible.
        `name` - name of the variable, mostly useful for debugging purposes. Will be decorated by a pseudo-random numeric identifier to prevent multiple variables of the same name to exist within left-hand side of a single rule.
      Returns:
        new variable declaration, not yet bound to anything

    - #### createVariable

          public final <X> org.drools.model.Variable<? extends X> createVariable​(Class<X> clz,
                                                                                 String name,
                                                                                 org.drools.model.DeclarationSource source)

      Declare a new `Variable` in this rule, with a given name and a declaration source. Delegates to `DSL.declarationOf(Class, String, DeclarationSource)`. Creating variables via this method guarantees unique variable names within the context of a rule through the use of `DroolsConstraintFactory.getVariableIdSupplier()`.
      Type Parameters:
        `X` - Generic type of the variable.
      Parameters:
        `clz` - type of the variable. Using `Object` will work in all cases, but Drools will spend unnecessary amount of time looking up applicable instances of that variable, as it has to traverse instances of all types in the working memory. Therefore, it is desirable to be as specific as possible.
        `name` - name of the variable, mostly useful for debugging purposes. Will be decorated by a pseudo-random numeric identifier to prevent multiple variables of the same name to exist within left-hand side of a single rule.
        `source` - declaration source of the variable
      Returns:
        new variable declaration, not yet bound to anything

    - #### createVariable

          public final <X> org.drools.model.Variable<X> createVariable​(String name)

      Declares a new `Object`-typed variable, see `createVariable(Class, String, DeclarationSource)` for details.

    - #### createVariable

          public final <X> org.drools.model.Variable<X> createVariable​(String name,
                                                                       org.drools.model.DeclarationSource source)

      Declares a new `Object`-typed variable, see `createVariable(Class, String)` for details.

    - #### finish

          public final List<org.drools.model.RuleItemBuilder<?>> finish​(org.drools.model.consequences.ConsequenceBuilder.AbstractValidBuilder<?> consequence)

    - #### getVariableIdSupplier

          public LongSupplier getVariableIdSupplier()

    - #### getPrimaryPatternBuilder

          public abstract DroolsPatternBuilder<PatternVar> getPrimaryPatternBuilder()

      Primary pattern is the Drools pattern to which operations such as filter and join will be applied. Consider the following example left hand side DRL:

               $person: Person()
               $lesson: Lesson($person in people)

      Here, Lesson is the primary pattern of this rule. We can use filters to restrict matched Lesson instances, and we can use $person variable in those filters. But the Person() instances themselves are now fixed and the Person pattern can be found in `getPrerequisites()` and no longer modified.

      The primary pattern is provided as a builder. This is necessary since the patterns are shared and modified between different classes and it would therefore be possible for one class to modify the other's pattern. This way, the pattern is only constructed when necessary, at which point it will no longer be shared.

      Returns:
        never null, builder that will be used to obtain the final version of the primary pattern

    - #### getShelvedRuleItems

          public abstract List<org.drools.model.view.ViewItemBuilder<?>> getShelvedRuleItems()

      Patterns that are no longer of any use to the primary pattern, yet are required for the Drools rule to function. Consider the following example left hand side DRL:

               $tuples: Set() from accumulate(...) // This is the shelved pattern.
               $person: Person() from $tuples // This is the prerequisite pattern, referencing the shelved pattern.
               $lesson: Lesson($person in people) // This is the primary pattern, referencing the prerequisite pattern.

      In this example, any further Person filters or joiners will still be applied on the primary pattern. Yet the rule overall would not function properly without also including the shelved pattern.

      The difference between these and `getPrerequisites()` is that the latter would be folded inside a subsequent accumulate pattern, while shelved patterns (typically representing previous accumulate patterns) wouldn't. Consider the following example left hand side DRL:

               $tuples: Set() from accumulate(...) // This is the original shelved pattern from above.
               $otherTuples: Set() from accumulate(
                    and(
                        $person: Person() from $tuples, // This is the original prerequisite pattern from above.
                        $lesson: Lesson($person in people) // This is the original primary pattern from above.
                    ),
                    collectCount()
               )
               $otherPerson: Person() from $otherTuples // This is the new primary pattern.

      Returns:
        never null, a list of preceding items that are required by the primary pattern.

    - #### getPrerequisites

          public abstract List<org.drools.model.view.ViewItemBuilder<?>> getPrerequisites()

      See `getPrimaryPatternBuilder()` for a definition.
      Returns:
        never null, a list of preceding items that are required by the primary pattern

    - #### getDependents

          public abstract List<org.drools.model.view.ViewItemBuilder<?>> getDependents()

      Patterns that follow up on the primary pattern, yet are not used for filtering or joining. Consider the following example left hand side DRL:

               $person: Person() // This is the primary pattern.
               exists Person(this != $person) // This is the dependent, immutable pattern.

      In this example, any further Person filters or joiners will still be applied on the primary pattern. Yet the rule overall would not function properly without also including the dependent pattern.
      Returns:
        never null, a list of subsequent items that are required by the primary pattern

    - #### mergeShelved

          protected List<org.drools.model.view.ViewItemBuilder<?>> mergeShelved​(org.drools.model.view.ViewItemBuilder<?>... newShelvedItems)

    - #### mergeDependents

          protected List<org.drools.model.view.ViewItemBuilder<?>> mergeDependents​(org.drools.model.view.ViewItemBuilder<?>... newDependents)

    - #### recollect

          public <NewA> DroolsUniRuleStructure<NewA,​NewA> recollect​(org.drools.model.Variable<NewA> newA,
                                                                          org.drools.model.view.ViewItem<?> accumulatePattern)

    - #### regroup

          public <NewA> DroolsUniRuleStructure<NewA,​NewA> regroup​(org.drools.model.Variable<Collection<NewA>> newASource,
                                                                        org.drools.model.PatternDSL.PatternDef<Collection<NewA>> collectPattern,
                                                                        org.drools.model.view.ViewItem<?> accumulatePattern)

    - #### regroupBi

          public <NewA,​NewB> DroolsBiRuleStructure<NewA,​NewB,​BiTuple<NewA,​NewB>> regroupBi​(org.drools.model.Variable<Collection<BiTuple<NewA,​NewB>>> newSource,
                                                                                                                   org.drools.model.PatternDSL.PatternDef<Collection<BiTuple<NewA,​NewB>>> collectPattern,
                                                                                                                   org.drools.model.view.ViewItem<?> accumulatePattern)

    - #### regroupBiToTri

          public <NewA,​NewB,​NewC> DroolsTriRuleStructure<NewA,​NewB,​NewC,​TriTuple<NewA,​NewB,​NewC>> regroupBiToTri​(org.drools.model.Variable<Set<TriTuple<NewA,​NewB,​NewC>>> newSource,
                                                                                                                                                           org.drools.model.PatternDSL.PatternDef<Set<TriTuple<NewA,​NewB,​NewC>>> collectPattern,
                                                                                                                                                           org.drools.model.view.ViewItem<?> accumulatePattern)

    - #### regroupBiToQuad

          public <NewA,​NewB,​NewC,​NewD> DroolsQuadRuleStructure<NewA,​NewB,​NewC,​NewD,​QuadTuple<NewA,​NewB,​NewC,​NewD>> regroupBiToQuad​(org.drools.model.Variable<Set<QuadTuple<NewA,​NewB,​NewC,​NewD>>> newSource,
                                                                                                                                                                                               org.drools.model.PatternDSL.PatternDef<Set<QuadTuple<NewA,​NewB,​NewC,​NewD>>> collectPattern,
                                                                                                                                                                                               org.drools.model.view.ViewItem<?> accumulatePattern)

    - #### getExpectedJustificationTypes

          public Class[] getExpectedJustificationTypes()

      Determines the types we expect to see as the result of this rule.

      Example 1: For `DroolsBiRuleStructure` before regrouping, we expect this to return an array of A and B's fact type.

      Example 2: For `DroolsBiRuleStructure` after regrouping, we expect this to return an array consisting of only `BiTuple` class.

      Returns:
        never null

    - #### getVariableTypes

          protected abstract Class[] getVariableTypes()