Chapter 13. Red Hat Build of OptaPlanner on Spring Boot: a school timetable quick start guide

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.

Procedure

1. Create the TimeTableSpringBootApp.java class with the following content:

   package com.example;
   
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   
   @SpringBootApplication
   public class TimeTableSpringBootApp {
   
       public static void main(String[] args) {
           SpringApplication.run(TimeTableSpringBootApp.class, args);
       }
   
   }

   Copy to Clipboard Toggle word wrap
2. Replace the src/main/java/com/example/DemoApplication.java class created by Spring Initializr with the TimeTableSpringBootApp.java class.
3. Run the TimeTableSpringBootApp.java class as the main class of a regular Java application.

Procedure

1. Create Java Persistence API (JPA) repositories for Timeslot, Room, and Lesson. For information about creating JPA repositories, see Accessing Data with JPA on the Spring website.
2. Expose the JPA repositories through REST. For information about exposing the repositories, see Accessing JPA Data with REST on the Spring website.
3. Build a TimeTableRepository facade to read and write a TimeTable in a single transaction.

4. Adjust the TimeTableController as shown in the following example:

   package com.example.solver;
   
   import com.example.domain.TimeTable;
   import com.example.persistence.TimeTableRepository;
   import org.optaplanner.core.api.score.ScoreManager;
   import org.optaplanner.core.api.solver.SolverManager;
   import org.optaplanner.core.api.solver.SolverStatus;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/timeTable")
   public class TimeTableController {
   
       @Autowired
       private TimeTableRepository timeTableRepository;
       @Autowired
       private SolverManager<TimeTable, Long> solverManager;
       @Autowired
       private ScoreManager<TimeTable> scoreManager;
   
       // To try, GET http://localhost:8080/timeTable
       @GetMapping()
       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 = timeTableRepository.findById(TimeTableRepository.SINGLETON_TIME_TABLE_ID);
           scoreManager.updateScore(solution); // Sets the score
           solution.setSolverStatus(solverStatus);
           return solution;
       }
   
       @PostMapping("/solve")
       public void solve() {
           solverManager.solveAndListen(TimeTableRepository.SINGLETON_TIME_TABLE_ID,
                   timeTableRepository::findById,
                   timeTableRepository::save);
       }
   
       public SolverStatus getSolverStatus() {
           return solverManager.getSolverStatus(TimeTableRepository.SINGLETON_TIME_TABLE_ID);
       }
   
       @PostMapping("/stopSolving")
       public void stopSolving() {
           solverManager.terminateEarly(TimeTableRepository.SINGLETON_TIME_TABLE_ID);
       }
   
   }

   Copy to Clipboard Toggle word wrap

   For simplicity, this code handles only one TimeTable instance, but it is straightforward to enable multi-tenancy and handle multiple TimeTable instances of different high schools in parallel.

   The getTimeTable() method returns the latest timetable from the database. It uses the ScoreManager (which is automatically injected) to calculate the score of that timetable so the UI can show the score.

   The solve() method starts a job to solve the current timetable and store 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. This enables the UI to show progress while the backend is still solving.

5. Now that the solve() method returns immediately, adjust the TimeTableControllerTest as shown in the following example:

   package com.example.solver;
   
   import com.example.domain.Lesson;
   import com.example.domain.TimeTable;
   import org.junit.jupiter.api.Test;
   import org.junit.jupiter.api.Timeout;
   import org.optaplanner.core.api.solver.SolverStatus;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.boot.test.context.SpringBootTest;
   
   import static org.junit.jupiter.api.Assertions.assertFalse;
   import static org.junit.jupiter.api.Assertions.assertNotNull;
   import static org.junit.jupiter.api.Assertions.assertTrue;
   
   @SpringBootTest(properties = {
           "optaplanner.solver.termination.spent-limit=1h", // Effectively disable this termination in favor of the best-score-limit
           "optaplanner.solver.termination.best-score-limit=0hard/*soft"})
   public class TimeTableControllerTest {
   
       @Autowired
       private TimeTableController timeTableController;
   
       @Test
       @Timeout(600_000)
       public void solveDemoDataUntilFeasible() throws InterruptedException {
           timeTableController.solve();
           TimeTable timeTable = timeTableController.getTimeTable();
           while (timeTable.getSolverStatus() != SolverStatus.NOT_SOLVING) {
               // Quick polling (not a Test Thread Sleep anti-pattern)
               // Test is still fast on fast systems and doesn't randomly fail on slow systems.
               Thread.sleep(20L);
               timeTable = timeTableController.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
6. Poll for the latest solution until the solver finishes solving.
7. To visualize the timetable, build an attractive web UI on top of these REST methods.

Procedure

1. Navigate to the technology/java-spring-boot directory.

2. Add the Micrometer Prometheus dependencies to the school timetable pom.xml file:

   <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
   </dependency>
   <dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
   </dependency>

   Copy to Clipboard Toggle word wrap

3. Add the following property to the application.properties file:

   management.endpoints.web.exposure.include=metrics,prometheus

   Copy to Clipboard Toggle word wrap

4. Start the school timetable application:

   mvn spring-boot:run

   Copy to Clipboard Toggle word wrap
5. Open http://localhost:8080/actuator/prometheus in a web browser.