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.7.SP1-redhat-0000x:create \
       -DprojectGroupId=com.example \
       -DprojectArtifactId=optaplanner-quickstart  \
       -DplatformGroupId=com.redhat.quarkus.platform
       -DplatformArtifactId=quarkus-bom
       -DplatformVersion=2.13.7.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 6.1. Properties used in the mvn io.quarkus:quarkus-maven-plugin:2.13.7.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.7.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.7.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.7.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 8.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 8.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 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 10.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

Procedure

1. Run the school timetable application for a fixed amount of time, for example, five minutes.

2. Review the score calculation speed in the log file as shown in the following example:

   ... Solving ended: ..., score calculation speed (29455/sec), ...

   Copy to Clipboard Toggle word wrap
3. Change a constraint, run the planning application again for the same amount of time, and review the score calculation speed recorded in the log file.

4. Run the application in debug mode to log every step that the application makes:

   • To run debug mode from the command line, use the -D system property.

   • To permanently enable debug mode, add the following line to the application.properties file:

     quarkus.log.category."org.optaplanner".level=debug

     Copy to Clipboard Toggle word wrap

     The following example shows output in the log file in debug mode:

     ... Solving started: time spent (67), best score (-20init/0hard/0soft), environment mode (REPRODUCIBLE), random (JDK with seed 0).
     ...     CH step (0), time spent (128), score (-18init/0hard/0soft), selected move count (15), picked move ([Math(101) {null -> Room A}, Math(101) {null -> MONDAY 08:30}]).
     ...     CH step (1), time spent (145), score (-16init/0hard/0soft), selected move count (15), picked move ([Physics(102) {null -> Room A}, Physics(102) {null -> MONDAY 09:30}]).
     ...

     Copy to Clipboard Toggle word wrap
5. Use trace logging to show every step and every move for each step.

Procedure

1. Use Hibernate and Panache to store Timeslot, Room, and Lesson instances in a database. See Simplified Hibernate ORM with Panache for more information.
2. Expose the instances through REST. For information, see Writing JSON REST Services.

3. Update the TimeTableResource class to read and write a TimeTable instance in a single transaction:

   package org.acme.optaplanner.rest;
   
   import javax.inject.Inject;
   import javax.transaction.Transactional;
   import javax.ws.rs.GET;
   import javax.ws.rs.POST;
   import javax.ws.rs.Path;
   
   import io.quarkus.panache.common.Sort;
   import org.acme.optaplanner.domain.Lesson;
   import org.acme.optaplanner.domain.Room;
   import org.acme.optaplanner.domain.TimeTable;
   import org.acme.optaplanner.domain.Timeslot;
   import org.optaplanner.core.api.score.ScoreManager;
   import org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore;
   import org.optaplanner.core.api.solver.SolverManager;
   import org.optaplanner.core.api.solver.SolverStatus;
   
   @Path("/timeTable")
   public class TimeTableResource {
   
       public static final Long SINGLETON_TIME_TABLE_ID = 1L;
   
       @Inject
       SolverManager<TimeTable, Long> solverManager;
       @Inject
       ScoreManager<TimeTable, HardSoftScore> scoreManager;
   
       // To try, open http://localhost:8080/timeTable
       @GET
       public TimeTable getTimeTable() {
           // Get the solver status before loading the solution
           // to avoid the race condition that the solver terminates between them
           SolverStatus solverStatus = getSolverStatus();
           TimeTable solution = findById(SINGLETON_TIME_TABLE_ID);
           scoreManager.updateScore(solution); // Sets the score
           solution.setSolverStatus(solverStatus);
           return solution;
       }
   
       @POST
       @Path("/solve")
       public void solve() {
           solverManager.solveAndListen(SINGLETON_TIME_TABLE_ID,
                   this::findById,
                   this::save);
       }
   
       public SolverStatus getSolverStatus() {
           return solverManager.getSolverStatus(SINGLETON_TIME_TABLE_ID);
       }
   
       @POST
       @Path("/stopSolving")
       public void stopSolving() {
           solverManager.terminateEarly(SINGLETON_TIME_TABLE_ID);
       }
   
       @Transactional
       protected TimeTable findById(Long id) {
           if (!SINGLETON_TIME_TABLE_ID.equals(id)) {
               throw new IllegalStateException("There is no timeTable with id (" + id + ").");
           }
           // Occurs in a single transaction, so each initialized lesson references the same timeslot/room instance
           // that is contained by the timeTable's timeslotList/roomList.
           return new TimeTable(
                   Timeslot.listAll(Sort.by("dayOfWeek").and("startTime").and("endTime").and("id")),
                   Room.listAll(Sort.by("name").and("id")),
                   Lesson.listAll(Sort.by("subject").and("teacher").and("studentGroup").and("id")));
       }
   
       @Transactional
       protected void save(TimeTable timeTable) {
           for (Lesson lesson : timeTable.getLessonList()) {
               // TODO this is awfully naive: optimistic locking causes issues if called by the SolverManager
               Lesson attachedLesson = Lesson.findById(lesson.getId());
               attachedLesson.setTimeslot(lesson.getTimeslot());
               attachedLesson.setRoom(lesson.getRoom());
           }
       }
   
   }

   Copy to Clipboard Toggle word wrap

   This example includes a TimeTable instance. However, you can enable multi-tenancy and handle TimeTable instances for multiple schools in parallel.

   The getTimeTable() method returns the latest timetable from the database. It uses the ScoreManager method, which is automatically injected, to calculate the score of that timetable and make it available to the UI.

   The solve() method starts a job to solve the current timetable and stores the time slot and room assignments in the database. It uses the SolverManager.solveAndListen() method to listen to intermediate best solutions and update the database accordingly. The UI uses this to show progress while the backend is still solving.

4. Update the TimeTableResourceTest class to reflect that the solve() method returns immediately and to poll for the latest solution until the solver finishes solving:

   package org.acme.optaplanner.rest;
   
   import javax.inject.Inject;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.acme.optaplanner.domain.Lesson;
   import org.acme.optaplanner.domain.TimeTable;
   import org.junit.jupiter.api.Test;
   import org.junit.jupiter.api.Timeout;
   import org.optaplanner.core.api.solver.SolverStatus;
   
   import static org.junit.jupiter.api.Assertions.assertFalse;
   import static org.junit.jupiter.api.Assertions.assertNotNull;
   import static org.junit.jupiter.api.Assertions.assertTrue;
   
   @QuarkusTest
   public class TimeTableResourceTest {
   
       @Inject
       TimeTableResource timeTableResource;
   
       @Test
       @Timeout(600_000)
       public void solveDemoDataUntilFeasible() throws InterruptedException {
           timeTableResource.solve();
           TimeTable timeTable = timeTableResource.getTimeTable();
           while (timeTable.getSolverStatus() != SolverStatus.NOT_SOLVING) {
               // Quick polling (not a Test Thread Sleep anti-pattern)
               // Test is still fast on fast machines and doesn't randomly fail on slow machines.
               Thread.sleep(20L);
               timeTable = timeTableResource.getTimeTable();
           }
           assertFalse(timeTable.getLessonList().isEmpty());
           for (Lesson lesson : timeTable.getLessonList()) {
               assertNotNull(lesson.getTimeslot());
               assertNotNull(lesson.getRoom());
           }
           assertTrue(timeTable.getScore().isFeasible());
       }
   
   }

   Copy to Clipboard Toggle word wrap
5. Build a web UI on top of these REST methods to provide a visual representation of the timetable.
6. Review the quickstart source code.

Procedure

1. Add the Micrometer Prometheus dependency to the school timetable pom.xml file:

   <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
   </dependency>

   Copy to Clipboard Toggle word wrap

2. Start the school timetable application:

   mvn compile quarkus:dev

   Copy to Clipboard Toggle word wrap
3. Open http://localhost:8080/q/metric in a web browser.

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Red Hat Build of OptaPlanner
   • Version: 8.33
2. Download Red Hat Build of OptaPlanner 8.33 Quick Starts.

3. Extract the rhbop-8.33.0-optaplanner-quickstarts-sources.zip file.

   The extracted org.optaplanner.optaplanner-quickstarts-8.33.0.Final-redhat-00004/use-cases/vaccination-scheduling directory contains example source code.

4. Navigate to the org.optaplanner.optaplanner-quickstarts-8.33.0.Final-redhat-00004/use-cases/vaccination-scheduling directory.

5. Enter the following command to start the OptaPlanner vaccination appointment scheduler in development mode:

   $ mvn quarkus:dev

   Copy to Clipboard Toggle word wrap

6. To view the OptaPlanner vaccination appointment scheduler, enter the following URL in a web browser.

   http://localhost:8080/

   Copy to Clipboard Toggle word wrap
7. To run the OptaPlanner vaccination appointment scheduler, click Solve.
8. Make changes to the source code then press the F5 key to refresh your browser. Notice that the changes that you made are now available.

Procedure

1. Navigate to the /use-cases/vaccination-scheduling directory.

2. To compile the OptaPlanner vaccination appointment scheduler, enter the following command:

   $ mvn package

   Copy to Clipboard Toggle word wrap

3. To run the compiled OptaPlanner vaccination appointment scheduler, enter the following command:

   $ java -jar ./target/quarkus-app/quarkus-run.jar

   Copy to Clipboard Toggle word wrap
   Note

   To run the application on port 8081, add -Dquarkus.http.port=8081 to the preceding command.

4. To start the OptaPlanner vaccination appointment scheduler, enter the following URL in a web browser.

   http://localhost:8080/

   Copy to Clipboard Toggle word wrap

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Red Hat Build of OptaPlanner
   • Version: 8.33
2. Download Red Hat Build of OptaPlanner 8.33 Quick Starts.
3. Extract the rhbop-8.33.0-optaplanner-quickstarts-sources.zip file.
4. Navigate to the org.optaplanner.optaplanner-quickstarts-8.33.0.Final-redhat-00004/use-cases/employee-scheduling directory.

5. Enter the following command to start the OptaPlanner employee scheduler in development mode:

   $ mvn quarkus:dev

   Copy to Clipboard Toggle word wrap

6. To view the OptaPlanner employee scheduler, enter the following URL in a web browser.

   http://localhost:8080/

   Copy to Clipboard Toggle word wrap
7. To run the OptaPlanner employee scheduler, click Solve.
8. Make changes to the source code then press the F5 key to refresh your browser. Notice that the changes that you made are now available.

Procedure

1. Navigate to the /use-cases/vaccination-scheduling directory.

2. To compile the OptaPlanner employee scheduler, enter the following command:

   $ mvn package

   Copy to Clipboard Toggle word wrap

3. To run the compiled OptaPlanner employee scheduler, enter the following command:

   $ java -jar ./target/quarkus-app/quarkus-run.jar

   Copy to Clipboard Toggle word wrap
   Note

   To run the application on port 8081, add -Dquarkus.http.port=8081 to the preceding command.

4. To start the OptaPlanner employee scheduler, enter the following URL in a web browser.

   http://localhost:8080/

   Copy to Clipboard Toggle word wrap

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Red Hat Build of OptaPlanner
   • Version: 8.33
2. Download Red Hat Build of OptaPlanner 8.33 Quick Starts.

3. Extract the rhbop-8.33.0-optaplanner-quickstarts-sources.zip file.

   The extracted org.optaplanner.optaplanner-quickstarts-8.33.0.Final-redhat-00004/use-cases/school-timetabling directory contains example source code.

4. Navigate to the org.optaplanner.optaplanner-quickstarts-8.33.0.Final-redhat-00004/use-cases/school-timetabling directory.
5. Download the Red Hat Build of OptaPlanner 8.33.0 Maven Repositroy (rhbop-8.33.0-optaplanner-maven-repository.zip).
6. Extract the rhbop-8.33.0-optaplanner-maven-repository.zip file.
7. Copy the contents of the rhbop-8.33.0-optaplanner/maven-repository subdirectory into the ~/.m2/repository directory.
8. Navigate to the org.optaplanner.optaplanner-quickstarts-8.33.0.Final-redhat-00004/technology/java-spring-boot directory.

9. Enter the following command to build the Spring Boot school timetabling project:

   mvn clean install -DskipTests

   Copy to Clipboard Toggle word wrap

10. To build the Spring Boot school timetabling project, enter the following command:

    mvn spring-boot:run -DskipTests

    Copy to Clipboard Toggle word wrap

11. To view the project, enter the following URL in a web browser:

    http://localhost:8080/

    Copy to Clipboard Toggle word wrap

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 13.4, “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.