Package ai.timefold.solver.core.api.domain.variable

Annotation Interface ShadowSources

@Target(METHOD) @Retention(RUNTIME) public @interface ShadowSources
Specifies the paths to variables that a method referenced by ShadowVariable.supplierName() uses to compute the value of a ShadowVariable.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String[]
    value
    The paths to variables the method uses to compute the value of a declarative shadow variable.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    alignmentKey
    If non-empty, this is name of a property on the entity that will be used to define a group of entities to align values for.

  • Element Details

    • value

      String[] value
      The paths to variables the method uses to compute the value of a declarative shadow variable.

      Each path is a String that is one of the following three forms:

      • "variableName", for referring any variable on the same planning entity.
      • A list of names seperated by ".", such as "variableOrFact.fact.entity.variable", for referencing a variable accessible from the planning entity. The first property may be a fact or any non-declarative variable; the remaining properties before the end must be facts, and the final property must be a variable. For the path "a.b", it refers to the variable "b" on the property/variable "a" on the planning entity. In general, if you access a variable in your method using a chain like a.b.c, that chain should be included as a source.
      • A list of names seperated by ".", followed by a name suffix by "[].", followed by either of the forms above. For example, "group[].previous". In this case, "group" is a Collection on the planning entity, and the annotated method uses the "previous" variable of each element in the collection. The collection must not change during solving and may be null.
      For example, for this method 
       
 @InverseRelationShadowVariable
 Entity entity;

 @PreviousElementShadowVariable
 Value previous;

 @ShadowVariable(supplierName="startTimeSupplier")
 LocalDateTime startTime;

 @ShadowVariable(supplierName="endTimeSupplier")
 LocalDateTime endTime;

 Collection<Value> dependencies;

 &#64;ShadowSources("previous.endTime", "entity", "dependencies[].endTime")
 public LocalDateTime startTimeSupplier() {
     LocalDateTime readyTime = null;
     if (previous != null) {
         readyTime = previous.endTime;
     } else if (entity != null) {
         readyTime = entity.startTime;
     } else {
         return null;
     }
     if (dependencies != null) {
         for (var dependency : dependencies) {
             if (dependency.endTime == null) {
                 return null;
             }
             readyTime = (readyTime.isBefore(dependency.endTime)? dependency.endTime: readyTime;
         }
     }
     return readyTime;
 }
      The value { "previous.endTime", "entity", "dependencies[].endTime") } is used for ShadowSources since it accesses the end time declarative shadow variable of its previous element variable ("previous.endTime"), a fact on its inverse relation variable ("entity"), and the end time declarative shadow variable on each element in its dependencies ("dependencies[].endTime").

      Returns:
      A non-empty list of variables the supplier method accesses.

    • alignmentKey

      String alignmentKey
      If non-empty, this is name of a property on the entity that will be used to define a group of entities to align values for.

      When the alignment key is null, the entity is considered independent and their alignment will not be aligned with any other entity. When the alignment key is non-null, the shadow variable will only be calculated for one entity with that alignment key, and all other entities with that alignment key will have their shadows set to that value.

      When the alignment key is unspecified or null, the entity is not considered to be part of any alignment group and will not share variable calculations with other entities.

      Important: the alignment key must not point to a planning variable and must not change during solving.

      Returns:
      The name of a property on the entity to use for value alignment, or the empty string to not align values with any other entity.
      Default:
      ""