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

Annotation Interface PlanningEntity

@Target(TYPE)
@Retention(RUNTIME)
public @interface PlanningEntity

Specifies that the class is a planning entity. There are two types of entities:

Genuine entity

Must have at least 1 genuine planning variable, and 0 or more shadow variables.

Shadow entity

Must have at least 1 shadow variable, and no genuine variables.

If a planning entity has neither a genuine nor a shadow variable, it is not a planning entity and the solver will fail fast.

The class should have a public no-arg constructor, so it can be cloned (unless the PlanningSolution.solutionCloner() is specified).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	PlanningEntity.NullComparator<T>
static interface	PlanningEntity.NullComparatorFactory<Solution_,T>
static interface	PlanningEntity.NullDifficultyComparator<T>	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of PlanningEntity.NullComparator.
static interface	PlanningEntity.NullDifficultyWeightFactory<Solution_,T>	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of PlanningEntity.NullComparatorFactory.
static interface	PlanningEntity.NullPinningFilter	Deprecated, for removal: This API element is subject to removal in a future version. Prefer using PlanningPin.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<? extends Comparator>	comparatorClass	Allows sorting a collection of planning entities for this variable.
Class<? extends ComparatorFactory>	comparatorFactoryClass	The ComparatorFactory alternative for comparatorClass().
Class<? extends Comparator>	difficultyComparatorClass	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of comparatorClass().
Class<? extends SelectionSorterWeightFactory>	difficultyWeightFactoryClass	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of comparatorFactoryClass().
Class<? extends PinningFilter>	pinningFilter	Deprecated, for removal: This API element is subject to removal in a future version. Prefer using PlanningPin.

Element Details

comparatorClass

Class<? extends Comparator> comparatorClass

Allows sorting a collection of planning entities for this variable. Some algorithms perform better when the entities are sorted based on specific metrics.

The Comparator should sort the data in ascending order. For example, prioritize three vehicles by sorting them based on their capacity: Vehicle C (4 people), Vehicle A (6 people), Vehicle B (32 people)

Do not use together with comparatorFactoryClass().

Returns:

PlanningVariable.NullComparator when it is null (workaround for annotation limitation)

See Also:

• comparatorFactoryClass()

Default:

ai.timefold.solver.core.api.domain.entity.PlanningEntity.NullComparator.class

comparatorFactoryClass

Class<? extends ComparatorFactory> comparatorFactoryClass

The ComparatorFactory alternative for comparatorClass().

Differs from comparatorClass() because it allows accessing the current solution when creating the comparator.

Do not use together with comparatorClass().

Returns:

PlanningEntity.NullComparatorFactory when it is null (workaround for annotation limitation)

See Also:

• comparatorClass()

Default:

ai.timefold.solver.core.api.domain.entity.PlanningEntity.NullComparatorFactory.class

pinningFilter

@Deprecated(forRemoval=true,
            since="1.23.0")
Class<? extends PinningFilter> pinningFilter

Deprecated, for removal: This API element is subject to removal in a future version.

Prefer using PlanningPin.

A pinned planning entity is never changed during planning, this is useful in repeated planning use cases (such as continuous planning and real-time planning). This applies to all the planning variables of this planning entity.

The method PinningFilter.accept(Object, Object) returns false if the selection entity is pinned and it returns true if the selection entity is movable

Returns:

PlanningEntity.NullPinningFilter when it is null (workaround for annotation limitation)

Default:

ai.timefold.solver.core.api.domain.entity.PlanningEntity.NullPinningFilter.class

difficultyComparatorClass

@Deprecated(forRemoval=true,
            since="1.28.0")
Class<? extends Comparator> difficultyComparatorClass

Deprecated, for removal: This API element is subject to removal in a future version.

Deprecated in favor of comparatorClass().

Allows a collection of planning entities to be sorted by difficulty. A difficultyWeight estimates how hard is to plan a certain PlanningEntity. Some algorithms benefit from planning on more difficult planning entities first/last or from focusing on them.

The Comparator should sort in ascending difficulty (even though many optimization algorithms will reverse it). For example: sorting 3 processes on difficultly based on their RAM usage requirement: Process B (1GB RAM), Process A (2GB RAM), Process C (7GB RAM),

Do not use together with difficultyWeightFactoryClass().

Returns:

PlanningEntity.NullDifficultyComparator when it is null (workaround for annotation limitation)

See Also:

• difficultyWeightFactoryClass()

Default:

ai.timefold.solver.core.api.domain.entity.PlanningEntity.NullDifficultyComparator.class

difficultyWeightFactoryClass

@Deprecated(forRemoval=true,
            since="1.28.0")
Class<? extends SelectionSorterWeightFactory> difficultyWeightFactoryClass

Deprecated, for removal: This API element is subject to removal in a future version.

Deprecated in favor of comparatorFactoryClass().

The SelectionSorterWeightFactory alternative for difficultyComparatorClass().

Do not use together with difficultyComparatorClass().

Returns:

PlanningEntity.NullDifficultyWeightFactory when it is null (workaround for annotation limitation)

See Also:

• difficultyComparatorClass()

Default:

ai.timefold.solver.core.api.domain.entity.PlanningEntity.NullDifficultyWeightFactory.class