Add ShutdownHandlers

base/src/main/java/de/staropensource/sosengine/base/Engine.java

@@ -20,6 +20,7 @@
 package de.staropensource.sosengine.base;
 
 import de.staropensource.sosengine.base.annotations.EngineSubsystem;
+import de.staropensource.sosengine.base.classes.ShutdownHandler;
 import de.staropensource.sosengine.base.classes.SubsystemClass;
 import de.staropensource.sosengine.base.classes.helpers.EventHelper;
 import de.staropensource.sosengine.base.data.information.EngineInformation;
@@ -37,6 +38,7 @@ import de.staropensource.sosengine.base.utility.DependencyResolver;
 import de.staropensource.sosengine.base.utility.Miscellaneous;
 import de.staropensource.sosengine.base.utility.PlaceholderEngine;
 import lombok.Getter;
+import lombok.Setter;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Range;
 import org.reflections.Reflections;
@@ -89,6 +91,47 @@ public final class Engine extends SubsystemClass {
      */
     private static LoggerInstance logger;
 
+    /**
+     * Contains if the engine is shutting down.
+     *
+     * @since v1-alpha1
+     * -- GETTER --
+     * Returns if the engine is shutting down.
+     *
+     * @return shutdown status
+     * @since v1-alpha1
+     */
+    @Getter
+    private boolean shuttingDown = false;
+
+    /**
+     * Contains the engine's shutdown handler.
+     * The shutdown handler is responsible for
+     * shutting down the JVM safely.
+     *
+     * @see ShutdownHandler
+     * @since v1-alpha2
+     * -- GETTER --
+     * Returns the engine's shutdown handler.
+     * The shutdown handler is responsible for
+     * shutting down the JVM safely.
+     *
+     * @return shutdown handler
+     * @see ShutdownHandler
+     * @since v1-alpha2
+     * -- SETTER --
+     * Sets the engine's shutdown handler.
+     * The shutdown handler is responsible for
+     * shutting down the JVM safely.
+     *
+     * @param shutdownHandler new shutdown handler
+     * @see ShutdownHandler
+     * @since v1-alpha2
+     */
+    @Getter
+    @Setter
+    private @NotNull ShutdownHandler shutdownHandler = new Engine.JvmShutdownHandler();
+
     /**
      * Contains a list of all registered subsystems.
      * The list is sorted after initialization order.
@@ -104,19 +147,6 @@ public final class Engine extends SubsystemClass {
     @Getter
     private @NotNull ImmutableLinkedList<@NotNull DependencySubsystemVector> subsystems = new ImmutableLinkedList<>();
 
-    /**
-     * Contains if the engine is shutting down.
-     *
-     * @since v1-alpha1
-     * -- GETTER --
-     * Returns if the engine is shutting down.
-     *
-     * @return shutdown status
-     * @since v1-alpha1
-     */
-    @Getter
-    private boolean shuttingDown = false;
-
     /**
      * Initializes the StarOpenSource Engine.
      *
@@ -248,6 +278,15 @@ public final class Engine extends SubsystemClass {
         EventHelper.cacheEvent(ThrowableCatchEvent.class);
     }
 
+    /**
+     * Starts engine threads.
+     *
+     * @since v1-alpha1
+     */
+    public void startThreads() {
+        Logger.startLoggingThread();
+    }
+
     /**
      * Collects all subsystems by their {@link EngineSubsystem} annotation.
      *
@@ -343,15 +382,6 @@ public final class Engine extends SubsystemClass {
         subsystems = new ImmutableLinkedList<>(order);
     }
 
-    /**
-     * Starts engine threads.
-     *
-     * @since v1-alpha1
-     */
-    public void startThreads() {
-        Logger.startLoggingThread();
-    }
-
     /**
      * Shuts the engine down.
      *
@@ -383,7 +413,7 @@ public final class Engine extends SubsystemClass {
         new InternalEngineShutdownEvent().callEvent();
 
         logger.verb("Shutting down JVM with code " + exitCode);
-        Runtime.getRuntime().exit(exitCode);
+        shutdownHandler.shutdown((short) exitCode);
     }
 
     /**
@@ -406,14 +436,31 @@ public final class Engine extends SubsystemClass {
     @Override
     public void initializeSubsystem() {}
 
-    /**
-     * Returns the {@link DependencyVector} for this subsystem.
-     *
-     * @see DependencyVector
-     * @since v1-alpha1
-     */
+    /** {@inheritDoc} */
     @Override
     public @NotNull DependencyVector getDependencyVector() {
         return new DependencyVector("engine", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString());
     }
+
+    /**
+     * The default shutdown handler, which causes the JVM to exit.
+     *
+     * @see ShutdownHandler
+     * @see System#exit(int)
+     * @since v1-alpha2
+     */
+    public static final class JvmShutdownHandler implements ShutdownHandler {
+        /**
+         * Constructs this class.
+         *
+         * @since v1-alpha2
+         */
+        public JvmShutdownHandler() {}
+
+        /** {@inheritDoc} */
+        @Override
+        public void shutdown(short exitCode) {
+            System.exit(exitCode);
+        }
+    }
 }

base/src/main/java/de/staropensource/sosengine/base/classes/ShutdownHandler.java

@@ -0,0 +1,42 @@
+/*
+ * STAROPENSOURCE ENGINE SOURCE FILE
+ * Copyright (c) 2024 The StarOpenSource Engine Contributors
+ * Licensed under the GNU Affero General Public License v3
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.staropensource.sosengine.base.classes;
+
+import de.staropensource.sosengine.base.Engine;
+import org.jetbrains.annotations.Range;
+
+/**
+ * Interface for custom shutdown handlers.
+ * <p>
+ * Shutdown handlers are responsible for shutting down
+ * the platform safely after the engine has shut down.
+ *
+ * @see Engine#setShutdownHandler(ShutdownHandler)
+ * @since v1-alpha2
+ */
+public interface ShutdownHandler {
+    /**
+     * Executes the shutdown handler.
+     *
+     * @param exitCode exit code
+     * @since v1-alpha2
+     */
+    void shutdown(@Range(from = 0, to = 255) short exitCode);
+}