Chapter 8. Red Hat build of OptaPlanner on Red Hat build of Quarkus: a school timetable quick start guide

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.6 or higher:

   mvn --version

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 the project, enter one of the following commands:

   Note

   Apple macOS and Microsoft Windows are not supported production environments.

   • If you are using Linux or Apple macOS, enter the following command:

     mvn io.quarkus:quarkus-maven-plugin:1.11.6.Final-redhat-00001:create \
         -DprojectGroupId=com.example \
         -DprojectArtifactId=optaplanner-quickstart  \
         -Dextensions="resteasy,resteasy-jackson,optaplanner-quarkus,optaplanner-quarkus-jackson" \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformVersion=1.11.6.Final-redhat-00001 \
         -DnoExamples

     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 8.1. Properties used in the mvn io.quarkus:quarkus-maven-plugin:1.11.6.Final-redhat-00001: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.
       platformGroupId	The Group ID of the target platform.
       platformVersion	The version of the platform that you want the project to use.
       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. The values of the platformGroupId and platformVersion properties are used by quarkus-universe-bom to manage project dependencies.

4. After the directory structure is created, open the optaplanner-quickstart/pom.xml file in a text editor and examine the contents of the file to ensure it contains the following elements:

   <properties>
   	...
   	<quarkus-plugin.version>1.11.6.Final-redhat-00001</quarkus-plugin.version>
   	<quarkus.platform.artifact-id>quarkus-universe-bom</quarkus.platform.artifact-id>
   	<quarkus.platform.group-id>com.redhat.quarkus</quarkus.platform.group-id>
   	<quarkus.platform.version>1.11.6.Final-redhat-00001.Final-redhat-00001</quarkus.platform.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>
   	</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>

   The Quarkus BOM is imported into the pom.xml file. Therefore, you do not need to list the versions of individual Quarkus dependencies in the pom.xml file.

5. Review the quarkus-resteasy dependency in the pom.xml file. This dependency enables you to develop REST applications:

       <dependency>
           <groupId>io.quarkus</groupId>
           <artifactId>quarkus-resteasy</artifactId>
       </dependency>

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;
       }
   
   }

   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;
       }
   
   }

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;
       }
   
   }

   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 8.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.

Procedure

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

   ./mvnw compile quarkus:dev

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"}]}'

   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"}

   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).