手順

1. Web ブラウザーで Spring Initializr を開きます。

   https://start.spring.io/

2. プロジェクト、言語、Spring Boot バージョンを選択し、プロジェクトのメタデータを入力します。
3. Add Dependencies をクリックし、Spring Web を選択して spring-boot-starter-web の依存関係を追加します。
4. GENERATE をクリックします。プロジェクトの ZIP ファイルがダウンロードされます。
5. ZIP ファイルを展開して、Spring Boot プロジェクトディレクトリーに移動します。

6. Red Hat Business Optimizer の依存関係 (optaplanner-spring-boot-starter) を追加します。現在、optaplanner-spring-boot-starter は Spring Initializr に含まれていないため、ビルドファイルに手動で追加する必要があります。

   • Maven プロジェクトを生成した場合は optaplanner-spring-boot-starter 依存関係をプロジェクトの pom.xml に追加します。

     <dependencyManagement>
         <dependencies>
             <dependency>
                 <groupId>org.optaplanner</groupId>
                 <artifactId>optaplanner-spring-boot-starter</artifactId>
                 <version>{project-version}</version>
             </dependency>
         </dependencies>
     </dependencyManagement>

     以下の例では、optaplanner-spring-boot-starter 依存関係をプロジェクトの pom.xml ファイルに追加します。

     <?xml version="1.0" encoding="UTF-8"?>
     <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
         <modelVersion>4.0.0</modelVersion>
         <parent>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-parent</artifactId>
             <version>{version-org-spring-framework-boot}</version>
         </parent>
     
         <groupId>com.example</groupId>
         <artifactId>constraint-solving-ai-optaplanner</artifactId>
         <version>0.1.0-SNAPSHOT</version>
         <name>Constraint Solving AI with Red Hat Business Optimizer</name>
         <description>A Spring Boot Red Hat Business Optimizer example to generate a school timetable.</description>
     
         <properties>
             <java.version>1.8</java.version>
         </properties>
     
         <dependencies>
             <dependency>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-starter-web</artifactId>
             </dependency>
             <dependency>
                 <groupId>org.optaplanner</groupId>
                 <artifactId>optaplanner-spring-boot-starter</artifactId>
             </dependency>
     
             <dependency>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-starter-test</artifactId>
                 <scope>test</scope>
                 <exclusions>
                     <exclusion>
                         <groupId>org.junit.vintage</groupId>
                         <artifactId>junit-vintage-engine</artifactId>
                     </exclusion>
                 </exclusions>
             </dependency>
         </dependencies>
     
         <dependencyManagement>
             <dependencies>
                 <dependency>
                     <groupId>org.optaplanner</groupId>
                     <artifactId>optaplanner-spring-boot-starter</artifactId>
                     <version>{project-version}</version>
                 </dependency>
             </dependencies>
         </dependencyManagement>
     
         <build>
             <plugins>
                 <plugin>
                     <groupId>org.springframework.boot</groupId>
                     <artifactId>spring-boot-maven-plugin</artifactId>
                 </plugin>
             </plugins>
         </build>
     
     </project>

   • Gradle プロジェクトを生成した場合は optaplanner-spring-boot-starter を build.gradle ファイルに追加します。

     implementation "org.optaplanner:optaplanner-spring-boot-starter:{project-version}"

     以下の例では optaplanner-spring-boot-starter 依存関係を、Gradle Java プロジェクトの build.gradle ファイルに追加します。

     plugins {
         id "org.springframework.boot" version "{version-org-spring-framework-boot}"
         id "io.spring.dependency-management" version "1.0.9.RELEASE"
         id "java"
     }
     
     group = "com.example"
     version = "0.1.0-SNAPSHOT"
     sourceCompatibility = "1.8"
     
     repositories {
         mavenCentral()
     }
     
     dependencies {
         implementation "org.springframework.boot:spring-boot-starter-web"
         implementation "org.optaplanner:optaplanner-spring-boot-starter:{project-version}"
         testImplementation("org.springframework.boot:spring-boot-starter-test") {
             exclude group: "org.junit.vintage", module: "junit-vintage-engine"
         }
     }
     
     test {
         useJUnitPlatform()
     }

手順

1. src/main/java/com/example/domain/Timeslot.java クラスを作成します。

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

   後述しているように、toString() メソッドで出力を短くするため、Red Hat Business Optimizer の DEBUG ログまたは TRACE ログの読み取りが簡単になっています。

2. src/main/java/com/example/domain/Room.java クラスを作成します。

   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. src/main/java/com/example/domain/Lesson.java クラスを作成します。

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

   Lesson クラスには @PlanningEntity アノテーションが含まれており、その中にプランニング変数が 1 つ以上含まれているため、Red Hat Business Optimizer はこのクラスが解決時に変化することを認識します。

   timeslot フィールドには @PlanningVariable アノテーションがあるため、Red Hat Business Optimizer は、このフィールドの値が変化することを認識しています。このフィールドに割り当てることのできる Timeslot インスタンスを見つけ出すために、Red Hat Business Optimizer は valueRangeProviderRefs プロパティーを使用して値の範囲プロバイダーと連携し、List<Timeslot> を提供して選択できるようにします。値の範囲プロバイダーに関する詳細は、4章プランニングソリューションでのドメインオブジェクトの収集 を参照してください。

   room フィールドにも、同じ理由で @PlanningVariable アノテーションが含まれます。

手順

1. 以下の内容を含む TimeTableSpringBootApp.java クラスを作成します。

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

2. Spring Initializr で作成された src/main/java/com/example/DemoApplication.java クラスは TimeTableSpringBootApp.java クラスに置き換えます。
3. 通常の Java アプリケーションのメインクラスとして TimeTableSpringBootApp.java クラスを実行します。

手順

1. Timeslot、Room、および Lesson の Java Persistence API (JPA) リポジトリーを作成します。JPA リポジトリーの作成に関する情報は、Spring の Web サイトの Accessing Data with JPA を参照してください。
2. REST で JPA リポジトリーを公開します。リポジトリーの公開に関する情報は、Spring の Web サイトの Accessing JPA Data with REST を参照してください。
3. TimeTableRepository Facade をビルドして、1 回のトランザクションで TimeTable を読み取り、書き込みます。

4. 以下の例のように TimeTableController を調整します。

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

   簡素化するために、このコードは TimeTable インスタンスを 1 つだけ処理しますが、マルチテナントを有効にして、異なる高校の TimeTable インスタンスを複数、平行して処理することも簡単にできます。

   getTimeTable() メソッドは、データベースから最新の時間割を返します。このメソッドは、ScoreManager (自動注入) を使用して、UI でスコアを表示できるように、対象の時間割のスコアを計算します。

   solve() メソッドは、ジョブを開始して、現在の時間割を解決し、時間枠と部屋の割り当てをデータベースに保存します。このメソッドは、SolverManager.solveAndListen() メソッドを使用して、中間の最適解をリッスンし、それに合わせてデータベースを更新します。こうすることで、バックエンドで解決しながら、UI で進捗を表示できます。

5. solve() メソッドが即座に返されるようになったので、以下の例のように TimeTableControllerTest を調整します。

   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 machines and doesn't randomly fail on slow machines.
               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());
       }
   
   }

6. ソルバーの解決が完了するまで、最新のソリューションをポーリングします。
7. 時間割を視覚化するには、これらの REST メソッドの上に適切な Web UI を構築します。