[#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,28 @@ public void lifeCycleStopped(LifeCycle event) {
         server.setHandler(webapp);
         server.setStopAtShutdown(true);
         server.addEventListener(customLifeCycleListener);
-
-        server.start();
+        webapp.setThrowUnavailableOnStartupException(true);
+
+        try {
+            server.start();
+        } catch (Exception e) {
+            stopServer(server);
+            DevServerStartupErrorHandler.throwIfHandled(e);
+            // Re-throw if the exception is not recognized as a dev server startup failure.
+            throw 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) {
+            throw new IllegalStateException("Failed to stop server after web application startup failure.", e);
+        }
+    }
+
 }

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

@@ -0,0 +1,28 @@
+package teammates.ui.errorhandlers;
+
+import java.util.Optional;
+
+import teammates.ui.exception.DevServerStartupException;
+
+/**
+ * Handles startup errors with dev-server-friendly messages where possible.
+ */
+public final class DevServerStartupErrorHandler {
+
+    private DevServerStartupErrorHandler() {
+        // Utility class
+    }
+
+    /**
+     * Throws a dev-server-friendly exception if a handler matches.
+     */
+    public static void throwIfHandled(Exception e) {
+        Optional<StartupErrorHandler> handler = DevServerStartupErrorHandlerFactory.getHandler(e);
+        if (handler.isEmpty()) {
+            return;
+        }
+
+        throw new DevServerStartupException(handler.get().buildErrorMessage(e));
+    }
+
+}

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

@@ -0,0 +1,45 @@
+package teammates.ui.errorhandlers;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Generates the matching {@link StartupErrorHandler} for a startup error.
+ */
+public final class DevServerStartupErrorHandlerFactory {
+
+    private static final List<Class<? extends StartupErrorHandler>> ERROR_HANDLERS = new ArrayList<>();
+
+    static {
+        map(SchemaValidationStartupErrorHandler.class);
+    }
+
+    private DevServerStartupErrorHandlerFactory() {
+        // Utility class
+    }
+
+    private static void map(Class<? extends StartupErrorHandler> errorHandlerClass) {
+        ERROR_HANDLERS.add(errorHandlerClass);
+    }
+
+    /**
+     * Returns the matching {@link StartupErrorHandler} for the startup error.
+     */
+    public static Optional<StartupErrorHandler> getHandler(Exception e) {
+        return ERROR_HANDLERS.stream()
+                .map(DevServerStartupErrorHandlerFactory::instantiate)
+                .filter(handler -> handler.canHandle(e))
+                .findFirst();
+    }
+
+    private static StartupErrorHandler instantiate(Class<? extends StartupErrorHandler> errorHandlerClass) {
+        try {
+            return errorHandlerClass.getDeclaredConstructor().newInstance();
+        } catch (Exception e) {
+            assert false : "Could not create the startup error handler " + errorHandlerClass.getSimpleName();
+            return null;
+        }
+    }
+
+}

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

@@ -0,0 +1,56 @@
+package teammates.ui.errorhandlers;
+
+import org.hibernate.tool.schema.spi.SchemaManagementException;
+
+/**
+ * Formats Hibernate schema validation failures for local development startup.
+ */
+public final class SchemaValidationStartupErrorHandler implements StartupErrorHandler {
+
+    private static final String SCHEMA_VALIDATION_PREFIX = "Schema-validation:";
+    private static final String 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",
+            "============================================================",
+            "");
+
+    @Override
+    public boolean canHandle(Exception e) {
+        return findSchemaValidationFailure(e) != null;
+    }
+
+    @Override
+    public String buildErrorMessage(Exception e) {
+        return String.format(MESSAGE, getSchemaValidationMessage(e));
+    }
+
+    private static String getSchemaValidationMessage(Exception e) {
+        Exception schemaValidationFailure = findSchemaValidationFailure(e);
+        if (schemaValidationFailure == null) {
+            return e.getMessage();
+        }
+        return schemaValidationFailure.getMessage().trim();
+    }
+
+    private static Exception findSchemaValidationFailure(Exception e) {
+        Exception current = e;
+        while (current != null) {
+            String message = current.getMessage();
+            if (current instanceof SchemaManagementException
+                    || message != null && message.trim().startsWith(SCHEMA_VALIDATION_PREFIX)) {
+                return current;
+            }
+            current = (Exception) current.getCause();
+        }
+        return null;
+    }
+
+}

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

@@ -0,0 +1,17 @@
+package teammates.ui.errorhandlers;
+
+/**
+ * Handles startup errors that can be formatted with dev-server-friendly messages.
+ */
+public interface StartupErrorHandler {
+
+    /**
+     * Returns whether this handler can format the given startup error.
+     */
+    boolean canHandle(Exception e);
+
+    /**
+     * Builds the dev-server-friendly message for the given startup error.
+     */
+    String buildErrorMessage(Exception e);
+}

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,10 @@
+package teammates.ui.exception;
+
+/**
+ * Exception thrown when an error occurs during dev server startup.
+ */
+public class DevServerStartupException extends RuntimeException {
+    public DevServerStartupException(String message) {
+        super(message, null, true, false);
+    }
+}

src/test/java/teammates/ui/devserverstartuperrorhandlers/DevServerStartupErrorHandlerFactoryTest.java

@@ -0,0 +1,36 @@
+package teammates.ui.devserverstartuperrorhandlers;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.hibernate.tool.schema.spi.SchemaManagementException;
+import org.testng.annotations.Test;
+
+import teammates.test.BaseTestCase;
+import teammates.ui.errorhandlers.DevServerStartupErrorHandlerFactory;
+import teammates.ui.errorhandlers.SchemaValidationStartupErrorHandler;
+import teammates.ui.errorhandlers.StartupErrorHandler;
+
+/**
+ * SUT: {@link DevServerStartupErrorHandlerFactory}.
+ */
+public class DevServerStartupErrorHandlerFactoryTest extends BaseTestCase {
+
+    @Test
+    public void testGetHandler_schemaValidationException_returnsSchemaValidationHandler() {
+        SchemaManagementException exception = new SchemaManagementException(
+                "Schema-validation: missing column [institute_id] in table [account_requests]");
+
+        StartupErrorHandler startupErrorHandler = DevServerStartupErrorHandlerFactory.getHandler(exception)
+                .orElseThrow();
+
+        assertTrue(startupErrorHandler instanceof SchemaValidationStartupErrorHandler);
+    }
+
+    @Test
+    public void testGetHandler_unknownException_returnsEmpty() {
+        RuntimeException exception = new RuntimeException("Failed to connect to database");
+
+        assertTrue(DevServerStartupErrorHandlerFactory.getHandler(exception).isEmpty());
+    }
+
+}

src/test/java/teammates/ui/devserverstartuperrorhandlers/DevServerStartupErrorHandlerTest.java

@@ -0,0 +1,44 @@
+package teammates.ui.devserverstartuperrorhandlers;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.hibernate.tool.schema.spi.SchemaManagementException;
+import org.testng.annotations.Test;
+
+import teammates.test.BaseTestCase;
+import teammates.ui.errorhandlers.DevServerStartupErrorHandler;
+import teammates.ui.errorhandlers.SchemaValidationStartupErrorHandler;
+import teammates.ui.exception.DevServerStartupException;
+
+/**
+ * SUT: {@link DevServerStartupErrorHandler}.
+ */
+public class DevServerStartupErrorHandlerTest extends BaseTestCase {
+
+    private static final String SCHEMA_VALIDATION_MESSAGE =
+            "Schema-validation: missing column [institute_id] in table [account_requests]";
+
+    @Test
+    public void testThrowIfHandled_schemaValidationException_throwsDevServerStartupException() {
+        SchemaManagementException exception = new SchemaManagementException(SCHEMA_VALIDATION_MESSAGE);
+        SchemaValidationStartupErrorHandler handler = new SchemaValidationStartupErrorHandler();
+
+        DevServerStartupException thrown = assertThrows(DevServerStartupException.class, () -> {
+            DevServerStartupErrorHandler.throwIfHandled(exception);
+        });
+
+        assertEquals(handler.buildErrorMessage(exception), thrown.getMessage());
+    }
+
+    @Test
+    public void testGetMessage_nonSchemaValidationException_returnsEmpty() {
+        RuntimeException exception = new RuntimeException("Failed to connect to database");
+
+        assertDoesNotThrow(() -> {
+            DevServerStartupErrorHandler.throwIfHandled(exception);
+        });
+    }
+
+}

src/test/java/teammates/ui/devserverstartuperrorhandlers/SchemaValidationStartupErrorHandlerTest.java

@@ -0,0 +1,55 @@
+package teammates.ui.devserverstartuperrorhandlers;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.hibernate.tool.schema.spi.SchemaManagementException;
+import org.testng.annotations.Test;
+
+import teammates.test.BaseTestCase;
+import teammates.ui.errorhandlers.SchemaValidationStartupErrorHandler;
+
+/**
+ * SUT: {@link SchemaValidationStartupErrorHandler}.
+ */
+public class SchemaValidationStartupErrorHandlerTest extends BaseTestCase {
+
+    private static final String SCHEMA_VALIDATION_MESSAGE =
+            "Schema-validation: missing column [institute_id] in table [account_requests]";
+
+    private final SchemaValidationStartupErrorHandler handler = new SchemaValidationStartupErrorHandler();
+
+    @Test
+    public void testCanHandle_directSchemaManagementException_returnsTrue() {
+        SchemaManagementException exception = new SchemaManagementException(SCHEMA_VALIDATION_MESSAGE);
+
+        assertTrue(handler.canHandle(exception));
+    }
+
+    @Test
+    public void testCanHandle_wrappedSchemaManagementException_returnsTrue() {
+        RuntimeException exception = new RuntimeException("Failed to build session factory",
+                new SchemaManagementException(SCHEMA_VALIDATION_MESSAGE));
+
+        assertTrue(handler.canHandle(exception));
+    }
+
+    @Test
+    public void testCanHandle_nonSchemaValidationException_returnsFalse() {
+        RuntimeException exception = new RuntimeException("Failed to connect to database");
+
+        assertFalse(handler.canHandle(exception));
+    }
+
+    @Test
+    public void testBuildErrorMessage_schemaValidationException_includesCommandDocsAndExactError() {
+        SchemaManagementException exception = new SchemaManagementException(SCHEMA_VALIDATION_MESSAGE);
+
+        String message = handler.buildErrorMessage(exception);
+
+        assertTrue(message.contains(SCHEMA_VALIDATION_MESSAGE));
+        assertTrue(message.contains("./gradlew liquibaseUpdate"));
+        assertTrue(message.contains("docs/how-to/schema-migration.md"));
+    }
+
+}

src/test/java/teammates/ui/devserverstartuperrorhandlers/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Contains test cases for {@link teammates.ui.errorhandlers} package.
+ */
+package teammates.ui.devserverstartuperrorhandlers;

src/test/resources/testng-component.xml

@@ -15,6 +15,7 @@
             <package name="teammates.logic.external.email" />
             <package name="teammates.logic.util" />
             <package name="teammates.storage.api" />
+            <package name="teammates.ui.devserverstartuperrorhandlers" />
             <package name="teammates.ui.request" />
             <package name="teammates.ui.servlets" />
             <package name="teammates.ui.webapi" />