[#14312] Add more developer friendly schema validation error

src/main/java/teammates/main/Application.java

@@ -10,6 +10,7 @@
 
 import teammates.common.util.Config;
 import teammates.common.util.Logger;
+import teammates.ui.errorhandlers.DevServerStartupErrorHandler;
 import teammates.ui.servlets.DevServerLoginServlet;
 
 /**
@@ -75,12 +76,26 @@ public void lifeCycleStopped(LifeCycle event) {
         server.setHandler(webapp);
         server.setStopAtShutdown(true);
         server.addEventListener(customLifeCycleListener);
+        webapp.setThrowUnavailableOnStartupException(true);
 
-        server.start();
+        try {
+            server.start();
+        } catch (Exception e) {
+            stopServer(server);
+            throw Config.IS_DEV_SERVER ? DevServerStartupErrorHandler.transform(e) : e;
+        }
 
         // By using the server.join() the server thread will join with the current thread.
         // See https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#join-- for more details.
         server.join();
     }
 
+    private static void stopServer(Server server) {
+        try {
+            server.stop();
+        } catch (Exception e) {
+            log.severe("Failed to stop server after web application startup failure.", e);
+        }
+    }
+
 }

src/main/java/teammates/ui/errorhandlers/DevServerStartupErrorHandler.java

@@ -0,0 +1,80 @@
+package teammates.ui.errorhandlers;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Function;
+
+import org.hibernate.tool.schema.spi.SchemaManagementException;
+
+import teammates.ui.exception.DevServerStartupException;
+
+/**
+ * Handles startup errors with dev-server-friendly messages where possible.
+ */
+public final class DevServerStartupErrorHandler {
+
+    private static final String SCHEMA_VALIDATION_PREFIX = "Schema-validation:";
+    private static final String SCHEMA_VALIDATION_MESSAGE = String.join(System.lineSeparator(),
+            "",
+            "============================================================",
+            "Database schema validation failed:",
+            "%s",
+            "",
+            "Your local database schema is out of date.",
+            "Run: ./gradlew liquibaseUpdate",
+            "Then restart the local server.",
+            "",
+            "For more details, see docs/how-to/schema-migration.md",
+            "============================================================",
+            "");
+
+    /**
+     * Add new common startup errors here in order of specificity.
+     */
+    private static final List<Function<Throwable, Optional<String>>> ERROR_MESSAGE_PROVIDERS = List.of(
+            DevServerStartupErrorHandler::buildSchemaValidationMessage);
+
+    private DevServerStartupErrorHandler() {
+        // Utility class
+    }
+
+    /**
+     * Transforms a recognized startup error into a dev-server-friendly exception.
+     * Returns the original exception when no provider recognizes it.
+     */
+    public static Exception transform(Exception e) {
+        return ERROR_MESSAGE_PROVIDERS.stream()
+                .map(provider -> provider.apply(e))
+                .flatMap(Optional::stream)
+                .findFirst()
+                .<Exception>map(message -> new DevServerStartupException(message))
+                .orElse(e);
+    }
+
+    private static Optional<String> buildSchemaValidationMessage(Throwable error) {
+        Throwable schemaValidationFailure = findSchemaValidationFailure(error);
+        if (schemaValidationFailure == null) {
+            return Optional.empty();
+        }
+
+        String details = Optional.ofNullable(schemaValidationFailure.getMessage())
+                .map(String::trim)
+                .filter(message -> !message.isEmpty())
+                .orElse("Hibernate reported a schema validation error.");
+        return Optional.of(String.format(SCHEMA_VALIDATION_MESSAGE, details));
+    }
+
+    private static Throwable findSchemaValidationFailure(Throwable error) {
+        Throwable current = error;
+        while (current != null) {
+            String message = current.getMessage();
+            if (current instanceof SchemaManagementException
+                    || message != null && message.trim().startsWith(SCHEMA_VALIDATION_PREFIX)) {
+                return current;
+            }
+            current = current.getCause();
+        }
+        return null;
+    }
+
+}

src/main/java/teammates/ui/errorhandlers/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Contains handlers for errors that occur during dev server startup, and the factory to retrieve them.
+ */
+package teammates.ui.errorhandlers;

src/main/java/teammates/ui/exception/DevServerStartupException.java

@@ -0,0 +1,11 @@
+package teammates.ui.exception;
+
+/**
+ * Exception thrown when an error occurs during dev server startup.
+ */
+public class DevServerStartupException extends RuntimeException {
+    public DevServerStartupException(String message) {
+        // Null cause to avoid printing the stack trace twice.
+        super(message, null, true, false);
+    }
+}