Developing solvers with Red Hat Build of OptaPlanner

Procedure

1. In a command terminal, enter the following command to verify that Maven is using JDK 11 and that the Maven version is 3.8 or higher:

   mvn --version

   Copy to Clipboard Toggle word wrap
2. If the preceding command does not return JDK 11, add the path to JDK 11 to the PATH environment variable and enter the preceding command again.

3. To generate a Quarkus OptaPlanner quickstart project, enter the following command, where redhat-0000x is the current version of the Quarkus BOM file:

   mvn com.redhat.quarkus.platform:quarkus-maven-plugin:2.13.8.SP1-redhat-0000x:create \
       -DprojectGroupId=com.example \
       -DprojectArtifactId=optaplanner-quickstart  \
       -DplatformGroupId=com.redhat.quarkus.platform
       -DplatformArtifactId=quarkus-bom
       -DplatformVersion=2.13.8.SP1-redhat-0000x \
       -DnoExamples
       -Dextensions="resteasy,resteasy-jackson,optaplanner-quarkus,optaplanner-quarkus-jackson" \

   Copy to Clipboard Toggle word wrap

   This command create the following elements in the ./optaplanner-quickstart directory:

   • The Maven structure
   • Example Dockerfile file in src/main/docker

   • The application configuration file

     Expand

     Table 5.1. Properties used in the mvn io.quarkus:quarkus-maven-plugin:2.13.8.SP1-redhat-0000x:create command

     Property	Description
     projectGroupId	The group ID of the project.
     projectArtifactId	The artifact ID of the project.
     extensions	A comma-separated list of Quarkus extensions to use with this project. For a full list of Quarkus extensions, enter mvn quarkus:list-extensions on the command line.
     noExamples	Creates a project with the project structure but without tests or classes.

     Show more

     The values of the projectGroupID and the projectArtifactID properties are used to generate the project version. The default project version is 1.0.0-SNAPSHOT.

4. To view your OptaPlanner project, change directory to the OptaPlanner Quickstarts directory:

   cd optaplanner-quickstart

   Copy to Clipboard Toggle word wrap

5. Review the pom.xml file. The content should be similar to the following example:

   <?xml version="1.0"?>
   <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.example</groupId>
     <artifactId>optaplanner-quickstart</artifactId>
     <version>1.0.0-SNAPSHOT</version>
     <properties>
       <compiler-plugin.version>3.8.1</compiler-plugin.version>
       <maven.compiler.release>11</maven.compiler.release>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
       <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
       <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
       <quarkus.platform.version>2.13.8.SP1-redhat-0000x</quarkus.platform.version>
       <skipITs>true</skipITs>
       <surefire-plugin.version>3.0.0-M7</surefire-plugin.version>
     </properties>
     <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>${quarkus.platform.group-id}</groupId>
           <artifactId>${quarkus.platform.artifact-id}</artifactId>
           <version>${quarkus.platform.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
         <dependency>
           <groupId>${quarkus.platform.group-id}</groupId>
           <artifactId>quarkus-optaplanner-bom</artifactId>
           <version>${quarkus.platform.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>org.optaplanner</groupId>
         <artifactId>optaplanner-quarkus</artifactId>
       </dependency>
       <dependency>
         <groupId>org.optaplanner</groupId>
         <artifactId>optaplanner-quarkus-jackson</artifactId>
       </dependency>
       <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-resteasy-jackson</artifactId>
       </dependency>
       <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-resteasy</artifactId>
       </dependency>
       <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-arc</artifactId>
       </dependency>
       <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-junit5</artifactId>
         <scope>test</scope>
       </dependency>
       <dependency>
         <groupId>io.rest-assured</groupId>
         <artifactId>rest-assured</artifactId>
         <scope>test</scope>
       </dependency>
     </dependencies>
     <repositories>
       <repository>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
         <id>redhat</id>
         <url>https://maven.repository.redhat.com/ga</url>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
         <id>redhat</id>
         <url>https://maven.repository.redhat.com/ga</url>
       </pluginRepository>
     </pluginRepositories>
     <build>
       <plugins>
         <plugin>
           <groupId>${quarkus.platform.group-id}</groupId>
           <artifactId>quarkus-maven-plugin</artifactId>
           <version>${quarkus.platform.version}</version>
           <extensions>true</extensions>
           <executions>
             <execution>
               <goals>
                 <goal>build</goal>
                 <goal>generate-code</goal>
                 <goal>generate-code-tests</goal>
               </goals>
             </execution>
           </executions>
         </plugin>
         <plugin>
           <artifactId>maven-compiler-plugin</artifactId>
           <version>${compiler-plugin.version}</version>
           <configuration>
             <compilerArgs>
               <arg>-parameters</arg>
             </compilerArgs>
           </configuration>
         </plugin>
         <plugin>
           <artifactId>maven-surefire-plugin</artifactId>
           <version>${surefire-plugin.version}</version>
           <configuration>
             <systemPropertyVariables>
               <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
               <maven.home>${maven.home}</maven.home>
             </systemPropertyVariables>
           </configuration>
         </plugin>
         <plugin>
           <artifactId>maven-failsafe-plugin</artifactId>
           <version>${surefire-plugin.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>integration-test</goal>
                 <goal>verify</goal>
               </goals>
               <configuration>
                 <systemPropertyVariables>
                   <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                   <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                   <maven.home>${maven.home}</maven.home>
                 </systemPropertyVariables>
               </configuration>
             </execution>
           </executions>
         </plugin>
       </plugins>
     </build>
     <profiles>
       <profile>
         <id>native</id>
         <activation>
           <property>
             <name>native</name>
           </property>
         </activation>
         <properties>
           <skipITs>false</skipITs>
           <quarkus.package.type>native</quarkus.package.type>
         </properties>
       </profile>
     </profiles>
   </project>

   Copy to Clipboard Toggle word wrap

Procedure

1. Open https://code.quarkus.redhat.com in your web browser:
2. Specify details about your project:
3. Enter a group name for your project. The format of the name follows the Java package naming convention, for example, com.example.
4. Enter a name that you want to use for Maven artifacts generated from your project, for example code-with-quarkus.

5. Select Build Tool > Maven to specify that you want to create a Maven project. The build tool that you choose determines the items:

   • The directory structure of your generated project
   • The format of configuration files used in your generated project

   • The custom build script and command for compiling and starting your application that code.quarkus.redhat.com displays for you after you generate your project

     Note

     Red Hat provides support for using code.quarkus.redhat.com to create OptaPlanner Maven projects only. Generating Gradle projects is not supported by Red Hat.

6. Enter a version to be used in artifacts generated from your project. The default value of this field is 1.0.0-SNAPSHOT. Using semantic versioning is recommended, but you can use a different type of versioning if you prefer.

7. Enter the package name of artifacts that the build tool generates when you package your project.

   According to the Java package naming conventions the package name should match the group name that you use for your project, but you can specify a different name.

8. Select the following extensions to include as dependencies:

   • RESTEasy JAX-RS (quarkus-resteasy)
   • RESTEasy Jackson (quarkus-resteasy-jackson)
   • OptaPlanner AI constraint solver(optaplanner-quarkus)

   • OptaPlanner Jackson (optaplanner-quarkus-jackson)

     Red Hat provides different levels of support for individual extensions on the list, which are indicated by labels next to the name of each extension:

     • SUPPORTED extensions are fully supported by Red Hat for use in enterprise applications in production environments.
     • TECH-PREVIEW extensions are subject to limited support by Red Hat in production environments under the Technology Preview Features Support Scope.
     • DEV-SUPPORT extensions are not supported by Red Hat for use in production environments, but the core functionalities that they provide are supported by Red Hat developers for use in developing new applications.

     • DEPRECATED extension are planned to be replaced with a newer technology or implementation that provides the same functionality.

       Unlabeled extensions are not supported by Red Hat for use in production environments.

9. Select Generate your application to confirm your choices and display the overlay screen with the download link for the archive that contains your generated project. The overlay screen also shows the custom command that you can use to compile and start your application.
10. Select Download the ZIP to save the archive with the generated project files to your system.
11. Extract the contents of the archive.

12. Navigate to the directory that contains your extracted project files:

    cd <directory_name>

    Copy to Clipboard Toggle word wrap

13. Compile and start your application in development mode:

    ./mvnw compile quarkus:dev

    Copy to Clipboard Toggle word wrap

Procedure

1. Create a Quarkus application:

   quarkus create app -P io.quarkus:quarkus-bom:2.13.8.SP1-redhat-0000x

   Copy to Clipboard Toggle word wrap

2. To view the available extensions, enter the following command:

   quarkus ext -i

   Copy to Clipboard Toggle word wrap

   This command returns the following extensions:

   optaplanner-quarkus
   optaplanner-quarkus-benchmark
   optaplanner-quarkus-jackson
   optaplanner-quarkus-jsonb

   Copy to Clipboard Toggle word wrap

3. Enter the following command to add extensions to the project’s pom.xml file:

   quarkus ext add resteasy-jackson
   quarkus ext add optaplanner-quarkus
   quarkus ext add optaplanner-quarkus-jackson

   Copy to Clipboard Toggle word wrap

4. Open the pom.xml file in a text editor. The contents of the file should look similar to the following example:

   <?xml version="1.0"?>
   <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.acme</groupId>
     <artifactId>code-with-quarkus-optaplanner</artifactId>
     <version>1.0.0-SNAPSHOT</version>
     <properties>
   	<compiler-plugin.version>3.8.1</compiler-plugin.version>
   	<maven.compiler.parameters>true</maven.compiler.parameters>
   	<maven.compiler.source>11</maven.compiler.source>
   	<maven.compiler.target>11</maven.compiler.target>
   	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   	<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
   	<quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
   	<quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
   	<quarkus.platform.version>2.13.8.SP1-redhat-0000x</quarkus.platform.version>
   	<surefire-plugin.version>3.0.0-M5</surefire-plugin.version>
     </properties>
     <dependencyManagement>
   	<dependencies>
     	<dependency>
       	<groupId>${quarkus.platform.group-id}</groupId>
       	<artifactId>${quarkus.platform.artifact-id}</artifactId>
       	<version>${quarkus.platform.version}</version>
       	<type>pom</type>
       	<scope>import</scope>
     	</dependency>
     	<dependency>
       	<groupId>io.quarkus.platform</groupId>
       	<artifactId>optaplanner-quarkus</artifactId>
       	<version>2.2.2.Final</version>
       	<type>pom</type>
       	<scope>import</scope>
     	</dependency>
   	</dependencies>
     </dependencyManagement>
     <dependencies>
   	<dependency>
     	<groupId>io.quarkus</groupId>
     	<artifactId>quarkus-arc</artifactId>
   	</dependency>
   	<dependency>
     	<groupId>io.quarkus</groupId>
     	<artifactId>quarkus-resteasy</artifactId>
   	</dependency>
   	<dependency>
     	<groupId>org.optaplanner</groupId>
     	<artifactId>optaplanner-quarkus</artifactId>
   	</dependency>
   	<dependency>
     	<groupId>org.optaplanner</groupId>
     	<artifactId>optaplanner-quarkus-jackson</artifactId>
   	</dependency>
   	<dependency>
     	<groupId>io.quarkus</groupId>
     	<artifactId>quarkus-resteasy-jackson</artifactId>
   	</dependency>
   	<dependency>
     	<groupId>io.quarkus</groupId>
     	<artifactId>quarkus-junit5</artifactId>
     	<scope>test</scope>
   	</dependency>
   	<dependency>
     	<groupId>io.rest-assured</groupId>
     	<artifactId>rest-assured</artifactId>
     	<scope>test</scope>
   	</dependency>
     </dependencies>
     <build>
   	<plugins>
     	<plugin>
       	<groupId>${quarkus.platform.group-id}</groupId>
       	<artifactId>quarkus-maven-plugin</artifactId>
       	<version>${quarkus.platform.version}</version>
       	<extensions>true</extensions>
       	<executions>
         	<execution>
           	<goals>
             	<goal>build</goal>
             	<goal>generate-code</goal>
             	<goal>generate-code-tests</goal>
           	</goals>
         	</execution>
       	</executions>
     	</plugin>
     	<plugin>
       	<artifactId>maven-compiler-plugin</artifactId>
       	<version>${compiler-plugin.version}</version>
       	<configuration>
         	<parameters>${maven.compiler.parameters}</parameters>
       	</configuration>
     	</plugin>
     	<plugin>
       	<artifactId>maven-surefire-plugin</artifactId>
       	<version>${surefire-plugin.version}</version>
       	<configuration>
         	<systemPropertyVariables>
           	<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
           	<maven.home>${maven.home}</maven.home>
         	</systemPropertyVariables>
       	</configuration>
     	</plugin>
   	</plugins>
     </build>
     <profiles>
   	<profile>
     	<id>native</id>
     	<activation>
       	<property>
         	<name>native</name>
       	</property>
     	</activation>
     	<build>
       	<plugins>
         	<plugin>
           	<artifactId>maven-failsafe-plugin</artifactId>
           	<version>${surefire-plugin.version}</version>
           	<executions>
             	<execution>
               	<goals>
                 	<goal>integration-test</goal>
                 	<goal>verify</goal>
               	</goals>
               	<configuration>
                 	<systemPropertyVariables>
                   	<native.image.path>${project.build.directory}/${project.build.finalName}-run</native.image.path>
                   	<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                   	<maven.home>${maven.home}</maven.home>
                 	</systemPropertyVariables>
               	</configuration>
             	</execution>
           	</executions>
         	</plugin>
       	</plugins>
     	</build>
     	<properties>
       	<quarkus.package.type>native</quarkus.package.type>
     	</properties>
   	</profile>
     </profiles>
   </project>

   Copy to Clipboard Toggle word wrap

Procedure

1. Build a Solver instance with the SolverFactory.

2. Configure the solver configuration XML file:

   1. Define the model.
   2. Define the score function.

   3. Optional: Configure the optimization algorithm.

      The following example is a solver XML file for the NQueens problem:

      <?xml version="1.0" encoding="UTF-8"?>
      <solver xmlns="https://www.optaplanner.org/xsd/solver" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="https://www.optaplanner.org/xsd/solver https://www.optaplanner.org/xsd/solver/solver.xsd">
        <!-- Define the model -->
        <solutionClass>org.optaplanner.examples.nqueens.domain.NQueens</solutionClass>
        <entityClass>org.optaplanner.examples.nqueens.domain.Queen</entityClass>
      
        <!-- Define the score function -->
        <scoreDirectorFactory>
          <scoreDrl>org/optaplanner/examples/nqueens/optional/nQueensConstraints.drl</scoreDrl>
        </scoreDirectorFactory>
      
        <!-- Configure the optimization algorithms (optional) -->
        <termination>
          ...
        </termination>
        <constructionHeuristic>
          ...
        </constructionHeuristic>
        <localSearch>
          ...
        </localSearch>
      </solver>

      Copy to Clipboard Toggle word wrap
      Note

      On some environments, for example OSGi and JBoss modules, classpath resources such as the solver config, score DRLs, and domain classe) in your JAR files might not be available to the default ClassLoader of the optaplanner-core JAR file. In those cases, provide the ClassLoader of your classes as a parameter:

             SolverFactory<NQueens> solverFactory = SolverFactory.createFromXmlResource(
                     ".../nqueensSolverConfig.xml", getClass().getClassLoader());

      Copy to Clipboard Toggle word wrap

3. Configure the SolverFactory with a solver configuration XML file, provided as a classpath resource as defined by ClassLoader.getResource():

          SolverFasctory<NQueens> solverFactory = SolverFactory.createFromXmlResource(
                  "org/optaplanner/examples/nqueens/optional/nqueensSolverConfig.xml");
          Solver<NQueens> solver = solverFactory.buildSolver();

   Copy to Clipboard Toggle word wrap

Procedure

1. Add a custom property.

   For example, if your EasyScoreCalculator has heavy calculations which are cached and you want to increase the cache size in one benchmark add the myCacheSize property:

     <scoreDirectorFactory>
       <easyScoreCalculatorClass>...MyEasyScoreCalculator</easyScoreCalculatorClass>
       <easyScoreCalculatorCustomProperties>
         <property name="myCacheSize" value="1000"/><!-- Override value -->
       </easyScoreCalculatorCustomProperties>
     </scoreDirectorFactory>

   Copy to Clipboard Toggle word wrap

2. Add a public setter for each custom property, which is called when a Solver is built.

   public class MyEasyScoreCalculator extends EasyScoreCalculator<MySolution, SimpleScore> {
   
           private int myCacheSize = 500; // Default value
   
           @SuppressWarnings("unused")
           public void setMyCacheSize(int myCacheSize) {
               this.myCacheSize = myCacheSize;
           }
   
       ...
   }

   Copy to Clipboard Toggle word wrap

   Most value types are supported, including boolean, int, double, BigDecimal, String and enums.

Procedure

1. Add the following Maven dependency to your OptaPlanner project’s pom.xml file:

   Note

   You do not need to add an extra bridge dependency.

       <dependency>
         <groupId>ch.qos.logback</groupId>
         <artifactId>logback-classic</artifactId>
         <version>1.x</version>
       </dependency>

   Copy to Clipboard Toggle word wrap

2. Configure the logging level on the org.optaplanner package in your logback.xml file as shown in the following example where <LEVEL> is a logging level listed in Section 7.4, “Using Logback to log OptaPlanner solver activity”.

   <configuration>
   
     <logger name="org.optaplanner" level="<LEVEL>"/>
   
     ...
   
   </configuration>

   Copy to Clipboard Toggle word wrap

3. Optional: If you have a multitenant application where multiple Solver instances might be running at the same time, separate the logging of each instance into separate files:

   1. Surround the solve() call with Mapped Diagnostic Context (MDC):

              MDC.put("tenant.name",tenantName);
              MySolution bestSolution = solver.solve(problem);
              MDC.remove("tenant.name");

      Copy to Clipboard Toggle word wrap

   2. Configure your logger to use different files for each ${tenant.name}. For example, use a SiftingAppender in the logback.xml file:

        <appender name="fileAppender" class="ch.qos.logback.classic.sift.SiftingAppender">
          <discriminator>
            <key>tenant.name</key>
            <defaultValue>unknown</defaultValue>
          </discriminator>
          <sift>
            <appender name="fileAppender.${tenant.name}" class="...FileAppender">
              <file>local/log/optaplanner-${tenant.name}.log</file>
              ...
            </appender>
          </sift>
        </appender>

      Copy to Clipboard Toggle word wrap
      Note

      When running multiple solvers or one multithreaded solve, most appenders, including the console, cause congestion with debug and trace logging. Switch to an async appender to avoid this problem or turn off debug logging.

4. If OptaPlanner doesn’t recognize the new level, temporarily add the system property -Dlogback.LEVEL=true to troubleshoot.

Procedure

1. Add the bridge dependency to the project pom.xml file:

       <dependency>
         <groupId>org.slf4j</groupId>
         <artifactId>slf4j-log4j12</artifactId>
         <version>1.x</version>
       </dependency>

   Copy to Clipboard Toggle word wrap

2. Configure the logging level on the package org.optaplanner in your log4j.xml file as shown in the following example, where <LEVEL> is a logging level listed in Section 7.4, “Using Logback to log OptaPlanner solver activity”.

   <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
   
     <category name="org.optaplanner">
       <priority value="<LEVEL>" />
     </category>
   
     ...
   
   </log4j:configuration>

   Copy to Clipboard Toggle word wrap

3. Optional: If you have a multitenant application where multiple Solver instances might be running at the same time, separate the logging of each instance into separate files:

   1. Surround the solve() call with Mapped Diagnostic Context (MDC):

              MDC.put("tenant.name",tenantName);
              MySolution bestSolution = solver.solve(problem);
              MDC.remove("tenant.name");

      Copy to Clipboard Toggle word wrap

   2. Configure your logger to use different files for each ${tenant.name}. For example, use a SiftingAppender in the logback.xml file:

        <appender name="fileAppender" class="ch.qos.logback.classic.sift.SiftingAppender">
          <discriminator>
            <key>tenant.name</key>
            <defaultValue>unknown</defaultValue>
          </discriminator>
          <sift>
            <appender name="fileAppender.${tenant.name}" class="...FileAppender">
              <file>local/log/optaplanner-${tenant.name}.log</file>
              ...
            </appender>
          </sift>
        </appender>

      Copy to Clipboard Toggle word wrap
      Note

      When running multiple solvers or one multithreaded solve, most appenders, including the console, cause congestion with debug and trace logging. Switch to an async appender to avoid this problem or turn off debug logging.

Procedure

1. Optional: To change the random seed of a random instance, specify a randomSeed:

   <solver xmlns="https://www.optaplanner.org/xsd/solver" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="https://www.optaplanner.org/xsd/solver https://www.optaplanner.org/xsd/solver/solver.xsd">
     <randomSeed>0</randomSeed>
     ...
   </solver>

   Copy to Clipboard Toggle word wrap

2. Optional: To change the pseudorandom number generator implementation, specify a value for the randomType property listed in the solver configuration file below, where <RANDOM_NUMBER_GENERATOR> is a pseudorandom number generator:

   <solver xmlns="https://www.optaplanner.org/xsd/solver" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="https://www.optaplanner.org/xsd/solver https://www.optaplanner.org/xsd/solver/solver.xsd">
     <randomType><RANDOM_NUMBER_GENERATOR></randomType>
     ...
   </solver>

   Copy to Clipboard Toggle word wrap

   The following pseudorandom number generators are supported:

   • JDK (default): Standard random number generator implementation (java.util.Random)
   • MERSENNE_TWISTER: Random number generator implementation by Commons Math
   • WELL512A, WELL1024A, WELL19937A, WELL19937C, WELL44497A and WELL44497B: Random number generator implementation by Commons Math

Procedure

1. To handle intermediate best solutions, use solveAndListen(…​):

   public class TimeTableService {
   
       private SolverManager<TimeTable, Long> solverManager;
   
       // Returns immediately
       public void solveLive(Long timeTableId) {
           solverManager.solveAndListen(timeTableId,
                   // Called once, when solving starts
                   this::findById,
                   // Called multiple times, for every best solution change
                   this::save);
       }
   
       public TimeTable findById(Long timeTableId) {...}
   
       public void save(TimeTable timeTable) {...}
   
       public void stopSolving(Long timeTableId) {
           solverManager.terminateEarly(timeTableId);
       }
   
   }

   Copy to Clipboard Toggle word wrap

   This implementation is using the database to communicate with the UI, which polls the database. More advanced implementations push the best solutions directly to the UI or a messaging queue.

2. When the user is satisfied with the intermediate best solution and does not want to wait any longer for a better one, call SolverManager.terminateEarly(problemId).

Procedure

1. Create a new class to hold the constraint weights and other constraint parameters, for example ConferenceConstraintConfiguration.

2. Annotate this class with @ConstraintConfiguration:

   @ConstraintConfiguration
   public class ConferenceConstraintConfiguration {
       ...
   }

   Copy to Clipboard Toggle word wrap

3. Add the constraint configuration on the planning solution and annotate that field or property with @ConstraintConfigurationProvider:

   @PlanningSolution
   public class ConferenceSolution {
   
       @ConstraintConfigurationProvider
       private ConferenceConstraintConfiguration constraintConfiguration;
   
       ...
   }

   Copy to Clipboard Toggle word wrap

4. In the constraint configuration class, add a @ConstraintWeight property for each constraint and give each constraint weight a default value:

   @ConstraintConfiguration(constraintPackage = "...conferencescheduling.score")
   public class ConferenceConstraintConfiguration {
   
       @ConstraintWeight("Speaker conflict")
       private HardMediumSoftScore speakerConflict = HardMediumSoftScore.ofHard(10);
   
       @ConstraintWeight("Theme track conflict")
       private HardMediumSoftScore themeTrackConflict = HardMediumSoftScore.ofSoft(10);
       @ConstraintWeight("Content conflict")
       private HardMediumSoftScore contentConflict = HardMediumSoftScore.ofSoft(100);
   
       ...
   }

   Copy to Clipboard Toggle word wrap

   The @ConstraintConfigurationProvider annotation automatically exposes the constraint configuration as a problem fact. There is no need to add a @ProblemFactProperty annotation. A constraint weight cannot be null.

5. Expose the constraint weights in a UI so business users can tweak the values. The preceding example uses the ofHard(), ofMedium() and ofSoft() methods to do that. Notice how it defaults the content conflict constraint as ten times more important than the theme track conflict constraint. Normally, a constraint weight only uses one score level, but it’s possible to use multiple score levels (at a small performance cost).

Procedure

1. Create the src/main/java/com/example/domain/Timeslot.java class:

   package com.example.domain;
   
   import java.time.DayOfWeek;
   import java.time.LocalTime;
   
   public class Timeslot {
   
       private DayOfWeek dayOfWeek;
       private LocalTime startTime;
       private LocalTime endTime;
   
       private Timeslot() {
       }
   
       public Timeslot(DayOfWeek dayOfWeek, LocalTime startTime, LocalTime endTime) {
           this.dayOfWeek = dayOfWeek;
           this.startTime = startTime;
           this.endTime = endTime;
       }
   
       @Override
       public String toString() {
           return dayOfWeek + " " + startTime.toString();
       }
   
       // ********************************
       // Getters and setters
       // ********************************
   
       public DayOfWeek getDayOfWeek() {
           return dayOfWeek;
       }
   
       public LocalTime getStartTime() {
           return startTime;
       }
   
       public LocalTime getEndTime() {
           return endTime;
       }
   
   }

   Copy to Clipboard Toggle word wrap

   Notice the toString() method keeps the output short so it is easier to read OptaPlanner’s DEBUG or TRACE log, as shown later.

2. Create the src/main/java/com/example/domain/Room.java class:

   package com.example.domain;
   
   public class Room {
   
       private String name;
   
       private Room() {
       }
   
       public Room(String name) {
           this.name = name;
       }
   
       @Override
       public String toString() {
           return name;
       }
   
       // ********************************
       // Getters and setters
       // ********************************
   
       public String getName() {
           return name;
       }
   
   }

   Copy to Clipboard Toggle word wrap

3. Create the src/main/java/com/example/domain/Lesson.java class:

   package com.example.domain;
   
   import org.optaplanner.core.api.domain.entity.PlanningEntity;
   import org.optaplanner.core.api.domain.variable.PlanningVariable;
   
   @PlanningEntity
   public class Lesson {
   
       private Long id;
   
       private String subject;
       private String teacher;
       private String studentGroup;
   
       @PlanningVariable(valueRangeProviderRefs = "timeslotRange")
       private Timeslot timeslot;
   
       @PlanningVariable(valueRangeProviderRefs = "roomRange")
       private Room room;
   
       private Lesson() {
       }
   
       public Lesson(Long id, String subject, String teacher, String studentGroup) {
           this.id = id;
           this.subject = subject;
           this.teacher = teacher;
           this.studentGroup = studentGroup;
       }
   
       @Override
       public String toString() {
           return subject + "(" + id + ")";
       }
   
       // ********************************
       // Getters and setters
       // ********************************
   
       public Long getId() {
           return id;
       }
   
       public String getSubject() {
           return subject;
       }
   
       public String getTeacher() {
           return teacher;
       }
   
       public String getStudentGroup() {
           return studentGroup;
       }
   
       public Timeslot getTimeslot() {
           return timeslot;
       }
   
       public void setTimeslot(Timeslot timeslot) {
           this.timeslot = timeslot;
       }
   
       public Room getRoom() {
           return room;
       }
   
       public void setRoom(Room room) {
           this.room = room;
       }
   
   }

   Copy to Clipboard Toggle word wrap

   The Lesson class has an @PlanningEntity annotation, so OptaPlanner knows that this class changes during solving because it contains one or more planning variables.

   The timeslot field has an @PlanningVariable annotation, so OptaPlanner knows that it can change its value. In order to find potential Timeslot instances to assign to this field, OptaPlanner uses the valueRangeProviderRefs property to connect to a value range provider that provides a List<Timeslot> to pick from. See Section 14.3, “Gather the domain objects in a planning solution” for information about value range providers.

   The room field also has an @PlanningVariable annotation for the same reasons.

Procedure

1. To compile the application in development mode, enter the following command from the project directory:

   ./mvnw compile quarkus:dev

   Copy to Clipboard Toggle word wrap

2. Test the REST service. You can use any REST client. The following example uses the Linux command curl to send a POST request:

   $ curl -i -X POST http://localhost:8080/timeTable/solve -H "Content-Type:application/json" -d '{"timeslotList":[{"dayOfWeek":"MONDAY","startTime":"08:30:00","endTime":"09:30:00"},{"dayOfWeek":"MONDAY","startTime":"09:30:00","endTime":"10:30:00"}],"roomList":[{"name":"Room A"},{"name":"Room B"}],"lessonList":[{"id":1,"subject":"Math","teacher":"A. Turing","studentGroup":"9th grade"},{"id":2,"subject":"Chemistry","teacher":"M. Curie","studentGroup":"9th grade"},{"id":3,"subject":"French","teacher":"M. Curie","studentGroup":"10th grade"},{"id":4,"subject":"History","teacher":"I. Jones","studentGroup":"10th grade"}]}'

   Copy to Clipboard Toggle word wrap

   After the time period specified in termination spent time defined in your application.properties file, the service returns output similar to the following example:

   HTTP/1.1 200
   Content-Type: application/json
   ...
   
   {"timeslotList":...,"roomList":...,"lessonList":[{"id":1,"subject":"Math","teacher":"A. Turing","studentGroup":"9th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"08:30:00","endTime":"09:30:00"},"room":{"name":"Room A"}},{"id":2,"subject":"Chemistry","teacher":"M. Curie","studentGroup":"9th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"09:30:00","endTime":"10:30:00"},"room":{"name":"Room A"}},{"id":3,"subject":"French","teacher":"M. Curie","studentGroup":"10th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"08:30:00","endTime":"09:30:00"},"room":{"name":"Room B"}},{"id":4,"subject":"History","teacher":"I. Jones","studentGroup":"10th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"09:30:00","endTime":"10:30:00"},"room":{"name":"Room B"}}],"score":"0hard/0soft"}

   Copy to Clipboard Toggle word wrap

   Notice that your application assigned all four lessons to one of the two time slots and one of the two rooms. Also notice that it conforms to all hard constraints. For example, M. Curie’s two lessons are in different time slots.

3. To review what OptaPlanner did during the solving time, review the info log on the server side. The following is sample info log output:

   ... Solving started: time spent (33), best score (-8init/0hard/0soft), environment mode (REPRODUCIBLE), random (JDK with seed 0).
   ... Construction Heuristic phase (0) ended: time spent (73), best score (0hard/0soft), score calculation speed (459/sec), step total (4).
   ... Local Search phase (1) ended: time spent (5000), best score (0hard/0soft), score calculation speed (28949/sec), step total (28398).
   ... Solving ended: time spent (5000), best score (0hard/0soft), score calculation speed (28524/sec), phase total (2), environment mode (REPRODUCIBLE).

   Copy to Clipboard Toggle word wrap