diff --git a/base/src/main/java/de/staropensource/sosengine/base/Engine.java b/base/src/main/java/de/staropensource/sosengine/base/Engine.java
index 04d91d0..fbff927 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/Engine.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/Engine.java
@@ -92,7 +92,7 @@ public final class Engine implements SubsystemMainClass {
* @since 1-alpha0
*/
public Engine() {
- // Check if sos!engine is already loaded
+ // Only allow one instance
if (instance == null)
instance = this;
else {
@@ -201,15 +201,17 @@ public final class Engine implements SubsystemMainClass {
* @since 1-alpha0
*/
public void precomputeEventListeners() {
+ // Internal events
EventHelper.precomputeEventListeners(InternalEngineShutdownEvent.class);
+ // General events
EventHelper.precomputeEventListeners(EngineCrashEvent.class);
EventHelper.precomputeEventListeners(EngineShutdownEvent.class);
EventHelper.precomputeEventListeners(LogEvent.class);
}
/**
- * Starts base engine threads.
+ * Starts engine threads.
*
* @since 1-alpha1
*/
@@ -220,18 +222,21 @@ public final class Engine implements SubsystemMainClass {
/**
* Shuts the engine and JVM down.
*
- * @param exitCode the code to exit with, from 0-255
+ * @param exitCode code to exit with, from 0-255
* @since 1-alpha0
*/
public void shutdown(@Range(from = 0, to = 255) int exitCode) {
logger.info("Shutting engine down");
shuttingDown = true;
+
logger.verb("Notifiying classes about shutdown");
new EngineShutdownEvent().callEvent();
+
logger.verb("Notifying subsystems about shutdown");
new InternalEngineShutdownEvent().callEvent();
+
logger.verb("Shutting down JVM with code " + exitCode);
- Logger.flushLogMessages();
+ Logger.flushLogMessages(); // Flush all log messages before exiting
Runtime.getRuntime().exit(exitCode);
}
diff --git a/base/src/main/java/de/staropensource/sosengine/base/EngineConfiguration.java b/base/src/main/java/de/staropensource/sosengine/base/EngineConfiguration.java
index 74ead89..b55cd2d 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/EngineConfiguration.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/EngineConfiguration.java
@@ -252,6 +252,7 @@ public final class EngineConfiguration implements SubsystemConfiguration {
else
Logger.crash(new LogIssuer(getClass(), CodePart.ENGINE), "Tried initializing " + getClass().getName() + " twice");
+ // Load default configuration
loadDefaultConfiguration();
}
@@ -260,6 +261,7 @@ public final class EngineConfiguration implements SubsystemConfiguration {
// Define variables
PropertyParser parser = new PropertyParser(properties);
+ // Loop through all properties
for (String property : properties.stringPropertyNames()) {
// Check if property name starts with group
if (!property.startsWith(group)) continue;
@@ -267,7 +269,7 @@ public final class EngineConfiguration implements SubsystemConfiguration {
// Skip to important stuff
property = property.substring(group.length());
- // Match settings
+ // Overwrite matching settings
try {
switch (property) {
case "debug" -> debug = parser.getBoolean(group + property);
@@ -294,7 +296,7 @@ public final class EngineConfiguration implements SubsystemConfiguration {
} catch (NullPointerException ignored) {}
}
- // Disable all debug options if 'debug' is disabled
+ // Disable all debugging switches if 'debug' is disabled
if (!debug) {
debugEvents = false;
debugShortcodeConverter = false;
diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/Placeholder.java b/base/src/main/java/de/staropensource/sosengine/base/classes/Placeholder.java
index 611e6cd..26dcd0f 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/classes/Placeholder.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/classes/Placeholder.java
@@ -42,7 +42,7 @@ public interface Placeholder {
/**
* Replaces the placeholder with it's appropriate content.
*
- * @param text the text to process
+ * @param text text to process
* @return the processed text
* @since 1-alpha0
*/
diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemConfiguration.java b/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemConfiguration.java
index 86220fe..4bc590b 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemConfiguration.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemConfiguration.java
@@ -49,7 +49,7 @@ public interface SubsystemConfiguration {
* Loads the subsystem configuration from the specified {@link Properties}.
* Unless you want to allow configuration overriding, resetting the configuration using {@code loadDefaultConfiguration()} is advised.
*
- * @param properties the {@link Properties} object
+ * @param properties {@link Properties} object
* @see SubsystemConfiguration#loadDefaultConfiguration()
* @since 1-alpha0
*/
@@ -76,8 +76,8 @@ public interface SubsystemConfiguration {
/**
* Returns a configuration setting.
*
- * @param setting the setting name
- * @return the setting's value or {@code null} if not found
+ * @param setting setting name
+ * @return setting's value or {@code null} if not found
*/
Object getSetting(@NotNull String setting);
}
diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/helpers/EventHelper.java b/base/src/main/java/de/staropensource/sosengine/base/classes/helpers/EventHelper.java
index 5843348..71ee5fd 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/classes/helpers/EventHelper.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/classes/helpers/EventHelper.java
@@ -65,11 +65,12 @@ public class EventHelper {
* @since 1-alpha0
*/
public static void logCall(@NotNull Class extends Event> clazz, @NotNull Object ... arguments) {
+ // Print event call if event debugging is enabled
if (EngineConfiguration.getInstance().isDebugEvents())
if (arguments.length == 0)
- Logger.diag(new LogIssuer(clazz), "Event " + clazz.getName() + " called");
+ Logger.diag(new LogIssuer(clazz), "Event " + clazz.getName() + " emitted");
else
- Logger.diag(new LogIssuer(clazz), "Event " + clazz.getName() + " called with arguments " + ListFormatter.formatArray(arguments));
+ Logger.diag(new LogIssuer(clazz), "Event " + clazz.getName() + " emitted, passing arguments " + ListFormatter.formatArray(arguments));
}
/**
@@ -86,6 +87,7 @@ public class EventHelper {
if (forceScanning || !cachedEventListeners.containsKey(clazz)) {
// Scan entire classpath through Reflections library
+ // (enforced or not cached)
Reflections reflections = new Reflections(
new ConfigurationBuilder()
.setUrls(ClasspathHelper.forJavaClassPath())
@@ -100,7 +102,7 @@ public class EventHelper {
if (method.getAnnotation(EventListener.class).event() == clazz)
methods.add(method);
- // Sort 'methods' linked list
+ // Sort 'methods' linked list after event priority
methods.sort(Comparator.comparing(method0 -> method0.getAnnotation(EventListener.class).priority()));
} else
// 'forcedScanning' is false and matching event listeners are cached
@@ -147,7 +149,7 @@ public class EventHelper {
}
/**
- * Precomputes all event listeners listening on some event.
+ * Caches all event listeners listening on some event.
* Will recompute all event listeners if the specified event is already cached.
*
* @param clazz event listeners to (p)recompute, set to {@code null} to recompute all cached events
@@ -170,7 +172,7 @@ public class EventHelper {
/**
* Removes events from the event listener cache.
*
- * @param clazz event class to remove cached event listeners for, set to {@code null} to remove all cached event listeners
+ * @param clazz event class to remove cached event listeners for or {@code null} to remove all cached event listeners
* @since 1-alpha0
*/
public static void removePrecomputedEventListeners(@Nullable Class extends Event> clazz) {
diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/logging/LogIssuer.java b/base/src/main/java/de/staropensource/sosengine/base/classes/logging/LogIssuer.java
index 896f720..e088651 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/classes/logging/LogIssuer.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/classes/logging/LogIssuer.java
@@ -75,7 +75,7 @@ public class LogIssuer {
/**
* Constructor.
*
- * @param clazz the issuing class
+ * @param clazz issuing class
* @param additionalInformation additional information about the issuer
* @param codePart identifies to which part of the program the class belongs to
* @since 1-alpha0
@@ -90,7 +90,7 @@ public class LogIssuer {
/**
* Constructor.
*
- * @param clazz the issuing class
+ * @param clazz issuing class
* @param additionalInformation additional information about the issuer
* @since 1-alpha0
*/
@@ -104,8 +104,8 @@ public class LogIssuer {
/**
* Constructor.
*
- * @param clazz the issuing class
- * @param codePart identifies to which part of the program the class belongs to
+ * @param clazz issuing class
+ * @param codePart identifies to which part of the program the class belongs to
* @since 1-alpha0
*/
public LogIssuer(@NotNull Class> clazz, @NotNull CodePart codePart) {
@@ -117,7 +117,7 @@ public class LogIssuer {
/**
* Constructor.
*
- * @param clazz the issuing class
+ * @param clazz issuing class
* @since 1-alpha0
*/
public LogIssuer(@NotNull Class> clazz) {
diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/info/EngineInformation.java b/base/src/main/java/de/staropensource/sosengine/base/data/info/EngineInformation.java
index bb21500..0ae7b92 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/data/info/EngineInformation.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/data/info/EngineInformation.java
@@ -225,12 +225,12 @@ public final class EngineInformation {
return;
}
- // Load properties from gradle.properties
+ // Load properties from bundled gradle.properties
Properties properties = new Properties();
InputStream inputStream = this.getClass().getClassLoader().getResourceAsStream("gradle.properties");
if (inputStream == null) {
- logger.crash("Unable to load build information: InputStream is null");
+ logger.crash("Unable to load build information: The bundled gradle.properties file could not be found. Do symlinks work on the system that built this JAR?");
return;
}
diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/info/JvmInformation.java b/base/src/main/java/de/staropensource/sosengine/base/data/info/JvmInformation.java
index aeecd17..dd59ef3 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/data/info/JvmInformation.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/data/info/JvmInformation.java
@@ -48,10 +48,10 @@ public final class JvmInformation {
public static int getJavaVersion() {
String version = System.getProperty("java.version");
- if (version.startsWith("1."))
+ if (version.startsWith("1.")) // Omit "1." (if present)
version = version.substring(2, 3);
else {
- if (version.contains("."))
+ if (version.contains(".")) // Only get MAJOR version
version = version.substring(0, version.indexOf("."));
}
diff --git a/base/src/main/java/de/staropensource/sosengine/base/events/LogEvent.java b/base/src/main/java/de/staropensource/sosengine/base/events/LogEvent.java
index ab68dd6..5a85500 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/events/LogEvent.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/events/LogEvent.java
@@ -53,9 +53,9 @@ public final class LogEvent implements Event {
/**
* Calls the event and notifies all annotated methods.
*
- * @param level the log level
- * @param logIssuer the log issuer
- * @param message the log message
+ * @param level log level
+ * @param logIssuer log issuer
+ * @param message log message
* @since 1-alpha0
*/
public void callEvent(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String message) {
diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/CrashHandler.java b/base/src/main/java/de/staropensource/sosengine/base/logging/CrashHandler.java
index e7f50d6..307d94b 100644
--- a/base/src/main/java/de/staropensource/sosengine/base/logging/CrashHandler.java
+++ b/base/src/main/java/de/staropensource/sosengine/base/logging/CrashHandler.java
@@ -44,13 +44,6 @@ import java.util.*;
*/
@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" })
public final class CrashHandler {
- /**
- * Hopefully {@code false} :)
- * Note: Switching this to true might cause issues. Just don't do it ^^
- *
- * @since 1-alpha0
- */
- public static boolean crashed = false;
/**
* Contains the template used to print a crash report.
@@ -115,13 +108,12 @@ public final class CrashHandler {
* @since 1-alpha0
*/
public static void handleCrash(@NotNull LogIssuer logIssuer, @NotNull String message, @Nullable Throwable throwable) {
- crashed = true;
String base = crashTemplate;
- // Convert crashContent to String and replace %content% in crashTemplate with the result
+ // Replace '%content%' with crash content
base = base.replace("%content%", processCrashContent()); // This is so simple we don't need the PlaceholderEngine to do it for us
- // Execute LoggerImpl#prePlaceholder
+ // Invoke LoggerImpl#prePlaceholder
base = Logger.getLoggerImplementation().prePlaceholder(LogLevel.CRASH, logIssuer, base);
// Create list of temporary placeholders
@@ -140,13 +132,13 @@ public final class CrashHandler {
// Replace placeholders
base = PlaceholderEngine.getInstance().process(base, temporaryPlaceholders);
- // Execute LoggerImpl#postPlaceholder
+ // Invoke LoggerImpl#postPlaceholder
base = Logger.getLoggerImplementation().postPlaceholder(LogLevel.CRASH, logIssuer, base);
- // Print log message
+ // Print log message by invoking LoggerImpl#print
Logger.getLoggerImplementation().print(LogLevel.CRASH, logIssuer, base);
- // Send EngineCrash event
+ // Emit EngineCrashEvent
new EngineCrashEvent().callEvent();
// Shutdown (engine &) JVM
@@ -159,8 +151,8 @@ public final class CrashHandler {
/**
* Internal method for generating the crash message content. Do not call.
*
- * @param map the {@link LinkedHashMap} to process
- * @param indentationSize the indentation level
+ * @param map {@link LinkedHashMap} to process
+ * @param indentationSize indentation level
* @return crash content string
* @see CrashHandler#processCrashContent()
* @since 1-alpha0
@@ -170,11 +162,10 @@ public final class CrashHandler {
* We can safely ignore this as this method
* 1. checks data types as best as it can,
* 2. only works on a String and not on a File or something which could cause damage, and
- * 3. we can trust our own engine and the application not doing shit in here.
- * as an application or subsystem developer you'll likely want useful crash information.
+ * 3. we can trust our own engine and possibly subsystems not doing shit in here.
+ * As a subsystem developer you'll likely want useful crash information.
*
* But hey, if someone breaks this method (which may be possible idk didn't test it) then congrats!
- * If someone opens a pull requests wanting to "fix" this method, I'll happily decline it :)
*/
@NotNull
private static String processCrashContent(@NotNull LinkedHashMap