From f383261ed981f85551fdf08cacbad6c4dc7951e2 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Wed, 31 Jul 2024 03:53:44 +0200 Subject: [PATCH] MASSIVE CODE CHANGE tl;dr I changed many Javadoc comments, some code, removed dumb or unused stuff and revamped the entire logging infrastructure by yeeting out LogIssuer and CodePart and much, much more --- ...mpl.java => AnsiLoggerImplementation.java} | 30 +- .../ansi/AnsiShortcodeConverter.java | 11 +- .../sosengine/ansi/AnsiSubsystem.java | 36 +- ansi/src/main/java/module-info.java | 2 +- .../staropensource/sosengine/base/Engine.java | 88 ++-- .../sosengine/base/EngineConfiguration.java | 127 ++--- .../base/annotations/EngineSubsystem.java | 9 +- .../base/annotations/EventListener.java | 21 +- .../base/annotations/package-info.java | 4 +- .../sosengine/base/classes/Configuration.java | 146 ++++++ .../sosengine/base/classes/Event.java | 5 +- .../sosengine/base/classes/LoggerImpl.java | 67 --- .../base/classes/LoggerImplementation.java | 75 +++ .../sosengine/base/classes/Placeholder.java | 9 +- .../base/classes/ShortcodeParserSkeleton.java | 64 ++- ...stemMainClass.java => SubsystemClass.java} | 39 +- .../base/classes/SubsystemConfiguration.java | 83 --- .../base/classes/VersioningSystem.java | 15 +- .../base/classes/helpers/EventHelper.java | 100 ++-- .../sosengine/base/classes/package-info.java | 4 +- .../EngineInformation.java | 138 ++--- .../{info => information}/JvmInformation.java | 77 +-- .../{info => information}/package-info.java | 4 +- .../sosengine/base/data/package-info.java | 2 +- .../FourNumberVersioningSystem.java | 33 +- .../versioning/OneNumberVersioningSystem.java | 9 +- .../versioning/SemanticVersioningSystem.java | 47 +- .../StarOpenSourceVersioningSystem.java | 42 +- .../ThreeNumberVersioningSystem.java | 26 +- .../versioning/TwoNumberVersioningSystem.java | 23 +- .../base/data/versioning/package-info.java | 2 +- .../base/events/EngineCrashEvent.java | 6 +- .../base/events/EngineShutdownEvent.java | 6 +- .../base/events/EngineSoftCrashEvent.java | 9 +- .../sosengine/base/events/LogEvent.java | 22 +- .../base/events/ThrowableCatchEvent.java | 8 +- .../sosengine/base/events/package-info.java | 2 +- .../base/exceptions/ParserException.java | 6 + .../TristateConversionException.java | 14 +- .../UnexpectedThrowableException.java | 9 +- .../dependency/DependencyCycleException.java | 5 +- .../UnmetDependenciesException.java | 22 +- .../exceptions/dependency/package-info.java | 2 +- .../base/exceptions/package-info.java | 2 +- .../reflection/IncompatibleTypeException.java | 13 +- ...tanceMethodFromStaticContextException.java | 2 +- .../reflection/InvalidMethodSignature.java | 11 + .../reflection/NoAccessException.java | 9 +- .../StaticInitializerException.java | 12 +- .../exceptions/reflection/package-info.java | 4 +- ...IncompatibleVersioningSystemException.java | 3 +- .../InvalidVersionStringException.java | 15 +- .../exceptions/versioning/package-info.java | 2 +- .../events/InternalEngineShutdownEvent.java | 9 +- .../sosengine/base/internal/package-info.java | 2 +- .../base/internal/placeholders/DateDay.java | 3 +- .../base/internal/placeholders/DateMonth.java | 3 +- .../base/internal/placeholders/DateYear.java | 3 +- .../placeholders/EngineDependencyJansi.java | 5 +- .../placeholders/EngineDependencyLwjgl.java | 5 +- .../EngineDependencyReflections.java | 5 +- .../placeholders/EngineDependencySlf4j.java | 5 +- .../placeholders/EngineGitBranch.java | 5 +- .../placeholders/EngineGitCommitHeader.java | 5 +- .../placeholders/EngineGitCommitIdLong.java | 5 +- .../placeholders/EngineGitCommitIdShort.java | 5 +- .../placeholders/EngineGitCommitTimeDay.java | 5 +- .../placeholders/EngineGitCommitTimeHour.java | 5 +- .../EngineGitCommitTimeMinute.java | 5 +- .../EngineGitCommitTimeMonth.java | 5 +- .../EngineGitCommitTimeSecond.java | 5 +- .../placeholders/EngineGitCommitTimeYear.java | 5 +- .../placeholders/EngineGitCommits.java | 5 +- .../placeholders/EngineGitCommitterEmail.java | 5 +- .../placeholders/EngineGitCommitterName.java | 5 +- .../internal/placeholders/EngineGitDirty.java | 7 +- .../internal/placeholders/EngineVersion.java | 3 +- .../placeholders/EngineVersionFork.java | 5 +- .../placeholders/EngineVersionType.java | 5 +- .../EngineVersionTyperelease.java | 5 +- .../placeholders/EngineVersionVersion.java | 5 +- .../internal/placeholders/JvmArguments.java | 5 +- .../placeholders/JvmImplementationName.java | 5 +- .../placeholders/JvmImplementationVendor.java | 5 +- .../JvmImplementationVersion.java | 5 +- .../base/internal/placeholders/JvmJava.java | 5 +- .../base/internal/placeholders/JvmUptime.java | 5 +- .../base/internal/placeholders/TimeEpoch.java | 3 +- .../base/internal/placeholders/TimeHour.java | 3 +- .../internal/placeholders/TimeMinute.java | 3 +- .../internal/placeholders/TimeSecond.java | 3 +- .../base/internal/placeholders/TimeZone.java | 3 +- .../{IssuerMessage.java => CrashMessage.java} | 11 +- .../crashhandler/IssuerClass.java | 19 +- .../{IssuerInfo.java => IssuerMetadata.java} | 26 +- ...{IssuerCodePart.java => IssuerOrigin.java} | 25 +- .../crashhandler/IssuerPackage.java | 19 +- .../placeholders/crashhandler/IssuerPath.java | 19 +- .../placeholders/crashhandler/Stacktrace.java | 6 +- .../crashhandler/StacktraceAll.java | 3 +- .../crashhandler/package-info.java | 2 +- .../placeholders/logger/LogClass.java | 17 +- .../placeholders/logger/LogColorPrimary.java | 3 +- .../logger/LogColorSecondary.java | 3 +- .../placeholders/logger/LogLevel.java | 3 +- .../placeholders/logger/LogMessage.java | 3 +- .../logger/{LogInfo.java => LogMetadata.java} | 26 +- .../{LogCodePart.java => LogOrigin.java} | 23 +- .../placeholders/logger/LogPackage.java | 17 +- .../internal/placeholders/logger/LogPath.java | 16 +- .../placeholders/logger/package-info.java | 2 +- .../internal/placeholders/package-info.java | 5 +- .../reflection/ReflectionAccessWidener.java | 34 +- .../internal/reflection/package-info.java | 2 +- .../types/DependencySubsystemVector.java | 31 +- .../base/internal/types/QueuedLogMessage.java | 71 +-- .../base/internal/types/package-info.java | 2 +- .../sosengine/base/logging/CrashHandler.java | 55 +- .../sosengine/base/logging/Logger.java | 197 +++---- .../base/logging/LoggerInstance.java | 225 ++++++-- ...pl.java => PlainLoggerImplementation.java} | 30 +- ...Impl.java => RawLoggerImplementation.java} | 32 +- .../logging/implementation/package-info.java | 3 +- .../sosengine/base/logging/package-info.java | 2 +- .../base/reflection/ClasspathAccess.java | 27 +- .../sosengine/base/reflection/Reflect.java | 20 +- .../base/reflection/ReflectionClass.java | 32 +- .../base/reflection/ReflectionField.java | 33 +- .../base/reflection/ReflectionMethod.java | 28 +- .../base/reflection/package-info.java | 4 +- .../base/types/DependencyVector.java | 27 +- .../sosengine/base/types/EventPriority.java | 20 +- .../sosengine/base/types/Tristate.java | 14 +- .../sosengine/base/types/VersionType.java | 8 +- .../types/immutable/ImmutableArrayList.java | 10 + .../types/immutable/ImmutableHashMap.java | 25 +- .../types/immutable/ImmutableHashSet.java | 10 + .../immutable/ImmutableLinkedHashMap.java | 25 +- .../types/immutable/ImmutableLinkedList.java | 15 +- .../base/types/immutable/package-info.java | 2 +- .../base/types/logging/LogIssuer.java | 128 ----- .../base/types/logging/LogLevel.java | 12 +- .../sosengine/base/types/logging/LogRule.java | 23 +- .../base/types/logging/LogRuleType.java | 3 +- .../base/types/logging/package-info.java | 3 +- .../sosengine/base/types/package-info.java | 2 +- .../base/types/reflection/ClassType.java | 2 +- .../types/reflection/VisibilityModifier.java | 6 +- .../base/types/reflection/package-info.java | 4 +- .../sosengine/base/types/vectors/Vec2d.java | 107 ++++ .../types/vectors/{Vec2.java => Vec2f.java} | 18 +- .../sosengine/base/types/vectors/Vec2i.java | 12 +- .../sosengine/base/types/vectors/Vec3d.java | 126 +++++ .../types/vectors/{Vec3.java => Vec3f.java} | 20 +- .../sosengine/base/types/vectors/Vec3i.java | 14 +- .../base/types/vectors/package-info.java | 2 +- .../base/utility/DependencyResolver.java | 23 +- .../sosengine/base/utility/ListFormatter.java | 12 +- .../sosengine/base/utility/Math.java | 17 +- .../sosengine/base/utility/Miscellaneous.java | 17 +- .../base/utility/PlaceholderEngine.java | 26 +- .../converter/EmptyShortcodeConverter.java | 9 +- .../base/utility/converter/package-info.java | 2 +- .../base/utility/parser/PropertyParser.java | 71 +-- .../base/utility/parser/StackTraceParser.java | 29 +- .../base/utility/parser/package-info.java | 3 +- .../sosengine/unittests/UnitConfig.java | 5 +- .../sosengine/unittests/UnitLogger.java | 43 +- .../sosengine/unittests/package-info.java | 4 +- base/src/main/java/module-info.java | 6 +- .../srctests/EngineConfigurationTest.java | 7 +- .../sosengine/base/srctests/TestBase.java | 2 +- build.gradle | 31 +- docs/docs/getting-started/initializing.md | 40 +- gradle.properties | 1 + .../graphics/glfw/GlfwSubsystem.java | 22 +- .../glfw/GlfwSubsystemConfiguration.java | 75 +-- .../graphics/glfw/callbacks/KeyCallback.java | 6 +- .../glfw/callbacks/MouseButtonCallback.java | 6 +- .../graphics/glfw/callbacks/package-info.java | 25 + .../glfw/classes/GlfwInternalClass.java | 41 +- .../glfw/classes/GlfwManagementClass.java | 22 +- .../graphics/glfw/classes/GlfwMonitor.java | 8 +- .../graphics/glfw/classes/GlfwWindow.java | 36 +- .../graphics/glfw/classes/WindowCallback.java | 6 +- .../graphics/glfw/classes/package-info.java | 25 + .../glfw/exceptions/package-info.java | 25 + .../sosengine/graphics/glfw/package-info.java | 2 +- .../graphics/glfw/types/GlfwPlatform.java | 6 +- .../graphics/glfw/types/package-info.java | 25 + graphics/glfw/src/main/java/module-info.java | 11 +- .../graphics/opengl/OpenGlInternalApi.java | 15 +- .../graphics/opengl/OpenGlManagement.java | 2 +- .../graphics/opengl/OpenGlSubsystem.java | 31 +- .../graphics/opengl/classes/OpenGlWindow.java | 15 +- .../opengl/classes/package-info.java} | 21 +- .../graphics/opengl/package-info.java | 2 +- .../opengl/src/main/java/module-info.java | 2 +- .../sosengine/graphics/GraphicsSubsystem.java | 88 ++-- .../GraphicsSubsystemConfiguration.java | 87 ++-- .../sosengine/graphics/classes/Monitor.java | 28 +- .../sosengine/graphics/classes/Window.java | 481 +++++++++--------- .../api/{ApiMainClass.java => ApiClass.java} | 25 +- .../classes/api/ApiInternalClass.java | 4 +- .../classes/api/ApiManagementClass.java | 20 +- .../graphics/classes/api/package-info.java | 25 + .../graphics/classes/package-info.java | 4 +- .../events/GraphicsApiErrorEvent.java | 4 +- .../events/GraphicsApiShutdownEvent.java | 2 + .../graphics/events/GraphicsErrorEvent.java | 11 +- .../sosengine/graphics/events/InputEvent.java | 15 +- .../graphics/events/package-info.java | 2 +- .../exceptions/InvalidMonitorException.java | 11 +- .../exceptions/NoMonitorsFoundException.java | 11 +- .../exceptions/NotOnMainThreadException.java | 2 +- .../WindowCreationFailureException.java | 3 +- .../graphics/exceptions/package-info.java | 28 + .../sosengine/graphics/package-info.java | 2 +- .../sosengine/graphics/types/input/Key.java | 3 +- .../graphics/types/input/KeyState.java | 2 +- .../graphics/types/input/package-info.java | 25 + .../graphics/types/package-info.java | 2 +- .../graphics/types/window/VsyncMode.java | 19 +- .../graphics/types/window/WindowMode.java | 17 +- .../graphics/types/window/package-info.java | 25 + graphics/src/main/java/module-info.java | 3 +- .../graphics/vulkan/VulkanSubsystem.java | 39 +- .../graphics/vulkan/package-info.java | 33 +- .../vulkan/src/main/java/module-info.java | 2 - .../slf4j_compat/CompatibilityLogger.java | 11 +- .../CompatibilityLoggerFactory.java | 12 +- .../CompatibilityLoggerProvider.java | 24 +- ...bsystem.java => Slf4jCompatSubsystem.java} | 53 +- .../sosengine/slf4j_compat/package-info.java | 5 +- slf4j-compat/src/main/java/module-info.java | 3 +- src/main/javadoc/overview.html | 5 +- .../sosengine/testapp/Main.java | 29 +- .../sosengine/testapp/package-info.java | 4 +- testapp/src/main/java/module-info.java | 2 +- 239 files changed, 2867 insertions(+), 2497 deletions(-) rename ansi/src/main/java/de/staropensource/sosengine/ansi/{AnsiLoggerImpl.java => AnsiLoggerImplementation.java} (64%) create mode 100644 base/src/main/java/de/staropensource/sosengine/base/classes/Configuration.java delete mode 100644 base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImpl.java create mode 100644 base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImplementation.java rename base/src/main/java/de/staropensource/sosengine/base/classes/{SubsystemMainClass.java => SubsystemClass.java} (66%) delete mode 100644 base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemConfiguration.java rename base/src/main/java/de/staropensource/sosengine/base/data/{info => information}/EngineInformation.java (77%) rename base/src/main/java/de/staropensource/sosengine/base/data/{info => information}/JvmInformation.java (66%) rename base/src/main/java/de/staropensource/sosengine/base/data/{info => information}/package-info.java (85%) rename base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/{IssuerMessage.java => CrashMessage.java} (83%) rename base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/{IssuerInfo.java => IssuerMetadata.java} (67%) rename base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/{IssuerCodePart.java => IssuerOrigin.java} (68%) rename base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/{LogInfo.java => LogMetadata.java} (67%) rename base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/{LogCodePart.java => LogOrigin.java} (70%) rename base/src/main/java/de/staropensource/sosengine/base/logging/implementation/{PlainLoggerImpl.java => PlainLoggerImplementation.java} (69%) rename base/src/main/java/de/staropensource/sosengine/base/logging/implementation/{RawLoggerImpl.java => RawLoggerImplementation.java} (66%) delete mode 100644 base/src/main/java/de/staropensource/sosengine/base/types/logging/LogIssuer.java create mode 100644 base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2d.java rename base/src/main/java/de/staropensource/sosengine/base/types/vectors/{Vec2.java => Vec2f.java} (90%) create mode 100644 base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3d.java rename base/src/main/java/de/staropensource/sosengine/base/types/vectors/{Vec3.java => Vec3f.java} (90%) create mode 100644 graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/package-info.java create mode 100644 graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/package-info.java create mode 100644 graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/exceptions/package-info.java create mode 100644 graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/package-info.java rename graphics/{vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/events/GraphicsErrorEvent.java => opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/package-info.java} (60%) rename graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/{ApiMainClass.java => ApiClass.java} (81%) create mode 100644 graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/package-info.java create mode 100644 graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/package-info.java create mode 100644 graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/package-info.java create mode 100644 graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/package-info.java rename base/src/main/java/de/staropensource/sosengine/base/types/CodePart.java => graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/package-info.java (50%) rename slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/{Slf4jCompatibilitySubsystem.java => Slf4jCompatSubsystem.java} (55%) diff --git a/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiLoggerImpl.java b/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiLoggerImplementation.java similarity index 64% rename from ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiLoggerImpl.java rename to ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiLoggerImplementation.java index 5445b3e..2881b34 100644 --- a/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiLoggerImpl.java +++ b/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiLoggerImplementation.java @@ -20,50 +20,46 @@ package de.staropensource.sosengine.ansi; import de.staropensource.sosengine.base.EngineConfiguration; -import de.staropensource.sosengine.base.classes.LoggerImpl; +import de.staropensource.sosengine.base.classes.LoggerImplementation; import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; import org.fusesource.jansi.Ansi; import org.fusesource.jansi.AnsiConsole; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** - * Parses and prints colored log output using the Jansi library. + * Prints colored log output using the Jansi library. * * @see Logger - * @see LoggerImpl - * @since v1-alpha0 + * @see LoggerImplementation + * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) -public class AnsiLoggerImpl implements LoggerImpl { +public class AnsiLoggerImplementation implements LoggerImplementation { /** * Constructs this class. * - * @since v1-alpha0 + * @since v1-alpha2 */ - public AnsiLoggerImpl() {} + public AnsiLoggerImplementation() {} /** {@inheritDoc} */ - @NotNull @Override - public String prePlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String message) { - // No modifications necessary - return message; + public @NotNull String prePlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { + return format; // No modifications necessary } /** {@inheritDoc} */ - @NotNull @Override - public String postPlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format) { - // No modifications necessary - return format; + public @NotNull String postPlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { + return format; // No modifications necessary } /** {@inheritDoc} */ @SuppressWarnings({ "resource" }) // Using try-with-resources will cause issues here @Override - public void print(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format) { + public void print(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { // Convert to Ansi Ansi output = new AnsiShortcodeConverter(format, true).getAnsi(); diff --git a/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiShortcodeConverter.java b/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiShortcodeConverter.java index 943ce74..8977aab 100644 --- a/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiShortcodeConverter.java +++ b/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiShortcodeConverter.java @@ -28,17 +28,17 @@ import org.jetbrains.annotations.NotNull; * Converts shortcodes such as {@code } or {@code } into a usable {@link Ansi} escape sequence. * * @see ShortcodeParserSkeleton - * @since v1-alpha0 + * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public final class AnsiShortcodeConverter extends ShortcodeParserSkeleton { /** * Constructs this class. * - * @param string string to convert + * @param string string to convert * @param ignoreInvalidEscapes will ignore invalid escapes and print treat them like regular text * @throws ParserException when parsing failed - * @since v1-alpha0 + * @since v1-alpha2 */ public AnsiShortcodeConverter(@NotNull String string, boolean ignoreInvalidEscapes) throws ParserException { super(string, ignoreInvalidEscapes); @@ -48,10 +48,9 @@ public final class AnsiShortcodeConverter extends ShortcodeParserSkeleton { * Returns the parsed string as an {@link Ansi} sequence. * * @return {@link Ansi} sequence - * @since v1-alpha0 + * @since v1-alpha2 */ - @NotNull - public Ansi getAnsi() { + public @NotNull Ansi getAnsi() { Ansi ansi = Ansi.ansi(); for (String component : components) diff --git a/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiSubsystem.java b/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiSubsystem.java index 877140d..075083b 100644 --- a/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiSubsystem.java +++ b/ansi/src/main/java/de/staropensource/sosengine/ansi/AnsiSubsystem.java @@ -20,71 +20,63 @@ package de.staropensource.sosengine.ansi; import de.staropensource.sosengine.base.annotations.EngineSubsystem; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.classes.SubsystemClass; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.DependencyVector; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import lombok.Getter; import org.jetbrains.annotations.NotNull; /** * Main object for the ANSI Compatibility subsystem. * - * @since v1-alpha0 + * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public final class AnsiSubsystem implements SubsystemMainClass { +public final class AnsiSubsystem extends SubsystemClass { /** * Contains the class instance. * - * @since v1-alpha0 - * + * @since v1-alpha2 * -- GETTER -- * Returns the class instance. * * @return class instance unless the subsystem is uninitialized - * @since v1-alpha0 + * @since v1-alpha2 */ @Getter private static AnsiSubsystem instance = null; - /** {@inheritDoc} */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); - /** * Constructs this subsystem. + * + * @since v1-alpha2 */ public AnsiSubsystem() { // Check if subsystem has already initialized if (instance == null) instance = this; - else { - instance.logger.crash("The subsystem tried to initialize twice"); - } + else + logger.crash("Only one instance of this class is allowed, use getInstance() instead of creating a new instance"); } /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "ansi"; } /** {@inheritDoc} */ @Override public void initializeSubsystem() { - Logger.setLoggerImplementation(new AnsiLoggerImpl()); + Logger.setLoggerImplementation(new AnsiLoggerImplementation()); } /** {@inheritDoc} */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector("ansi", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString()); } } diff --git a/ansi/src/main/java/module-info.java b/ansi/src/main/java/module-info.java index a2bb3a4..aa9cefe 100644 --- a/ansi/src/main/java/module-info.java +++ b/ansi/src/main/java/module-info.java @@ -1,5 +1,5 @@ /** - * Defines the ANSI subsystem, allowing the engine to + * The ANSI subsystem, allowing the engine to * use ANSI escape codes using the Jansi library. * * @since v1-alpha2 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 47c30c8..ecf2cf7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/Engine.java +++ b/base/src/main/java/de/staropensource/sosengine/base/Engine.java @@ -20,9 +20,9 @@ package de.staropensource.sosengine.base; import de.staropensource.sosengine.base.annotations.EngineSubsystem; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; +import de.staropensource.sosengine.base.classes.SubsystemClass; import de.staropensource.sosengine.base.classes.helpers.EventHelper; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.events.*; import de.staropensource.sosengine.base.exceptions.dependency.UnmetDependenciesException; @@ -31,10 +31,8 @@ import de.staropensource.sosengine.base.internal.types.DependencySubsystemVector import de.staropensource.sosengine.base.logging.CrashHandler; import de.staropensource.sosengine.base.logging.Logger; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.DependencyVector; import de.staropensource.sosengine.base.types.immutable.ImmutableLinkedList; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.DependencyResolver; import de.staropensource.sosengine.base.utility.Miscellaneous; import de.staropensource.sosengine.base.utility.PlaceholderEngine; @@ -49,24 +47,22 @@ import org.reflections.util.ConfigurationBuilder; import java.util.*; /** - * sos!engine management object.
- * It is responsible for the base engine initialization. + * Main class of the sos!engine. * * @see EngineConfiguration * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public final class Engine implements SubsystemMainClass { +public final class Engine extends SubsystemClass { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * - * @return class instance unless the engine is uninitialized + * @return class instance unless {@link Engine} is uninitialized * @since v1-alpha0 */ @Getter @@ -76,7 +72,6 @@ public final class Engine implements SubsystemMainClass { * Contains the thread group of the engine. * * @since v1-alpha2 - * * -- GETTER -- * Returns the thread group of the engine. * @@ -87,19 +82,18 @@ public final class Engine implements SubsystemMainClass { private static final ThreadGroup threadGroup = new ThreadGroup("sos!engine"); /** - * Logger instance. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance * @since v1-alpha0 */ - private LoggerInstance logger; + private static LoggerInstance logger; /** * Contains a list of all registered subsystems. * The list is sorted after initialization order. * * @since v1-alpha1 - * * -- GETTER -- * Returns a list of all registered subsystems. * The list is sorted after initialization order. @@ -107,19 +101,17 @@ public final class Engine implements SubsystemMainClass { * @return subsystem list * @since v1-alpha1 */ - @NotNull @Getter - private ImmutableLinkedList<@NotNull DependencySubsystemVector> subsystems = new ImmutableLinkedList<>(); + private @NotNull ImmutableLinkedList<@NotNull DependencySubsystemVector> subsystems = new ImmutableLinkedList<>(); /** - * Indicates if the engine is shutting down. + * Contains if the engine is shutting down. * * @since v1-alpha1 - * * -- GETTER -- * Returns if the engine is shutting down. * - * @return if the engine is shutting down + * @return shutdown status * @since v1-alpha1 */ @Getter @@ -138,18 +130,18 @@ public final class Engine implements SubsystemMainClass { return; long initTime = Miscellaneous.measureExecutionTime(() -> { - // Initialize variables - logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); - - // Initialize EngineConfiguration and load it + // Initialize engine configuration new EngineConfiguration(); EngineConfiguration.getInstance().loadConfiguration(); initializeClasses(); // Initialize classes populateCrashContent(); // Populate crash content - precomputeEventListeners(); // Precompute event listeners + cacheEvents(); // Cache event listeners startThreads(); // Start threads + // Set the logger instance + logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").setMetadata(EngineInformation.getVersioningCodename()).build(); + // Perform automatic subsystem initialization if (EngineConfiguration.getInstance().isOptimizeSubsystemInitialization()) { collectSubsystems(); // Collect subsystems @@ -172,14 +164,13 @@ public final class Engine implements SubsystemMainClass { * @since v1-alpha0 */ private void initializeClasses() { - // Sorted in rough order of dependence new PlaceholderEngine(); EngineInformation.updateVariables(); } /** - * This method populates the Crash Handler's content with the default set of content. + * This method populates {@link CrashHandler#crashContent} with content. * * @see CrashHandler#getCrashContent() * @since v1-alpha0 @@ -188,10 +179,10 @@ public final class Engine implements SubsystemMainClass { private void populateCrashContent() { // Issuer Map<@NotNull String, @NotNull String> crashContentIssuer = new LinkedHashMap<>(); - crashContentIssuer.put("Code part", "%issuer_code_part%"); + crashContentIssuer.put("Code part", "%issuer_origin%"); crashContentIssuer.put("Classpath", "%issuer_path%"); - crashContentIssuer.put("Additional information", "%issuer_info%"); - crashContentIssuer.put("Message", "%issuer_message%"); + crashContentIssuer.put("Additional information", "%issuer_metadata%"); + crashContentIssuer.put("Message", "%crash_message%"); // Engine -> Dependencies -> base Map<@NotNull String, @NotNull String> crashContentEngineDependenciesBase = new LinkedHashMap<>(); @@ -241,20 +232,20 @@ public final class Engine implements SubsystemMainClass { } /** - * Precomputes all base engine events. + * Caches all base engine events. * * @since v1-alpha0 */ - private void precomputeEventListeners() { + private void cacheEvents() { // Internal events - EventHelper.precomputeEventListeners(InternalEngineShutdownEvent.class); + EventHelper.cacheEvent(InternalEngineShutdownEvent.class); // General events - EventHelper.precomputeEventListeners(EngineCrashEvent.class); - EventHelper.precomputeEventListeners(EngineShutdownEvent.class); - EventHelper.precomputeEventListeners(EngineSoftCrashEvent.class); - EventHelper.precomputeEventListeners(LogEvent.class); - EventHelper.precomputeEventListeners(ThrowableCatchEvent.class); + EventHelper.cacheEvent(EngineCrashEvent.class); + EventHelper.cacheEvent(EngineShutdownEvent.class); + EventHelper.cacheEvent(EngineSoftCrashEvent.class); + EventHelper.cacheEvent(LogEvent.class); + EventHelper.cacheEvent(ThrowableCatchEvent.class); } /** @@ -280,13 +271,13 @@ public final class Engine implements SubsystemMainClass { try { // Create new instance Object initializedClassRaw = clazz.getDeclaredConstructor().newInstance(); - SubsystemMainClass initializedClass = null; + SubsystemClass initializedClass = null; // Check if class implements SubsystemMainClass - if (initializedClassRaw instanceof SubsystemMainClass subsystemInstance) + if (initializedClassRaw instanceof SubsystemClass subsystemInstance) initializedClass = subsystemInstance; else - logger.crash("Failed to initialize subsystem " + clazz.getName() + ": Does not implement " + SubsystemMainClass.class.getName()); + logger.crash("Failed to initialize subsystem " + clazz.getName() + ": Does not implement " + SubsystemClass.class.getName()); //noinspection DataFlowIssue // the crash call will prevent a NullPointerException subsystemsMutable.add(new DependencySubsystemVector(initializedClass.getDependencyVector(), initializedClass)); @@ -362,7 +353,7 @@ public final class Engine implements SubsystemMainClass { } /** - * Shuts the engine and JVM down. + * Shuts the engine down. * * @param exitCode code to exit with, from 0-255 * @since v1-alpha0 @@ -396,20 +387,18 @@ public final class Engine implements SubsystemMainClass { } /** - * Shuts the engine and JVM down. + * Shuts the engine down. * * @since v1-alpha0 */ public void shutdown() { - shutdown(0); + if (instance != null) + instance.shutdown(0); } - /** - * {@inheritDoc} - */ - @NotNull + /** {@inheritDoc} */ @Override - public String getName() { + public @NotNull String getName() { return "base"; } @@ -423,9 +412,8 @@ public final class Engine implements SubsystemMainClass { * @see DependencyVector * @since v1-alpha1 */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector("engine", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString()); } } 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 7f18853..785bbbc 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/EngineConfiguration.java +++ b/base/src/main/java/de/staropensource/sosengine/base/EngineConfiguration.java @@ -20,14 +20,12 @@ package de.staropensource.sosengine.base; import de.staropensource.sosengine.base.classes.ShortcodeParserSkeleton; -import de.staropensource.sosengine.base.classes.SubsystemConfiguration; +import de.staropensource.sosengine.base.classes.Configuration; import de.staropensource.sosengine.base.classes.helpers.EventHelper; import de.staropensource.sosengine.base.logging.CrashHandler; import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; -import de.staropensource.sosengine.base.types.vectors.Vec2; +import de.staropensource.sosengine.base.types.vectors.Vec2f; import de.staropensource.sosengine.base.utility.parser.PropertyParser; import lombok.Getter; import org.jetbrains.annotations.NotNull; @@ -42,7 +40,7 @@ import java.util.Properties; * responsible for loading them into memory from {@link Properties} objects. *

* Now you might ask why we didn't go with the string-based approach. - * The answer is simple: It's a maintenance and documentation burden. + * The answer is simple: It's a maintenance burden. * Having various settings strings scattered across many classes will cause * trouble at some point, which will cause some strings to be undocumented * or have an inconsistent naming scheme. Containing settings as variables in @@ -50,14 +48,13 @@ import java.util.Properties; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter -public final class EngineConfiguration implements SubsystemConfiguration { +public final class EngineConfiguration extends Configuration { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -68,26 +65,23 @@ public final class EngineConfiguration implements SubsystemConfiguration { private static EngineConfiguration instance; /** - * Defines the group every property must start with to be recognized as a subsystem configuration setting. + * Contains the group in which setting overrides must begin with.. * * @since v1-alpha0 - * * -- GETTER -- - * Returns the group that every property must start with to be recognized as a subsystem configuration setting. + * Returns the group in which setting overrides must begin with. * * @return property group * @since v1-alpha0 */ - @NotNull @Getter - private static final String group = "sosengine.base."; + private final @NotNull String group = "sosengine.base."; /** - * If enabled, allows for unintentional behaviour and excess logging.
+ * If enabled, allows for unintentional behaviour and excess logging. * Unless you want to debug or work on a sensitive part of the engine, don't enable this! * * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #debug}. * @@ -102,7 +96,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * * @see EventHelper#logCall(Class, Object...) * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #debugEvents}. * @@ -118,7 +111,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * * @see ShortcodeParserSkeleton * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #debugShortcodeConverter}. * @@ -135,7 +127,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * @see ShortcodeParserSkeleton * @see #loggerLevel * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #errorShortcodeConverter}. * @@ -152,7 +143,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * @see #loggerPollingSpeed * @see Thread * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #optimizeLogging}. * @@ -168,7 +158,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * * @see VirtualThread * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #optimizeEvents}. * @@ -188,7 +177,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * * @see Engine * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #optimizeSubsystemInitialization}. * @@ -199,11 +187,10 @@ public final class EngineConfiguration implements SubsystemConfiguration { private boolean optimizeSubsystemInitialization; /** - * Determines which logger levels are allowed by setting the minimum logger level. + * Contains which logger levels are allowed by setting the minimum logger level. * * @see Logger * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #loggerLevel}. * @@ -218,7 +205,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * * @see Logger * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #loggerTemplate} * @@ -229,12 +215,11 @@ public final class EngineConfiguration implements SubsystemConfiguration { private String loggerTemplate; /** - * If enabled, the JVM will immediately shutdown on an engine crash. This will prevent shutdown hooks from executing.
+ * If enabled, the JVM will immediately shutdown on an engine crash. This will prevent shutdown hooks from executing. * Note: This will also prevent Jansi and potentially other libraries from removing temporary native libraries at shutdown. * * @see CrashHandler * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #loggerImmediateShutdown}. * @@ -249,7 +234,6 @@ public final class EngineConfiguration implements SubsystemConfiguration { * instead of the standard error for logging {@code ERROR} and {@code CRASH}. * * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #loggerForceStandardOutput}. * @@ -260,12 +244,11 @@ public final class EngineConfiguration implements SubsystemConfiguration { private boolean loggerForceStandardOutput; /** - * Determines how fast the logging thread will poll for queued messages. + * Contains how fast the logging thread will poll for queued messages. * Only applies if {@code optimizeLogging} is turned on. * * @see #optimizeLogging * @since v1-alpha1 - * * -- GETTER -- * Gets the value for {@link #loggerForceStandardOutput}. * @@ -278,13 +261,12 @@ public final class EngineConfiguration implements SubsystemConfiguration { /** * Will truncate the path of types when using their {@code toString} method. *

- * Here's an example: Lets say that you have a {@link Vec2} and to convert it - * to a String, which you can do with {@link Vec2#toString()}. With this flag disabled + * Here's an example: Lets say that you have a {@link Vec2f} and to convert it + * to a String, which you can do with {@link Vec2f#toString()}. With this flag disabled * it would return {@code de.staropensource.sosengine.base.types.vectors.Vec2(x=64 y=64)}, * with it however it would be {@code Vec2(x=64 y=64)}, which is much smaller. * * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #hideFullTypePath}. * @@ -301,60 +283,53 @@ public final class EngineConfiguration implements SubsystemConfiguration { * @since v1-alpha0 */ public EngineConfiguration() { + super("ENGINE"); // TODO Wait for flexible constructor bodies (JEP 482) to be implemented into the JVM as a stable feature. We don't want to use preview features in production code. + // Only allow one instance if (instance == null) instance = this; else - Logger.crash(new LogIssuer(getClass(), CodePart.ENGINE), "Tried initializing " + getClass().getName() + " twice"); + logger.crash("Only one instance of this class is allowed, use getInstance() instead of creating a new instance"); // Load default configuration loadDefaultConfiguration(); } /** {@inheritDoc} */ - public synchronized void loadConfiguration(@NotNull Properties properties) { - // Define variables - PropertyParser parser = new PropertyParser(properties); + @Override + protected void matchProperty(@NotNull PropertyParser parser, @NotNull String property) { + try { + switch (property) { + case "debug" -> debug = parser.getBoolean(group + property); + case "debugEvents" -> debugEvents = parser.getBoolean(group + property); + case "debugShortcodeConverter" -> debugShortcodeConverter = parser.getBoolean(group + property); - // Loop through all properties - for (String property : properties.stringPropertyNames()) { - // Check if property name starts with group - if (!property.startsWith(group)) - continue; + case "errorShortcodeConverter" -> errorShortcodeConverter = parser.getBoolean(group + property); - // Skip to important stuff - property = property.substring(group.length()); + case "optimizeLogging" -> optimizeLogging = parser.getBoolean(group + property); + case "optimizeEvents" -> optimizeEvents = parser.getBoolean(group + property); + case "optimizeSubsystemInitialization" -> optimizeSubsystemInitialization = parser.getBoolean(group + property); - // Overwrite matching settings - try { - switch (property) { - case "debug" -> debug = parser.getBoolean(group + property); - case "debugEvents" -> debugEvents = parser.getBoolean(group + property); - case "debugShortcodeConverter" -> debugShortcodeConverter = parser.getBoolean(group + property); - - case "errorShortcodeConverter" -> errorShortcodeConverter = parser.getBoolean(group + property); - - case "optimizeLogging" -> optimizeLogging = parser.getBoolean(group + property); - case "optimizeEvents" -> optimizeEvents = parser.getBoolean(group + property); - case "optimizeSubsystemInitialization" -> optimizeSubsystemInitialization = parser.getBoolean(group + property); - - case "loggerLevel" -> { - try { - loggerLevel = LogLevel.valueOf(parser.getString(group + property).toUpperCase()); - } catch (IllegalArgumentException ignored) { - System.out.println("Logger level " + parser.getString(group + property) + " is not valid"); - } + case "loggerLevel" -> { + try { + loggerLevel = LogLevel.valueOf(parser.getString(group + property).toUpperCase()); + } catch (IllegalArgumentException ignored) { + System.out.println("Logger level " + parser.getString(group + property) + " is not valid"); } - case "loggerTemplate" -> loggerTemplate = parser.getString(group + property); - case "loggerImmediateShutdown" -> loggerImmediateShutdown = parser.getBoolean(group + property); - case "loggerForceStandardOutput" -> loggerForceStandardOutput = parser.getBoolean(group + property); - case "loggerPollingSpeed" -> loggerPollingSpeed = parser.getInteger(group + property, true); - - case "hideFullTypePath" -> hideFullTypePath = parser.getBoolean(group + property); } - } catch (NullPointerException ignored) {} - } + case "loggerTemplate" -> loggerTemplate = parser.getString(group + property); + case "loggerImmediateShutdown" -> loggerImmediateShutdown = parser.getBoolean(group + property); + case "loggerForceStandardOutput" -> loggerForceStandardOutput = parser.getBoolean(group + property); + case "loggerPollingSpeed" -> loggerPollingSpeed = parser.getInteger(group + property, true); + case "hideFullTypePath" -> hideFullTypePath = parser.getBoolean(group + property); + } + } catch (NullPointerException ignored) {} + } + + /** {@inheritDoc} */ + @Override + protected void processSettings(@NotNull PropertyParser parser) { // Disable all debugging switches if 'debug' is disabled if (!debug) { debugEvents = false; @@ -363,12 +338,8 @@ public final class EngineConfiguration implements SubsystemConfiguration { } /** {@inheritDoc} */ - public synchronized void loadConfiguration() { - loadConfiguration(System.getProperties()); - } - - /** {@inheritDoc} */ - public synchronized void loadDefaultConfiguration() { + @Override + public void loadDefaultConfiguration() { debug = false; debugEvents = false; debugShortcodeConverter = false; @@ -389,8 +360,8 @@ public final class EngineConfiguration implements SubsystemConfiguration { } /** {@inheritDoc} */ - @Nullable - public Object getSetting(@NotNull String setting) { + @Override + public @Nullable Object getSetting(@NotNull String setting) { switch (setting) { case "debug" -> { return debug; } case "debugEvents" -> { return debugEvents; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/annotations/EngineSubsystem.java b/base/src/main/java/de/staropensource/sosengine/base/annotations/EngineSubsystem.java index 290da87..0b36bf7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/annotations/EngineSubsystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/annotations/EngineSubsystem.java @@ -19,16 +19,15 @@ package de.staropensource.sosengine.base.annotations; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; +import de.staropensource.sosengine.base.classes.SubsystemClass; import java.lang.annotation.*; /** - * This annotation marks a class as a subsystem main class. - *

- * Make sure your subsystem implements {@link SubsystemMainClass}. + * Marks a class as a subsystem main class. + * Make sure your subsystem implements {@link SubsystemClass}. * - * @see SubsystemMainClass + * @see SubsystemClass * @since v1-alpha1 */ @SuppressWarnings("unused") diff --git a/base/src/main/java/de/staropensource/sosengine/base/annotations/EventListener.java b/base/src/main/java/de/staropensource/sosengine/base/annotations/EventListener.java index 5665c83..ff9eca1 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/annotations/EventListener.java +++ b/base/src/main/java/de/staropensource/sosengine/base/annotations/EventListener.java @@ -26,7 +26,8 @@ import org.jetbrains.annotations.NotNull; import java.lang.annotation.*; /** - * This annotation allows methods to listen on certain events. + * Marks a method as an event listener, allowing it + * to respond to an events when it is emitted. * * @since v1-alpha0 */ @@ -36,18 +37,20 @@ import java.lang.annotation.*; @Documented public @interface EventListener { /** - * The event to listen for. + * Specifies the event to listen for. * - * @return the event the method listens for + * @return event to listen on + * @see Event + * @since v1-alpha0 */ - @NotNull - Class event(); + @NotNull Class event(); /** - * The priority of the event. + * Specifies the priority of the event. * - * @return the event priority + * @return event priority + * @see EventPriority + * @since v1-alpha0 */ - @NotNull - EventPriority priority() default EventPriority.DEFAULT; + @NotNull EventPriority priority() default EventPriority.DEFAULT; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/annotations/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/annotations/package-info.java index 66a47e2..4134dea 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/annotations/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/annotations/package-info.java @@ -18,8 +18,8 @@ */ /** - * Contains annotations that are used by the engine - * to dynamically invoke methods or register classes. + * Annotations used by the sos!engine to access + * classes and methods using reflection. * * @since v1-alpha0 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/Configuration.java b/base/src/main/java/de/staropensource/sosengine/base/classes/Configuration.java new file mode 100644 index 0000000..a7aac3b --- /dev/null +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/Configuration.java @@ -0,0 +1,146 @@ +/* + * 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 . + */ + +package de.staropensource.sosengine.base.classes; + +import de.staropensource.sosengine.base.logging.LoggerInstance; +import de.staropensource.sosengine.base.utility.parser.PropertyParser; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +import java.util.Properties; + +/** + * Interface for implementing configuration classes. + *

+ * Configuration classes use {@link Properties} objects to modify + * their settings as they can be supplied to the JVM's arguments + * and can be written to and read from during runtime. + * + * @since v1-alpha2 + */ +@SuppressWarnings({ "unused" }) +public abstract class Configuration { + /** + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha1 + */ + protected final @NotNull LoggerInstance logger; + + /** + * Constructs this class. + * + * @param origin see {@link LoggerInstance.Builder#setOrigin(String)} + * @since v1-alpha2 + */ + public Configuration(@NotNull String origin) { + // Set logger instance + logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin(origin).build(); + + // Load default configuration + loadDefaultConfiguration(); + } + + /** + * Loads all settings from the specified {@link Properties} object. + * Unless you want to override settings, consider invoking {@link #loadDefaultConfiguration()} first. + * + * @param properties {@link Properties} to read from + * @see #loadDefaultConfiguration() + * @since v1-alpha2 + */ + public void loadConfiguration(@NotNull Properties properties) { + PropertyParser parser = new PropertyParser(properties); + + // Loop through all properties + for (String property : properties.stringPropertyNames()) { + // Check if property name starts with group + if (!property.startsWith(getGroup())) + continue; + + // Remove group + property = property.substring(getGroup().length()); + + // Overwrite matching settings + try { + matchProperty(parser, property); + } catch (NullPointerException ignored) {} + } + + processSettings(parser); + } + + /** + * Loads all settings from the system properties. + * Useful if you want to allow the user to modify settings at startup. + * + * @see #loadConfiguration(Properties) + * @see System#getProperties() + * @since v1-alpha2 + */ + public void loadConfiguration() { + loadConfiguration(System.getProperties()); + } + + /** + * Returns the group in which setting overrides must begin with. + * + * @return property group + * @since v1-alpha2 + */ + public abstract @NotNull String getGroup(); + + /** + * Loads the default subsystem configuration. + * + * @see #loadConfiguration() + * @see #loadConfiguration(Properties) + * @since v1-alpha0 + */ + public abstract void loadDefaultConfiguration(); + + /** + * Matches the given {@code property} against all settings. + * If a match has been found, the setting will be overwritten with the property's value. + * + * @param parser matching {@link PropertyParser} + * @param property property to match + * @since v1-alpha2 + */ + protected abstract void matchProperty(@NotNull PropertyParser parser, @NotNull String property); + + /** + * Allows the implementor to process all settings and potentially + * modify them before {@link #loadConfiguration(Properties)} returns. + * + * @param parser matching {@link PropertyParser} + * @since v1-alpha2 + */ + protected abstract void processSettings(@NotNull PropertyParser parser); + + /** + * Returns a configuration setting. + * + * @param setting setting name + * @return setting's value or {@code null} if not found + */ + public abstract @Nullable Object getSetting(@NotNull String setting); +} diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/Event.java b/base/src/main/java/de/staropensource/sosengine/base/classes/Event.java index b9c066c..dc88843 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/Event.java +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/Event.java @@ -19,15 +19,18 @@ package de.staropensource.sosengine.base.classes; +import de.staropensource.sosengine.base.classes.helpers.EventHelper; + /** * Represents an event. * + * @see EventHelper * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) public interface Event { /** - * Calls the event and notifies all annotated methods. + * Emits the event and calls all event listeners. * * @since v1-alpha0 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImpl.java b/base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImpl.java deleted file mode 100644 index c467b88..0000000 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImpl.java +++ /dev/null @@ -1,67 +0,0 @@ -/* - * 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 . - */ - -package de.staropensource.sosengine.base.classes; - -import de.staropensource.sosengine.base.types.logging.LogIssuer; -import de.staropensource.sosengine.base.types.logging.LogLevel; -import org.jetbrains.annotations.NotNull; - -/** - * Interface for implementing custom logger implementations, called by {@link de.staropensource.sosengine.base.logging.Logger}. - * - * @see de.staropensource.sosengine.base.logging.Logger - * @since v1-alpha0 - */ -@SuppressWarnings({ "unused" }) -public interface LoggerImpl { - /** - * Run before placeholders are replaced. - * - * @param level log level - * @param logIssuer log issuer - * @param message log message - * @return new log message - * @since v1-alpha0 - */ - @NotNull - String prePlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String message); - - /** - * Run after placeholders are replaced. - * - * @param level log level - * @param logIssuer log issuer - * @param format log format - * @return new log format - * @since v1-alpha0 - */ - @NotNull - String postPlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format); - - /** - * Responsible for printing the finalized log message. - * - * @param level log level - * @param logIssuer log issuer - * @param format finalized log format - * @since v1-alpha0 - */ - void print(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format); -} diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImplementation.java b/base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImplementation.java new file mode 100644 index 0000000..38b9702 --- /dev/null +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/LoggerImplementation.java @@ -0,0 +1,75 @@ +/* + * 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 . + */ + +package de.staropensource.sosengine.base.classes; + +import de.staropensource.sosengine.base.logging.Logger; +import de.staropensource.sosengine.base.types.logging.LogLevel; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * Interface for implementing custom logger implementations. + * + * @see Logger#setLoggerImplementation(LoggerImplementation) + * @since v1-alpha0 + */ +@SuppressWarnings({ "unused" }) +public interface LoggerImplementation { + /** + * Invoked before anything is done with the log message. + * + * @param level level + * @param issuerClass issuer class + * @param issuerOrigin issuer origin + * @param issuerMetadata issuer metadata + * @param message raw message + * @param format unmodified log format + * @return new log message, return {@code null} for no change + * @since v1-alpha2 + */ + @Nullable String prePlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format); + + /** + * Invoked after placeholders have been processed and replaced. + * + * @param level level + * @param issuerClass issuer class + * @param issuerOrigin issuer origin + * @param issuerMetadata issuer metadata + * @param message raw message + * @param format unmodified log format + * @return new log format + * @since v1-alpha2 + */ + @NotNull String postPlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format); + + /** + * Prints the log message. + * + * @param level level + * @param issuerClass issuer class + * @param issuerOrigin issuer origin + * @param issuerMetadata issuer metadata + * @param message raw message + * @param format unmodified log format + * @since v1-alpha2 + */ + void print(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format); +} 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 792ab41..c568fdc 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 @@ -31,12 +31,11 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public interface Placeholder { /** - * Replaces the placeholder with it's appropriate content. + * Replaces the placeholder with content. * * @param text text to process - * @return the processed text - * @since v1-alpha0 + * @return processed text + * @since v1-alpha2 */ - @NotNull - String replace(@NotNull String text); + @NotNull String replace(@NotNull String text); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/ShortcodeParserSkeleton.java b/base/src/main/java/de/staropensource/sosengine/base/classes/ShortcodeParserSkeleton.java index 94adfe6..119fc92 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/ShortcodeParserSkeleton.java +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/ShortcodeParserSkeleton.java @@ -22,8 +22,6 @@ package de.staropensource.sosengine.base.classes; import de.staropensource.sosengine.base.EngineConfiguration; import de.staropensource.sosengine.base.exceptions.ParserException; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import lombok.Getter; import org.jetbrains.annotations.NotNull; @@ -31,7 +29,11 @@ import java.util.LinkedList; import java.util.Locale; /** - * The base skeleton for implementing a shortcode parser. + * Base class for implementing a shortcode converter. + *

+ * This class parses a string and converts it into a list of + * components, which can then be in turn be converted to something + * else, for example, ANSI escape codes. *

* The following shortcodes are available and can be used: *

    @@ -42,61 +44,58 @@ import java.util.Locale; *
  • italic
    • *
  • strikethrough
    • *
  • underline
    • - *
  • blink
    • - *
  • negative
    • *
* * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class ShortcodeParserSkeleton { /** - * Logger instance. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance * @since v1-alpha1 */ - protected final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + protected final @NotNull LoggerInstance logger; /** - * A list of components the parsed string is made out of. + * Contains a list of components the parsed text is made out of. * * @since v1-alpha1 - * * -- GETTER -- - * Returns a list of components the parsed string is made out of. + * Returns a list of components the parsed text is made out of. * - * @return component list of the parsed string + * @return component list * @since v1-alpha1 */ - @NotNull @Getter - protected final LinkedList components; + protected final @NotNull LinkedList components; /** * Constructs this class. * - * @param string string to parse - * @param ignoreInvalidEscapes will ignore invalid escapes and print treat them like regular text - * @throws ParserException when parsing failed - * @since v1-alpha1 + * @param string string to parse + * @param ignoreInvalidEscapes if {@code true}, will ignore and treat invalid escapes as text + * @throws ParserException on error + * @since v1-alpha2 */ public ShortcodeParserSkeleton(@NotNull String string, boolean ignoreInvalidEscapes) throws ParserException { + logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); components = parse(string, ignoreInvalidEscapes); } /** - * Parses an input string and spits out all of it's components. + * Parses the input string and returns a list + * of components the text is made out of. * * @param string string to parse - * @param ignoreInvalidEscapes will ignore invalid escapes and print treat them like regular text + * @param ignoreInvalidEscapes if {@code true}, will ignore and treat invalid escapes as text * @return list of components - * @throws ParserException when parsing failed + * @throws ParserException on error * @see EngineConfiguration#errorShortcodeConverter - * @since v1-alpha1 + * @since v1-alpha2 */ - @NotNull - protected LinkedList<@NotNull String> parse(@NotNull String string, boolean ignoreInvalidEscapes) throws ParserException { + protected @NotNull LinkedList<@NotNull String> parse(@NotNull String string, boolean ignoreInvalidEscapes) throws ParserException { LinkedList components = new LinkedList<>(); // List of components boolean tagActive = false; // Indicates that a tag is being parsed boolean escape = false; // Indicates whether the last character was a \ character @@ -276,18 +275,17 @@ public abstract class ShortcodeParserSkeleton { } /** - * Checks the supplied color tag and returns if it's valid. + * Returns if the specified color is valid * + * @return {@code true} if valid, {@code false} otherwise * @since v1-alpha2 */ private boolean isValidColor(@NotNull String color) { - switch (color.toLowerCase(Locale.ROOT)) { - case "black", "white", "red", "green", "blue", "yellow", "magenta", "cyan" -> { - return true; - } - default -> { - return false; - } - } + return switch (color.toLowerCase(Locale.ROOT)) { + case "black", "white", "red", + "green", "blue", "yellow", + "magenta", "cyan" -> true; + default -> false; + }; } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java b/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemClass.java similarity index 66% rename from base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java rename to base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemClass.java index d69134f..9fb18f7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemClass.java @@ -28,53 +28,60 @@ import de.staropensource.sosengine.base.types.DependencyVector; import org.jetbrains.annotations.NotNull; /** - * The interface for engine subsystem main classes. + * Interface for building subsystem main classes. * * @see EngineSubsystem * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public interface SubsystemMainClass { +public abstract class SubsystemClass { /** - * Logger instance. + * Constructs this class. + * + * @since v1-alpha2 + */ + public SubsystemClass() {} + + /** + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance * @since v1-alpha0 */ - LoggerInstance logger = null; + public final LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); /** - * Returns the name of this subsystem. + * Returns the name of the subsystem. * + * @return subsystem name * @since v1-alpha2 */ - @NotNull - String getName(); + public abstract @NotNull String getName(); /** - * Initializes this subsystem. + * Initializes the subsystem. * * @since v1-alpha1 */ - void initializeSubsystem(); + public abstract void initializeSubsystem(); /** - * Returns the {@link DependencyVector} for this subsystem. + * Returns a matching {@link DependencyVector}. + * Used for dependency resolution during startup. * - * @return {@link DependencyVector} for this subsystem - * @since v1-alpha1 + * @return matching {@link DependencyVector} for the subsystem * @see DependencyVector + * @since v1-alpha1 */ - @NotNull - DependencyVector getDependencyVector(); + public abstract @NotNull DependencyVector getDependencyVector(); /** - * Called when the engine shuts down. + * Called on engine shutdown. * * @see Engine#shutdown() * @see Engine#shutdown(int) * @since v1-alpha0 */ @EventListener(event = InternalEngineShutdownEvent.class) - static void shutdown() {} + protected static void shutdownSubsystem() {} } 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 deleted file mode 100644 index 7ad5165..0000000 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemConfiguration.java +++ /dev/null @@ -1,83 +0,0 @@ -/* - * 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 . - */ - -package de.staropensource.sosengine.base.classes; - -import org.jetbrains.annotations.NotNull; - -import java.util.Properties; - -/** - * Base class for subsystem configurations. - * - * @since v1-alpha0 - */ -@SuppressWarnings({ "unused" }) -public interface SubsystemConfiguration { - /** - * Contains the class instance. - * - * @since v1-alpha0 - */ - SubsystemConfiguration instance = null; - - /** - * Defines the group every property must start with to be recognized as a subsystem configuration setting. - * - * @since v1-alpha0 - */ - @NotNull - String group = "sosengine."; - - /** - * 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 {@link Properties} object - * @see SubsystemConfiguration#loadDefaultConfiguration() - * @since v1-alpha0 - */ - void loadConfiguration(@NotNull Properties properties); - - /** - * Loads the subsystem configuration from the system properties. - * - * @see SubsystemConfiguration#loadConfiguration(Properties) - * @see System#getProperties() - * @since v1-alpha0 - */ - void loadConfiguration(); - - /** - * Loads the default subsystem configuration. - * - * @see SubsystemConfiguration#loadConfiguration() - * @see SubsystemConfiguration#loadConfiguration(Properties) - * @since v1-alpha0 - */ - void loadDefaultConfiguration(); - - /** - * Returns a configuration setting. - * - * @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/VersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/classes/VersioningSystem.java index dc9a304..0fd8002 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/VersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/VersioningSystem.java @@ -24,27 +24,26 @@ import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Range; /** - * An interface used for implementing different versioning systems. + * Interface for building a versioning system (parser). * * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) public interface VersioningSystem { /** - * Returns the name of this versioning system. + * Returns the name of the versioning system. * - * @return name of this versioning system + * @return versioning system name * @since v1-alpha1 */ - @NotNull - String getName(); + @NotNull String getName(); /** - * Compares a version with another version. + * Compares a {@link VersioningSystem} with another. * - * @param version the version to compare against + * @param version {@link VersioningSystem} to compare against * @return smaller = {@code 0}, equal = {@code 1}, bigger = {@code 2} - * @throws IncompatibleVersioningSystemException when this versioning system does not support comparing with another versioning system + * @throws IncompatibleVersioningSystemException incompatible with the supplied versioning system * @since v1-alpha1 */ @Range(from = 0, to = 2) 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 715598f..6fbd09a 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 @@ -28,12 +28,9 @@ import de.staropensource.sosengine.base.exceptions.reflection.InstanceMethodFrom import de.staropensource.sosengine.base.exceptions.reflection.InvalidMethodSignature; import de.staropensource.sosengine.base.exceptions.reflection.NoAccessException; import de.staropensource.sosengine.base.exceptions.reflection.StaticInitializerException; -import de.staropensource.sosengine.base.logging.Logger; import de.staropensource.sosengine.base.logging.LoggerInstance; import de.staropensource.sosengine.base.reflection.Reflect; import de.staropensource.sosengine.base.reflection.ReflectionMethod; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.ListFormatter; import lombok.Getter; import org.jetbrains.annotations.NotNull; @@ -51,7 +48,7 @@ import java.util.LinkedList; import java.util.Set; /** - * Represents an event. + * Simplifies event logging and calling. * * @since v1-alpha0 */ @@ -59,48 +56,58 @@ import java.util.Set; @SuppressWarnings({ "unused" }) public final class EventHelper { /** - * Contains all cached event listeners. + * Holds all cached events. + * Should not be modified manually. * * @since v1-alpha0 */ - private static final HashMap<@NotNull Class, LinkedList<@NotNull ReflectionMethod>> cachedEventListeners = new HashMap<>(); + private static final @NotNull HashMap<@NotNull Class, LinkedList<@NotNull ReflectionMethod>> cachedEventListeners = new HashMap<>(); + + /** + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha1 + */ + private static final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(EventHelper.class).setOrigin("ENGINE").build(); /** * Constructs this class. + * + * @since v1-alpha0 */ public EventHelper() {} /** - * Logs the event call. + * Logs an event call. * - * @param clazz event class + * @param event event class * @param arguments arguments passed to event listeners * @since v1-alpha0 */ - public static void logCall(@NotNull Class clazz, @NotNull Object ... arguments) { + public static void logCall(@NotNull Class event, @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() + " emitted"); + logger.diag("Event " + event.getName() + " was emitted"); else - Logger.diag(new LogIssuer(clazz), "Event " + clazz.getName() + " emitted, passing arguments " + ListFormatter.formatArray(arguments)); + logger.diag("Event " + event.getName() + " was emitted, passing arguments " + ListFormatter.formatArray(arguments)); } /** - * Returns all event listeners. + * Returns all {@link EventListener}s listening on some event. + * The classpath will be scanned for listeners, unless cached results exist and {@code !forceScanning}. * - * @param clazz event class - * @param forceScanning forces the method to ignore cached event listeners, not recommended - * @return list of annotated methods + * @param event event class + * @param forceScanning forces scanning the classpath for listeners. not recommended due to a huge performance penalty + * @return list of event listeners + * @see #cacheEvent(Class) * @since v1-alpha0 */ - @NotNull - public static LinkedList getAnnotatedMethods(@NotNull Class clazz, boolean forceScanning) { + public static @NotNull LinkedList getAnnotatedMethods(@NotNull Class event, boolean forceScanning) { LinkedList methods = new LinkedList<>(); - if (forceScanning || !cachedEventListeners.containsKey(clazz)) { - // Scan entire classpath through Reflections library - // (enforced or not cached) + if (forceScanning || !cachedEventListeners.containsKey(event)) { Reflections reflections = new Reflections( new ConfigurationBuilder() .setUrls(ClasspathHelper.forJavaClassPath()) @@ -112,38 +119,38 @@ public final class EventHelper { // Sort event listeners not listening for this event out for (Method method : annotatedMethods) - if (method.getAnnotation(EventListener.class).event() == clazz) + if (method.getAnnotation(EventListener.class).event() == event) methods.add(Reflect.reflectOn(method)); // Sort 'methods' linked list after event priority methods.sort(Comparator.comparing(method -> method.getAnnotation(EventListener.class).priority())); } else - // 'forcedScanning' is false and matching event listeners are cached - methods = cachedEventListeners.get(clazz); + // Event listeners are cached and !forceScanning, return cached results + methods = cachedEventListeners.get(event); return methods; } /** - * Returns all matching event listeners. + * Returns all {@link EventListener}s listening on some event. + * The classpath will be scanned for listeners, unless cached results exist. * - * @param clazz event class - * @return list of annotated methods + * @param event event class + * @return list of event listeners * @since v1-alpha0 */ - @NotNull - public static LinkedList getAnnotatedMethods(@NotNull Class clazz) { - return getAnnotatedMethods(clazz, false); + public static @NotNull LinkedList getAnnotatedMethods(@NotNull Class event) { + return getAnnotatedMethods(event, false); } /** - * Invokes all matching event listeners without any arguments. + * Invokes all event listeners. * * @param event event class + * @param arguments arguments to pass to event listeners * @since v1-alpha0 */ public static void invokeAnnotatedMethods(@NotNull Class event, Object... arguments) { - LoggerInstance logger = new LoggerInstance(new LogIssuer(EventHelper.class, event.getName(), CodePart.ENGINE)); if (event != LogEvent.class) logCall(event); @@ -177,36 +184,35 @@ public final class EventHelper { } /** - * Caches all event listeners listening on some event. - * Will recompute all event listeners if the specified event is already cached. + * (Re-)Caches all event listeners for some {@link Event}. * - * @param clazz event listeners to (p)recompute, set to {@code null} to recompute all cached events + * @param event event to (re-)cache. Set to {@code null} to recompute all cached events * @since v1-alpha0 */ - public static synchronized void precomputeEventListeners(@Nullable Class clazz) { - if (clazz == null) - for (Class event : cachedEventListeners.keySet()) - precomputeEventListeners(event); + public static synchronized void cacheEvent(@Nullable Class event) { + if (event == null) + for (Class cachedEvent : cachedEventListeners.keySet()) + cacheEvent(cachedEvent); else { - LinkedList<@NotNull ReflectionMethod> annotatedMethods = getAnnotatedMethods(clazz); + LinkedList<@NotNull ReflectionMethod> annotatedMethods = getAnnotatedMethods(event); - if (cachedEventListeners.containsKey(clazz)) - cachedEventListeners.replace(clazz, annotatedMethods); + if (cachedEventListeners.containsKey(event)) + cachedEventListeners.replace(event, annotatedMethods); else - cachedEventListeners.put(clazz, annotatedMethods); + cachedEventListeners.put(event, annotatedMethods); } } /** - * Removes events from the event listener cache. + * Removes an event from the event listener cache. * - * @param clazz event class to remove cached event listeners for or {@code null} to remove all cached event listeners + * @param event event to uncache. Set to {@code null} to clear the entire cache * @since v1-alpha0 */ - public static synchronized void removePrecomputedEventListeners(@Nullable Class clazz) { - if (clazz == null) + public static synchronized void uncacheEvent(@Nullable Class event) { + if (event == null) cachedEventListeners.clear(); else - cachedEventListeners.remove(clazz); + cachedEventListeners.remove(event); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/classes/package-info.java index eee44da..0dd050c 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/package-info.java @@ -18,7 +18,9 @@ */ /** - * Contains various interfaces and abstract classes. + * Interfaces and abstract classes which can be used for implementing classes. + *

+ * These are not to be confused with data types. See {@link de.staropensource.sosengine.base.types}. * * @since v1-alpha0 */ 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/information/EngineInformation.java similarity index 77% rename from base/src/main/java/de/staropensource/sosengine/base/data/info/EngineInformation.java rename to base/src/main/java/de/staropensource/sosengine/base/data/information/EngineInformation.java index 7800021..317edab 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/info/EngineInformation.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/information/EngineInformation.java @@ -17,16 +17,15 @@ * along with this program. If not, see . */ -package de.staropensource.sosengine.base.data.info; +package de.staropensource.sosengine.base.data.information; import de.staropensource.sosengine.base.Engine; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.VersionType; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.parser.PropertyParser; import de.staropensource.sosengine.base.utility.parser.StackTraceParser; import lombok.Getter; +import org.jetbrains.annotations.NotNull; import java.io.IOException; import java.io.InputStream; @@ -38,17 +37,39 @@ import java.util.GregorianCalendar; import java.util.Properties; /** - * Provides build information about the sos!engine. + * Provides build information about the engine. + * + * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public final class EngineInformation { /** - * Provides the engine's version. + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha2 + */ + private static final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(EngineInformation.class).setOrigin("ENGINE").build(); + + /** + * Contains the engine's version codename. + * + * @since v1-alpha2 + * -- GETTER -- + * Returns the engine's version codename. + * + * @return engine version codename + * @since v1-alpha2 + */ + @Getter + private static String versioningCodename; + + /** + * Contains the engine's version. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the engine's version. + * Returns the engine's version. * * @return engine version * @since v1-alpha0 @@ -57,12 +78,11 @@ public final class EngineInformation { private static int versioningVersion; /** - * Provides the engine's version type. + * Contains the engine's version type. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the engine's version type. + * Returns the engine's version type. * * @return engine version type * @since v1-alpha0 @@ -71,28 +91,28 @@ public final class EngineInformation { private static VersionType versioningType; /** - * Provides the engine's type release. + * Contains the engine's typerelease. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the engine's type release. + * Returns the engine's typerelease. * - * @return engine type release + * @return engine typerelease * @since v1-alpha0 */ @Getter private static int versioningTyperelease; /** - * Provides the engine's fork identifier.
- * Likely empty. If not, it must be prefixed with a dash. + * Contains the engine's fork identifier. + *

+ * Likely empty. If not, prefixed with a dash. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the engine's fork identifier.
- * Likely empty. If not, it must be prefixed with a dash. + * Returns the engine's fork identifier. + *

+ * Likely empty. If not, prefixed with a dash. * * @return engine fork identifier * @since v1-alpha0 @@ -101,12 +121,11 @@ public final class EngineInformation { private static String versioningFork; /** - * Provides the engine's full version string. + * Contains the engine's full version string. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the engine's full version string. + * Returns the engine's full version string. * * @return engine version string * @since v1-alpha1 @@ -116,26 +135,24 @@ public final class EngineInformation { /** - * Provides the {@code dirty} value (i.e. if the source tree has been modified). + * Contains the {@code dirty} value (i.e. if the source tree has been modified). * * @since v1-alpha1 - * * -- GETTER -- - * Provides the {@code dirty} value (i.e. if the source tree has been modified). + * Returns the {@code dirty} value (i.e. if the source tree has been modified). * * @return git dirty value * @since v1-alpha1 */ @Getter - private static Boolean gitDirty; + private static boolean gitDirty; /** - * Provides the branch the engine was built on. + * Contains the branch the engine was built on. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the branch the engine was built on. + * Returns the branch the engine was built on. * * @return git branch * @since v1-alpha1 @@ -144,12 +161,11 @@ public final class EngineInformation { private static String gitBranch; /** - * Provides the commit count. + * Contains the commit count. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commit count. + * Returns the commit count. * * @return git commit count * @since v1-alpha1 @@ -158,12 +174,11 @@ public final class EngineInformation { private static int gitCommitCount; /** - * Provides the commit identifier (short form). + * Contains the commit identifier (short form). * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commit identifier (short form). + * Returns the commit identifier (short form). * * @return git long commit id * @since v1-alpha1 @@ -172,12 +187,11 @@ public final class EngineInformation { private static String gitCommitIdentifierShort; /** - * Provides the commit identifier (long form). + * Contains the commit identifier (long form). * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commit identifier (long form). + * Returns the commit identifier (long form). * * @return git long commit id * @since v1-alpha1 @@ -186,12 +200,11 @@ public final class EngineInformation { private static String gitCommitIdentifierLong; /** - * Provides the commit header. + * Contains the commit header. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commit header. + * Returns the commit header. * * @return git commit header * @since v1-alpha1 @@ -200,12 +213,11 @@ public final class EngineInformation { private static String gitCommitHeader; /** - * Provides the commit time. + * Contains the commit time. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commit time. + * Returns the commit time. * * @return git commit time * @since v1-alpha1 @@ -214,12 +226,11 @@ public final class EngineInformation { private static ZonedDateTime gitCommitTime; /** - * Provides the commiter's name. + * Contains the commiter's name. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commiter's name. + * Returns the commiter's name. * * @return git committer name * @since v1-alpha1 @@ -228,12 +239,11 @@ public final class EngineInformation { private static String gitCommitterName; /** - * Provides the commiter's email. + * Contains the commiter's email. * * @since v1-alpha1 - * * -- GETTER -- - * Provides the commiter's email. + * Returns the commiter's email. * * @return git committer email * @since v1-alpha1 @@ -243,12 +253,11 @@ public final class EngineInformation { /** - * Provides the version of the dependency {@code Jansi}. + * Contains the version of the dependency {@code Jansi}. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the version of the dependency {@code Jansi}. + * Returns the version of the dependency {@code Jansi}. * * @return Jansi dependency version * @since v1-alpha0 @@ -257,12 +266,11 @@ public final class EngineInformation { private static String dependencyJansi; /** - * Provides the version of the dependency {@code Reflections}. + * Contains the version of the dependency {@code Reflections}. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the version of the dependency {@code Reflections}. + * Returns the version of the dependency {@code Reflections}. * * @return Reflections dependency version * @since v1-alpha0 @@ -271,12 +279,11 @@ public final class EngineInformation { private static String dependencyReflections; /** - * Provides the version of the dependency {@code SLF4J}. + * Contains the version of the dependency {@code SLF4J}. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the version of the dependency {@code SLF4J}. + * Returns the version of the dependency {@code SLF4J}. * * @return SLF4J dependency version * @since v1-alpha0 @@ -285,12 +292,11 @@ public final class EngineInformation { private static String dependencySlf4j; /** - * Provides the version of the dependency {@code LWJGL}. + * Contains the version of the dependency {@code LWJGL}. * * @since v1-alpha0 - * * -- GETTER -- - * Provides the version of the dependency {@code LWJGL}. + * Returns the version of the dependency {@code LWJGL}. * * @return LWJGL dependency version * @since v1-alpha0 @@ -307,12 +313,13 @@ public final class EngineInformation { /** * Updates all variables. + *

+ * This method does not need to be invoked, as the information provided by this + * class is static (does not change) and is already populated at engine startup. * * @since v1-alpha1 */ public static synchronized void updateVariables() { - LoggerInstance logger = new LoggerInstance(new LogIssuer(EngineInformation.class, CodePart.ENGINE)); - // Load properties from bundled gradle.properties Properties gradleProperties = new Properties(); InputStream gradleStream = EngineInformation.class.getClassLoader().getResourceAsStream("gradle.properties"); @@ -370,6 +377,7 @@ public final class EngineInformation { PropertyParser gitParser = new PropertyParser(gitProperties); // Apply properties to fields + versioningCodename = gradleParser.getString("versioningCodename"); versioningVersion = gradleParser.getInteger("versioningVersion", true); versioningType = VersionType.valueOf(gradleParser.getString("versioningType").toUpperCase()); versioningTyperelease = gradleParser.getInteger("versioningTyperelease", true); 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/information/JvmInformation.java similarity index 66% rename from base/src/main/java/de/staropensource/sosengine/base/data/info/JvmInformation.java rename to base/src/main/java/de/staropensource/sosengine/base/data/information/JvmInformation.java index 3cd6e26..45d33ff 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/info/JvmInformation.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/information/JvmInformation.java @@ -17,11 +17,9 @@ * along with this program. If not, see . */ -package de.staropensource.sosengine.base.data.info; +package de.staropensource.sosengine.base.data.information; -import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.logging.LoggerInstance; import org.jetbrains.annotations.NotNull; import java.lang.management.ManagementFactory; @@ -30,9 +28,19 @@ import java.util.List; /** * Provides information about the running Java Virtual Machine. + * + * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) public final class JvmInformation { + /** + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha2 + */ + private static final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(JvmInformation.class).setOrigin("ENGINE").build(); + /** * Constructs this class. * @@ -43,8 +51,8 @@ public final class JvmInformation { /** * Returns the Java version this JVM implements. * - * @return the Java version - * @throws NumberFormatException if the version could not be converted into an int + * @return Java version + * @throws NumberFormatException on integer conversion failure * @since v1-alpha0 */ public static int getJavaVersion() throws NumberFormatException { @@ -60,7 +68,7 @@ public final class JvmInformation { try { return Integer.parseInt(version); } catch (NumberFormatException exception) { - Logger.crash(new LogIssuer(JvmInformation.class, CodePart.ENGINE), "Could not parse Java version: Integer conversion failed for string \"" + version + "\"", exception, true); + logger.crash("Could not parse Java version: Integer conversion failed for string \"" + version + "\"", exception, true); throw exception; } } @@ -68,33 +76,30 @@ public final class JvmInformation { /** * Returns the JVM implementation name. * - * @return the JVM implementation name + * @return implementation name * @since v1-alpha0 */ - @NotNull - public static String getImplementationName() { + public static @NotNull String getImplementationName() { return ManagementFactory.getRuntimeMXBean().getVmName(); } /** * Returns the JVM implementation version. * - * @return the JVM implementation version + * @return implementation version * @since v1-alpha0 */ - @NotNull - public static String getImplementationVersion() { + public static @NotNull String getImplementationVersion() { return ManagementFactory.getRuntimeMXBean().getVmVersion(); } /** * Returns the JVM implementation vendor. * - * @return the JVM implementation vendor + * @return implementation vendor * @since v1-alpha0 */ - @NotNull - public static String getImplementationVendor() { + public static @NotNull String getImplementationVendor() { return ManagementFactory.getRuntimeMXBean().getVmVendor(); } @@ -109,20 +114,18 @@ public final class JvmInformation { } /** - * Returns the arguments passed to the JVM (not to the running program). + * Returns all arguments passed to the JVM. + * This excludes all arguments passed to the application. * - * @return the JVM arguments + * @return JVM arguments * @since v1-alpha0 */ - @NotNull - public static List<@NotNull String> getArguments() { + public static @NotNull List<@NotNull String> getArguments() { return ManagementFactory.getRuntimeMXBean().getInputArguments(); } /** - * Returns the total amount of memory used the running application AND JVM. - *

- * Note: This is an estimate. + * Returns the estimated total amount of memory used the running application and JVM. * * @return estimated total amount of used memory * @since v1-alpha1 @@ -132,19 +135,19 @@ public final class JvmInformation { } /** - * Returns the maximum amount of memory usable by the running application. + * Returns the maximum amount of memory which can be used by the running application. * - * @return maximum amount of usable memory + * @return maximum amount of memory usable in bytes * @since v1-alpha1 */ - public static long getMemoryMax() { + public static long getMemoryLimit() { return Runtime.getRuntime().maxMemory(); } /** * Returns the amount of free memory available to the running application. * - * @return amount of free memory + * @return amount of free memory in bytes * @since v1-alpha1 */ public static long getMemoryFree() { @@ -154,37 +157,37 @@ public final class JvmInformation { /** * Returns the amount of memory used by the running application. * - * @return amount of used memory + * @return amount of used memory in bytes * @since v1-alpha1 */ public static long getMemoryUsed() { - return getMemoryMax() - getMemoryFree(); + return getMemoryLimit() - getMemoryFree(); } /** - * Returns the memory usage of the heap. + * Returns the size of heap memory. * - * @return heap usage + * @return heap memory size * @since v1-alpha1 */ - public static MemoryUsage getMemoryHeap() { + public static @NotNull MemoryUsage getMemoryHeap() { return ManagementFactory.getMemoryMXBean().getHeapMemoryUsage(); } /** - * Returns the memory usage of the stack. + * Returns size of stack memory. * - * @return stack usage + * @return stack memory size * @since v1-alpha1 */ - public static MemoryUsage getMemoryStack() { + public static @NotNull MemoryUsage getMemoryStack() { return ManagementFactory.getMemoryMXBean().getNonHeapMemoryUsage(); } /** - * Returns the amount of processors used by the JVM. + * Returns the amount of processors available to the JVM. *

- * Note: The amount of processors used may change rapidly. + * Note: The amount of available processors may change rapidly. * If your application scales resources based on the output of * this method, consider checking it's output often and scaling * resources accordingly. diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/info/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/data/information/package-info.java similarity index 85% rename from base/src/main/java/de/staropensource/sosengine/base/data/info/package-info.java rename to base/src/main/java/de/staropensource/sosengine/base/data/information/package-info.java index d326178..eaf375d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/info/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/information/package-info.java @@ -18,8 +18,8 @@ */ /** - * Provides various classes that can be used to retrieve information about the engine or JVM. + * Classes which can be used to retrieve information about the execution environment. * * @since v1-alpha0 */ -package de.staropensource.sosengine.base.data.info; +package de.staropensource.sosengine.base.data.information; diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/data/package-info.java index ac579d0..b910761 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains various packages with tiny classes that provide or process information. + * Classes which provide or process information. * * @since v1-alpha0 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/FourNumberVersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/FourNumberVersioningSystem.java index 6980bad..93a5689 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/FourNumberVersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/FourNumberVersioningSystem.java @@ -32,65 +32,60 @@ import org.jetbrains.annotations.Range; * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class FourNumberVersioningSystem implements VersioningSystem { /** - * Contains the 1. number vector. + * Contains the first number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 1. number vector. + * Returns the first number vector. * - * @return 1. number vector + * @return first number vector * @since v1-alpha1 */ private final int number1; /** - * Contains the 2. number vector. + * Contains the second number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 2. number vector. + * Returns the second number vector. * - * @return 2. number vector + * @return second number vector * @since v1-alpha1 */ private final int number2; /** - * Contains the 3. number vector. + * Contains the third number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 3. number vector. + * Returns the third number vector. * - * @return 3. number vector + * @return third number vector * @since v1-alpha1 */ private final int number3; /** - * Contains the 4. number vector. + * Contains the fourth number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 4. number vector. + * Returns the fourth number vector. * - * @return 4. number vector + * @return fourth number vector * @since v1-alpha1 */ private final int number4; /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "n4"; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/OneNumberVersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/OneNumberVersioningSystem.java index 5677c1f..3b93508 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/OneNumberVersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/OneNumberVersioningSystem.java @@ -27,18 +27,17 @@ import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Range; /** - * Represents a two-numbered versioning system, where an application or work is versioning by two arbitrary numbers. + * Represents a one-numbered versioning system, where an application or work is versioned by one arbitrary number. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class OneNumberVersioningSystem implements VersioningSystem { /** * Contains the number vector. * * @since v1-alpha1 - * * -- GETTER -- * Returns the number vector. * @@ -48,9 +47,8 @@ public final class OneNumberVersioningSystem implements VersioningSystem { private final int number; /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "n1"; } @@ -80,7 +78,6 @@ public final class OneNumberVersioningSystem implements VersioningSystem { return 2; return 1; - } else throw new IncompatibleVersioningSystemException(this, versionInterface); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/SemanticVersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/SemanticVersioningSystem.java index 1c32dcb..20bdae7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/SemanticVersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/SemanticVersioningSystem.java @@ -33,83 +33,78 @@ import java.util.Arrays; import java.util.List; /** - * Represents the semantic versioning system (version 2.0.0), where an application or work is versioning by a MAJOR version, a MINOR version, a PATCH version and optionally, a pre-release vector and a build number. + * Represents the semantic versioning system (version 2.0.0), where an application + * or work is versioning by a {@code MAJOR} version, {@code MINOR} version, + * {@code PATCH} version and optionally, a pre-release vector and a build number. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class SemanticVersioningSystem implements VersioningSystem { /** - * Contains the MAJOR vector. + * Contains the {@code MAJOR} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the MAJOR vector. + * Returns the {@code MAJOR} vector. * - * @return MAJOR vector + * @return {@code MAJOR} vector * @since v1-alpha1 */ private final int major; /** - * Contains the MINOR vector. + * Contains the {@code MINOR} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the MINOR vector. + * Returns the {@code MINOR} vector. * - * @return MINOR vector + * @return {@code MINOR} vector * @since v1-alpha1 */ private final int minor; /** - * Contains the PATCH vector. + * Contains the {@code PATCH} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the PATCH vector. + * Returns the {@code PATCH} vector. * - * @return PATCH vector + * @return {@code PATCH} vector * @since v1-alpha1 */ private final int patch; /** - * Contains the PRERELEASE vector. + * Contains the {@code PRERELEASE} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the PRERELEASE vector. + * Returns the {@code PRERELEASE} vector. * - * @return PRERELEASE vector + * @return {@code PRERELEASE} vector * @since v1-alpha1 */ - @Nullable - private final String prerelease; + private final @Nullable String prerelease; /** - * Contains the BUILD vector. + * Contains the {@code BUILD} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the BUILD vector. + * Returns the {@code BUILD} vector. * - * @return BUILD vector + * @return {@code BUILD} vector * @since v1-alpha1 */ private final int build; /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "Semantic"; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/StarOpenSourceVersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/StarOpenSourceVersioningSystem.java index b508ee2..3cfe62b 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/StarOpenSourceVersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/StarOpenSourceVersioningSystem.java @@ -33,71 +33,68 @@ import java.util.List; import java.util.Locale; /** - * Represents the StarOpenSource versioning system (version 2), where an application or work is versioning by a VERSION vector, a TYPE version type, a TYPERELEASE vector and optionally, a fork vector and a companion vector. + * Represents the StarOpenSource versioning system (version 2), where an application + * or work is versioning by a {@code VERSION} vector, {@code TYPE} version type, + * {@code TYPERELEASE} vector and optionally, a {@code FORK} vector and + * {@code COMPANION} vector. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class StarOpenSourceVersioningSystem implements VersioningSystem { /** - * Contains the VERSION vector. + * Contains the {@code VERSION} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the VERSION vector. + * Returns the {@code VERSION} vector. * - * @return VERSION vector + * @return {@code VERSION} vector * @since v1-alpha1 */ private final int version; /** - * Contains the TYPE vector. + * Contains the {@code TYPE} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the TYPE vector. + * Returns the {@code TYPE} vector. * - * @return TYPE vector + * @return {@code TYPE} vector * @since v1-alpha1 */ private final VersionType type; /** - * Contains the TYPERELEASE vector. + * Contains the {@code TYPERELEASE} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the TYPERELEASE vector. + * Returns the {@code TYPERELEASE}- vector. * - * @return TYPERELEASE vector + * @return {@code TYPERELEASE} vector * @since v1-alpha1 */ private final int typerelease; /** - * Contains the COMPANION vector. + * Contains the {@code COMPANION} vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the COMPANION vector. + * Returns the {@code COMPANION} vector. * - * @return COMPANION vector + * @return {@code COMPANION} vector * @since v1-alpha1 */ - @Nullable - private final String companion; + private final @Nullable String companion; /** * Contains the FORK vector. * * @since v1-alpha1 - * * -- GETTER -- * Returns the FORK vector. * @@ -107,9 +104,8 @@ public final class StarOpenSourceVersioningSystem implements VersioningSystem { private final String fork; /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "StarOpenSource"; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/ThreeNumberVersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/ThreeNumberVersioningSystem.java index 4fdeba2..52fe0a0 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/ThreeNumberVersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/ThreeNumberVersioningSystem.java @@ -32,52 +32,48 @@ import org.jetbrains.annotations.Range; * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class ThreeNumberVersioningSystem implements VersioningSystem { /** - * Contains the 1. number vector. + * Contains the first number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 1. number vector. + * Returns the first number vector. * - * @return 1. number vector + * @return first number vector * @since v1-alpha1 */ private final int number1; /** - * Contains the 2. number vector. + * Contains the second number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 2. number vector. + * Returns the second number vector. * - * @return 2. number vector + * @return second number vector * @since v1-alpha1 */ private final int number2; /** - * Contains the 3. number vector. + * Contains the third number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 3. number vector. + * Returns the third number vector. * - * @return 3. number vector + * @return third number vector * @since v1-alpha1 */ private final int number3; /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "n3"; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/TwoNumberVersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/TwoNumberVersioningSystem.java index 74eae14..bfbea27 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/TwoNumberVersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/TwoNumberVersioningSystem.java @@ -32,39 +32,36 @@ import org.jetbrains.annotations.Range; * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class TwoNumberVersioningSystem implements VersioningSystem { /** - * Contains the 1. number vector. + * Contains the first number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 1. number vector. + * Returns the first number vector. * - * @return 1. number vector + * @return first number vector * @since v1-alpha1 */ private final int number1; /** - * Contains the 2. number vector. + * Contains the second number vector. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the 2. number vector. + * Returns the second number vector. * - * @return 2. number vector + * @return second number vector * @since v1-alpha1 */ private final int number2; /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "n2"; } @@ -81,7 +78,7 @@ public final class TwoNumberVersioningSystem implements VersioningSystem { // Escape separator or throw error if invalid switch (separator) { case "." -> separator = "\\."; - case null -> throw new InvalidVersionStringException(this, versionString, "No matching separator could be found. Required are either one dot ('.') or hyphen ('-')."); + case null -> throw new InvalidVersionStringException(this, versionString, "No matching separator could be found. Required are either one dot ('.') or hyphen ('-')"); default -> {} } @@ -93,7 +90,7 @@ public final class TwoNumberVersioningSystem implements VersioningSystem { this.number1 = Integer.parseUnsignedInt(versionStringSplit[0]); this.number2 = Integer.parseUnsignedInt(versionStringSplit[1]); } catch (NumberFormatException exception) { - throw new InvalidVersionStringException(this, versionString, "Failed converting one of the vectors to an integer.", exception); + throw new InvalidVersionStringException(this, versionString, "Failed converting one of the vectors to an integer", exception); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/package-info.java index eea14f1..cf44766 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/data/versioning/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/data/versioning/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains built-in versioning systems that + * Built-in versioning systems which * can be used to represent versions of some work. * * @since v1-alpha1 diff --git a/base/src/main/java/de/staropensource/sosengine/base/events/EngineCrashEvent.java b/base/src/main/java/de/staropensource/sosengine/base/events/EngineCrashEvent.java index b3131c7..82b023e 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/events/EngineCrashEvent.java +++ b/base/src/main/java/de/staropensource/sosengine/base/events/EngineCrashEvent.java @@ -23,14 +23,16 @@ import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; /** - * Called in the event of an engine crash, just before the JVM exists. + * Called in the event of an engine crash. * * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) public final class EngineCrashEvent implements Event { /** - * Constructs this class. + * Constructs this event. + * + * @since v1-alpha0 */ public EngineCrashEvent() {} diff --git a/base/src/main/java/de/staropensource/sosengine/base/events/EngineShutdownEvent.java b/base/src/main/java/de/staropensource/sosengine/base/events/EngineShutdownEvent.java index bf55235..25710a2 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/events/EngineShutdownEvent.java +++ b/base/src/main/java/de/staropensource/sosengine/base/events/EngineShutdownEvent.java @@ -23,13 +23,15 @@ import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; /** - * Called when the engine and JVM are about to shutdown. + * Called when the engine is about to shutdown. * * @since v1-alpha0 */ public final class EngineShutdownEvent implements Event { /** - * Constructs this class. + * Constructs this event. + * + * @since v1-alpha0 */ public EngineShutdownEvent() {} diff --git a/base/src/main/java/de/staropensource/sosengine/base/events/EngineSoftCrashEvent.java b/base/src/main/java/de/staropensource/sosengine/base/events/EngineSoftCrashEvent.java index f2167a4..974dc66 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/events/EngineSoftCrashEvent.java +++ b/base/src/main/java/de/staropensource/sosengine/base/events/EngineSoftCrashEvent.java @@ -21,17 +21,22 @@ package de.staropensource.sosengine.base.events; import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; +import de.staropensource.sosengine.base.logging.Logger; /** * Called in the event of a soft engine crash - * ie. a crash which was declared as handled. + * ie. when a crash report is thrown but marked + * as handled. * + * @see Logger#crash(Class, String, String, String, Throwable, boolean) * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) public final class EngineSoftCrashEvent implements Event { /** - * Constructs this class. + * Constructs this event. + * + * @since v1-alpha0 */ public EngineSoftCrashEvent() {} 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 f561796..9156809 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 @@ -21,9 +21,9 @@ package de.staropensource.sosengine.base.events; import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** * Called before a new log message is printed. @@ -33,28 +33,32 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class LogEvent implements Event { /** - * Constructs this class. + * Constructs this event. + * + * @since v1-alpha0 */ public LogEvent() {} /** * {@inheritDoc} * @deprecated use the {@code callEvent} method with arguments - * @see LogEvent#callEvent(LogLevel, LogIssuer, String) + * @see #callEvent(LogLevel, Class, String, String, String) */ @Deprecated @Override public void callEvent() {} /** - * Calls the event and notifies all annotated methods. + * Emits the event and calls all event listeners. * - * @param level log level - * @param logIssuer log issuer - * @param message log message + * @param level level + * @param issuerClass issuer class + * @param issuerOrigin issuer origin + * @param issuerMetadata issuer metadata + * @param message message * @since v1-alpha0 */ - public void callEvent(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String message) { - EventHelper.invokeAnnotatedMethods(getClass(), level, logIssuer, message); + public void callEvent(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + EventHelper.invokeAnnotatedMethods(getClass(), level, issuerClass, issuerOrigin, issuerMetadata, message); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/events/ThrowableCatchEvent.java b/base/src/main/java/de/staropensource/sosengine/base/events/ThrowableCatchEvent.java index 4fdba0e..e74decd 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/events/ThrowableCatchEvent.java +++ b/base/src/main/java/de/staropensource/sosengine/base/events/ThrowableCatchEvent.java @@ -25,14 +25,16 @@ import de.staropensource.sosengine.base.utility.Miscellaneous; import org.jetbrains.annotations.NotNull; /** - * Called when an exception is caught. + * Called when an exception is caught by {@link Miscellaneous#executeSafely(Runnable, String)}. * * @see Miscellaneous#executeSafely(Runnable, String) * @since v1-alpha0 */ public final class ThrowableCatchEvent implements Event { /** - * Constructs this class. + * Constructs this event. + * + * @since v1-alpha0 */ public ThrowableCatchEvent() {} @@ -46,7 +48,7 @@ public final class ThrowableCatchEvent implements Event { public void callEvent() {} /** - * Calls the event and notifies all annotated methods. + * Emits the event and calls all event listeners. * * @param throwable caught throwable * @param identifier an identifier given to the runnable diff --git a/base/src/main/java/de/staropensource/sosengine/base/events/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/events/package-info.java index a68cb65..ae132f6 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/events/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/events/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains events. There's nothing more to say. + * Events. There's nothing more to say. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/ParserException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/ParserException.java index 7c4c91c..8bf85bc 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/ParserException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/ParserException.java @@ -27,6 +27,12 @@ import org.jetbrains.annotations.NotNull; * @since v1-alpha2 */ public class ParserException extends RuntimeException { + /** + * Constructs this exception. + * + * @param message parsing error + * @since v1-alpha2 + */ public ParserException(@NotNull String message) { super(message); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/TristateConversionException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/TristateConversionException.java index 4bf1d8e..afdd8f5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/TristateConversionException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/TristateConversionException.java @@ -22,15 +22,21 @@ package de.staropensource.sosengine.base.exceptions; import de.staropensource.sosengine.base.types.Tristate; /** - * Thrown when converting a {@link Tristate} into a boolean fails. + * Thrown when converting a {@link Tristate} into a {@link Boolean} fails. *

- * This exception inherits {@link RuntimeException} on purpose, as sometimes - * you expect or have already validated the {@link Tristate} not being {@link Tristate#UNSET}. + * This exception inherits {@link RuntimeException} on purpose, + * as sometimes you may sure/have already validated that the + * {@link Tristate} is not {@link Tristate#UNSET}. * * @since v1-alpha2 */ public class TristateConversionException extends RuntimeException { + /** + * Constructs this exception. + * + * @since v1-alpha2 + */ public TristateConversionException() { - super("Can't convert Tristate.UNSET into a boolean"); + super("Tristate.UNSET cannot be converted into a boolean"); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnexpectedThrowableException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnexpectedThrowableException.java index f3f465d..aa9228a 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnexpectedThrowableException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnexpectedThrowableException.java @@ -23,27 +23,24 @@ import lombok.Getter; import org.jetbrains.annotations.NotNull; /** - * Represents an exception caused by some throwable. - * Basic wrapper for every throwable there is. + * Thrown when a method invokes another method and it throws an unhandled {@link Throwable}. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public class UnexpectedThrowableException extends Exception { /** * Contains the throwable supplied to the constructor. * * @since v1-alpha1 - * * -- GETTER -- * Returns the throwable supplied by the constructor. * * @return throwable * @since v1-alpha1 */ - @NotNull - Throwable throwable; + private final @NotNull Throwable throwable; /** * Constructs this exception. diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/DependencyCycleException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/DependencyCycleException.java index 3994471..cf97541 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/DependencyCycleException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/DependencyCycleException.java @@ -19,15 +19,16 @@ package de.staropensource.sosengine.base.exceptions.dependency; +import de.staropensource.sosengine.base.utility.DependencyResolver; import org.jetbrains.annotations.NotNull; /** - * Represents an exception caused by a dependency cycle. + * Thrown when the {@link DependencyResolver} detects a dependency cycle. * * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) -public class DependencyCycleException extends Exception { +public class DependencyCycleException extends RuntimeException { /** * Constructs this exception. * diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/UnmetDependenciesException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/UnmetDependenciesException.java index c24225b..95f10aa 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/UnmetDependenciesException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/UnmetDependenciesException.java @@ -20,45 +20,45 @@ package de.staropensource.sosengine.base.exceptions.dependency; import de.staropensource.sosengine.base.types.DependencyVector; +import de.staropensource.sosengine.base.utility.DependencyResolver; import lombok.Getter; import org.jetbrains.annotations.NotNull; import java.util.Map; /** - * Represents an exception caused by unmet dependencies. + * Thrown when the {@link DependencyResolver} cannot resolve one + * or more {@link DependencyVector}s due to unmet dependencies. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public class UnmetDependenciesException extends Exception { /** * Contains the unmet dependencies list supplied to the constructor. *

- * The key contains the {@link DependencyVector} that has unmet dependencies, - * while the value contains the error string ie. which dependency is unmet and why. + * The key contains the {@link DependencyVector} that + * has unmet dependencies, while the value contains the error. * * @since v1-alpha1 - * * -- GETTER -- * Returns the unmet dependencies list supplied to the constructor. *

- * The key contains the {@link DependencyVector} that has unmet dependencies, - * while the value contains the error string ie. which dependency is unmet and why. + * The key contains the {@link DependencyVector} that + * has unmet dependencies, while the value contains the error. * * @return unmet dependencies list * @since v1-alpha1 */ - @NotNull - private final Map<@NotNull DependencyVector, @NotNull String> unmetDependencies; + private final @NotNull Map<@NotNull DependencyVector, @NotNull String> unmetDependencies; /** * Constructs this exception. * - * @param unmetDependencies map of unmet dependencies + * @param unmetDependencies map of all unmet dependencies + * @see #unmetDependencies * @since v1-alpha1 - * @see UnmetDependenciesException#unmetDependencies */ public UnmetDependenciesException(@NotNull Map<@NotNull DependencyVector, @NotNull String> unmetDependencies) { this.unmetDependencies = unmetDependencies; diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/package-info.java index 41f4b8b..e582679 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/dependency/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains exceptions related to dependency resolving. + * Exceptions related to dependency resolving. * * @see de.staropensource.sosengine.base.utility.DependencyResolver * @since v1-alpha1 diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/package-info.java index a12b4e7..a5e6070 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains exceptions thrown by the engine. + * Exceptions thrown by the engine, subsystems and applications. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/IncompatibleTypeException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/IncompatibleTypeException.java index 06cb775..137c942 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/IncompatibleTypeException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/IncompatibleTypeException.java @@ -24,7 +24,7 @@ import de.staropensource.sosengine.base.utility.ListFormatter; import org.jetbrains.annotations.NotNull; /** - * Thrown when the method called does not apply to the class type. + * Thrown when the invoked method does not apply to the type of the class. * * @since v1-alpha2 */ @@ -40,4 +40,15 @@ public class IncompatibleTypeException extends RuntimeException { public IncompatibleTypeException(@NotNull String methodName, @NotNull ClassType requiredClassType, @NotNull ClassType[] compatibleTypes) { super("The method ReflectionClass#" + methodName + " only applies to type(s) " + ListFormatter.formatArray(compatibleTypes) + ", not " + requiredClassType.name()); } + + /** + * Constructs this exception. + * + * @param methodName name of the method that failed + * @param requiredClassType class type received by the method + * @param compatibleType class type the method is compatible with + */ + public IncompatibleTypeException(@NotNull String methodName, @NotNull ClassType requiredClassType, @NotNull ClassType compatibleType) { + super("The method ReflectionClass#" + methodName + " only applies to type(s) " + ListFormatter.formatArray(new ClassType[]{ compatibleType }) + ", not " + requiredClassType.name()); + } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InstanceMethodFromStaticContextException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InstanceMethodFromStaticContextException.java index ef88dc0..ba3c183 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InstanceMethodFromStaticContextException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InstanceMethodFromStaticContextException.java @@ -22,7 +22,7 @@ package de.staropensource.sosengine.base.exceptions.reflection; import org.jetbrains.annotations.NotNull; /** - * Thrown when trying to call a non-static method from a static context. + * Thrown when trying to call an instance (non-static) method from a static context. * * @since v1-alpha2 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InvalidMethodSignature.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InvalidMethodSignature.java index 9c7fa2a..c2fd56f 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InvalidMethodSignature.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/InvalidMethodSignature.java @@ -21,7 +21,18 @@ package de.staropensource.sosengine.base.exceptions.reflection; import org.jetbrains.annotations.NotNull; +/** + * Thrown when a method could not be found due to an invalid method signature. + * + * @since v1-alpha2 + */ +@SuppressWarnings({ "unused" }) public class InvalidMethodSignature extends Exception { + /** + * Constructs this exception. + * + * @param methodName method name + */ public InvalidMethodSignature(@NotNull String methodName) { super("Method " + methodName + " has a different method signature"); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/NoAccessException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/NoAccessException.java index 5277c65..8e99648 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/NoAccessException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/NoAccessException.java @@ -22,12 +22,19 @@ package de.staropensource.sosengine.base.exceptions.reflection; import org.jetbrains.annotations.NotNull; /** - * Thrown if access to some class, method or field is denied. + * Thrown if access to some class, method or field has been denied. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public class NoAccessException extends Exception { + /** + * Constructs this exception. + * + * @param type {@code class}, {@code method} or {@code field} + * @param name class, method or field name + * @since v1-alpha2 + */ public NoAccessException(@NotNull String type, @NotNull String name) { super("Access to " + type + " " + name + " has been denied"); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/StaticInitializerException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/StaticInitializerException.java index e9a7422..524f14b 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/StaticInitializerException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/StaticInitializerException.java @@ -23,26 +23,24 @@ import lombok.Getter; import org.jetbrains.annotations.NotNull; /** - * Thrown when an exception occurs - * while executing a static initializer. + * Thrown when an exception is thrown by a static initializer. * * @since v1-alpha2 */ @Getter -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public class StaticInitializerException extends Exception { /** - * Contains the throwable supplied to the constructor. + * Contains the throwable thrown by the static initializer. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the throwable supplied to the constructor. + * Returns the throwable thrown by the static initializer. * * @return throwable thrown by the static initializer * @since v1-alpha2 */ - private final Throwable throwable; + private final @NotNull Throwable throwable; /** * Constructs this exception. diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/package-info.java index 96b20e9..c505a38 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/reflection/package-info.java @@ -18,9 +18,9 @@ */ /** - * Contains exceptions used during reflection. + * Exceptions related to reflection. * - * @see de.staropensource.sosengine.base.reflection.Reflect + * @see de.staropensource.sosengine.base.reflection * @since v1-alpha2 */ package de.staropensource.sosengine.base.exceptions.reflection; diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/IncompatibleVersioningSystemException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/IncompatibleVersioningSystemException.java index dcd4f97..e2fbe31 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/IncompatibleVersioningSystemException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/IncompatibleVersioningSystemException.java @@ -22,7 +22,8 @@ package de.staropensource.sosengine.base.exceptions.versioning; import de.staropensource.sosengine.base.classes.VersioningSystem; /** - * Represents an exception caused by supplying an invalid or unexpected versioning system. + * Thrown when trying to compare a {@link VersioningSystem} against another + * {@link VersioningSystem}, which it does not support. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/InvalidVersionStringException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/InvalidVersionStringException.java index 3e65590..1a9fcca 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/InvalidVersionStringException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/InvalidVersionStringException.java @@ -26,32 +26,35 @@ import org.jetbrains.annotations.Nullable; /** - * Represents an exception caused by an invalid version string. + * Thrown when an invalid version string is supplied + * to an implementation of {@link VersioningSystem}. * * @since v1-alpha1 */ @Getter -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public class InvalidVersionStringException extends Exception { /** * Contains the throwable supplied to the constructor. * + * @see #InvalidVersionStringException(VersioningSystem, String, Throwable) + * @see #InvalidVersionStringException(VersioningSystem, String, String, Throwable) * @since v1-alpha1 - * * -- GETTER -- * Returns the throwable supplied by the constructor. * * @return throwable + * @see #InvalidVersionStringException(VersioningSystem, String, Throwable) + * @see #InvalidVersionStringException(VersioningSystem, String, String, Throwable) * @since v1-alpha1 */ - @Nullable - private final Throwable throwable; + private final @Nullable Throwable throwable; /** * Constructs this exception. * * @param versioningSystem versioning system that is unable to parse version strings - * @param versionString version string {@code a} + * @param versionString version string {@code a} * @param message some error message * @param throwable throwable that caused the parsing error * @since v1-alpha1 diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/package-info.java index fd1ea85..58905f0 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/versioning/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains exceptions thrown by {@link de.staropensource.sosengine.base.classes.VersioningSystem}s. + * Exceptions thrown by implementations of {@link de.staropensource.sosengine.base.classes.VersioningSystem}s. * * @see de.staropensource.sosengine.base.classes.VersioningSystem * @since v1-alpha1 diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/events/InternalEngineShutdownEvent.java b/base/src/main/java/de/staropensource/sosengine/base/internal/events/InternalEngineShutdownEvent.java index 607b02f..eef5ed1 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/events/InternalEngineShutdownEvent.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/events/InternalEngineShutdownEvent.java @@ -23,17 +23,20 @@ import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; /** - * Called when the engine and JVM are about to shutdown, after {@link de.staropensource.sosengine.base.events.EngineShutdownEvent}. + * Called when the engine is about to shutdown, after {@link de.staropensource.sosengine.base.events.EngineShutdownEvent}. + *

+ * Meant for subsystems to perform cleanup and shutdown routines, not for applications. * * @since v1-alpha0 */ public final class InternalEngineShutdownEvent implements Event { /** - * Constructs this class. + * Constructs this event. + * + * @since v1-alpha0 */ public InternalEngineShutdownEvent() {} - /** {@inheritDoc} */ @Override public void callEvent() { diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/internal/package-info.java index df52caf..c6943d2 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains engine-internal stuff, not part of the API. + * Engine-internal stuff, not part of the API. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateDay.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateDay.java index 8d361bf..670c630 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateDay.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateDay.java @@ -41,9 +41,8 @@ public final class DateDay implements Placeholder { public DateDay() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%date_day%", Math.padNumbers(Calendar.getInstance().get(Calendar.DAY_OF_MONTH), 2)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateMonth.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateMonth.java index 76ea9ba..2df9351 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateMonth.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateMonth.java @@ -41,9 +41,8 @@ public final class DateMonth implements Placeholder { public DateMonth() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%date_month%", Math.padNumbers(Calendar.getInstance().get(Calendar.MONTH), 2)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateYear.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateYear.java index a25705b..a975455 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateYear.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/DateYear.java @@ -41,9 +41,8 @@ public final class DateYear implements Placeholder { public DateYear() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%date_year%", Math.padNumbers(Calendar.getInstance().get(Calendar.YEAR), 4)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyJansi.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyJansi.java index c55853a..258c729 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyJansi.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyJansi.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineDependencyJansi implements Placeholder { public EngineDependencyJansi() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_dependency_jansi%", EngineInformation.getDependencyJansi()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyLwjgl.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyLwjgl.java index cbbd20c..ec067f9 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyLwjgl.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyLwjgl.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineDependencyLwjgl implements Placeholder { public EngineDependencyLwjgl() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_dependency_lwjgl%", EngineInformation.getDependencyLwjgl()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyReflections.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyReflections.java index 479f552..c9216be 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyReflections.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencyReflections.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineDependencyReflections implements Placeholder { public EngineDependencyReflections() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_dependency_reflections%", EngineInformation.getDependencyReflections()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencySlf4j.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencySlf4j.java index a731c71..75af655 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencySlf4j.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineDependencySlf4j.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineDependencySlf4j implements Placeholder { public EngineDependencySlf4j() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_dependency_slf4j%", EngineInformation.getDependencySlf4j()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitBranch.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitBranch.java index ac77db0..ebf52fd 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitBranch.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitBranch.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitBranch implements Placeholder { public EngineGitBranch() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_branch%", EngineInformation.getGitBranch()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitHeader.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitHeader.java index b9abe3c..048f880 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitHeader.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitHeader.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitHeader implements Placeholder { public EngineGitCommitHeader() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_header%", EngineInformation.getGitCommitHeader()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdLong.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdLong.java index f84c02a..005efa8 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdLong.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdLong.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitIdLong implements Placeholder { public EngineGitCommitIdLong() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_id_long%", EngineInformation.getGitCommitIdentifierLong()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdShort.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdShort.java index c0327f9..f195cf9 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdShort.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitIdShort.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitIdShort implements Placeholder { public EngineGitCommitIdShort() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_id_short%", EngineInformation.getGitCommitIdentifierShort()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeDay.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeDay.java index f3f5eef..a97fab5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeDay.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeDay.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitTimeDay implements Placeholder { public EngineGitCommitTimeDay() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_time_day%", String.valueOf(EngineInformation.getGitCommitTime().getDayOfMonth())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeHour.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeHour.java index 36eadec..3c6298e 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeHour.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeHour.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitTimeHour implements Placeholder { public EngineGitCommitTimeHour() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_time_hour%", String.valueOf(EngineInformation.getGitCommitTime().getHour())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMinute.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMinute.java index 04b7873..e17a4ec 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMinute.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMinute.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitTimeMinute implements Placeholder { public EngineGitCommitTimeMinute() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_time_minute%", String.valueOf(EngineInformation.getGitCommitTime().getMinute())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMonth.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMonth.java index 582f16b..fd850e4 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMonth.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeMonth.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitTimeMonth implements Placeholder { public EngineGitCommitTimeMonth() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_time_month%", String.valueOf(EngineInformation.getGitCommitTime().getMonth())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeSecond.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeSecond.java index 1a40327..33f1858 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeSecond.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeSecond.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitTimeSecond implements Placeholder { public EngineGitCommitTimeSecond() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_time_second%", String.valueOf(EngineInformation.getGitCommitTime().getSecond())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeYear.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeYear.java index 471b7b1..3b2d7cc 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeYear.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitTimeYear.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitTimeYear implements Placeholder { public EngineGitCommitTimeYear() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commit_time_year%", String.valueOf(EngineInformation.getGitCommitTime().getYear())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommits.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommits.java index 26a8bfd..a65de76 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommits.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommits.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommits implements Placeholder { public EngineGitCommits() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_commits%", String.valueOf(EngineInformation.getGitCommitCount())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterEmail.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterEmail.java index b85b90a..5d4220e 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterEmail.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterEmail.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitterEmail implements Placeholder { public EngineGitCommitterEmail() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_committer_email%", EngineInformation.getGitCommitterEmail()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterName.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterName.java index 26b812e..881a2de 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterName.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitCommitterName.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitCommitterName implements Placeholder { public EngineGitCommitterName() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_git_committer_name%", EngineInformation.getGitCommitterName()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitDirty.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitDirty.java index c5667a5..bf0b416 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitDirty.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineGitDirty.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineGitDirty implements Placeholder { public EngineGitDirty() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%engine_git_dirty%", String.valueOf(EngineInformation.getGitDirty())); + public @NotNull String replace(@NotNull String text) { + return text.replace("%engine_git_dirty%", String.valueOf(EngineInformation.isGitDirty())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersion.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersion.java index 2932b4f..2e56e04 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersion.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersion.java @@ -38,9 +38,8 @@ public final class EngineVersion implements Placeholder { public EngineVersion() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_version%", "v%engine_version_version%-%engine_version_type%%engine_version_typerelease%%engine_version_fork%"); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionFork.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionFork.java index 57f8793..fc0f229 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionFork.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionFork.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineVersionFork implements Placeholder { public EngineVersionFork() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_version_fork%", EngineInformation.getVersioningFork()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionType.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionType.java index 6fb8c58..a02f1e3 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionType.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionType.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineVersionType implements Placeholder { public EngineVersionType() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_version_type%", EngineInformation.getVersioningType().name().toLowerCase()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionTyperelease.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionTyperelease.java index d2fbcf3..cd6d4c7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionTyperelease.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionTyperelease.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineVersionTyperelease implements Placeholder { public EngineVersionTyperelease() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_version_typerelease%", String.valueOf(EngineInformation.getVersioningTyperelease())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionVersion.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionVersion.java index 24a1e7e..6e878c4 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionVersion.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/EngineVersionVersion.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class EngineVersionVersion implements Placeholder { public EngineVersionVersion() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%engine_version_version%", String.valueOf(EngineInformation.getVersioningVersion())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmArguments.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmArguments.java index 9acce72..3c26192 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmArguments.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmArguments.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.JvmInformation; +import de.staropensource.sosengine.base.data.information.JvmInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class JvmArguments implements Placeholder { public JvmArguments() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { StringBuilder arguments = new StringBuilder(); for (String argument : JvmInformation.getArguments()) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationName.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationName.java index bfa2c0f..a8aaac5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationName.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationName.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.JvmInformation; +import de.staropensource.sosengine.base.data.information.JvmInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class JvmImplementationName implements Placeholder { public JvmImplementationName() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%jvm_implementation_name%", JvmInformation.getImplementationName()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVendor.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVendor.java index adea761..a8eb373 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVendor.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVendor.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.JvmInformation; +import de.staropensource.sosengine.base.data.information.JvmInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class JvmImplementationVendor implements Placeholder { public JvmImplementationVendor() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%jvm_implementation_vendor%", JvmInformation.getImplementationVendor()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVersion.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVersion.java index 6ed35b8..b803bbc 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVersion.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmImplementationVersion.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.JvmInformation; +import de.staropensource.sosengine.base.data.information.JvmInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class JvmImplementationVersion implements Placeholder { public JvmImplementationVersion() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%jvm_implementation_version%", JvmInformation.getImplementationVersion()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmJava.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmJava.java index eb62eb1..8302df6 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmJava.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmJava.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.JvmInformation; +import de.staropensource.sosengine.base.data.information.JvmInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class JvmJava implements Placeholder { public JvmJava() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%jvm_java%", String.valueOf(JvmInformation.getJavaVersion())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmUptime.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmUptime.java index 2242900..da86cd0 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmUptime.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/JvmUptime.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.base.internal.placeholders; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.data.info.JvmInformation; +import de.staropensource.sosengine.base.data.information.JvmInformation; import org.jetbrains.annotations.NotNull; /** @@ -39,9 +39,8 @@ public final class JvmUptime implements Placeholder { public JvmUptime() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%jvm_uptime%", String.valueOf(JvmInformation.getUptime())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeEpoch.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeEpoch.java index 0c2a733..8fe44c9 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeEpoch.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeEpoch.java @@ -40,9 +40,8 @@ public final class TimeEpoch implements Placeholder { public TimeEpoch() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%time_epoch%", Math.padNumbers(System.currentTimeMillis(), String.valueOf(Long.MAX_VALUE).length())); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeHour.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeHour.java index 39e88e9..285718e 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeHour.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeHour.java @@ -41,9 +41,8 @@ public final class TimeHour implements Placeholder { public TimeHour() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%time_hour%", Math.padNumbers(Calendar.getInstance().get(Calendar.HOUR_OF_DAY), 2)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeMinute.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeMinute.java index 343150e..4925e09 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeMinute.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeMinute.java @@ -41,9 +41,8 @@ public final class TimeMinute implements Placeholder { public TimeMinute() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%time_minute%", Math.padNumbers(Calendar.getInstance().get(Calendar.MINUTE), 2)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeSecond.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeSecond.java index 40b6dec..4cf001b 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeSecond.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeSecond.java @@ -41,9 +41,8 @@ public final class TimeSecond implements Placeholder { public TimeSecond() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%time_second%", Math.padNumbers(Calendar.getInstance().get(Calendar.SECOND), 2)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeZone.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeZone.java index 1c7bff1..352ae89 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeZone.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/TimeZone.java @@ -40,9 +40,8 @@ public final class TimeZone implements Placeholder { public TimeZone() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%time_zone%", java.util.TimeZone.getDefault().getDisplayName(false, java.util.TimeZone.SHORT, Locale.US)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerMessage.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/CrashMessage.java similarity index 83% rename from base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerMessage.java rename to base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/CrashMessage.java index b41c50b..41340e8 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerMessage.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/CrashMessage.java @@ -23,13 +23,13 @@ import de.staropensource.sosengine.base.classes.Placeholder; import org.jetbrains.annotations.NotNull; /** - * Implements the {@code issuer_message} placeholder. + * Implements the {@code crash_message} placeholder. * * @see Placeholder * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public final class IssuerMessage implements Placeholder { +public final class CrashMessage implements Placeholder { /** * The message to use. * @@ -44,14 +44,13 @@ public final class IssuerMessage implements Placeholder { * @param message message to use * @since v1-alpha0 */ - public IssuerMessage(@NotNull String message) { + public CrashMessage(@NotNull String message) { this.message = message; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%issuer_message%", message); + public @NotNull String replace(@NotNull String text) { + return text.replace("%crash_message%", message); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerClass.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerClass.java index a454925..8cc5a10 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerClass.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerClass.java @@ -20,7 +20,6 @@ package de.staropensource.sosengine.base.internal.placeholders.crashhandler; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; /** @@ -32,27 +31,25 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class IssuerClass implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer class to use. * - * @since v1-alpha0 + * @since v1-alpha2 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull Class issuerClass; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerClass issuer class to use * @since v1-alpha0 */ - public IssuerClass(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public IssuerClass(@NotNull Class issuerClass) { + this.issuerClass = issuerClass; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%issuer_class%", logIssuer.getClazz().getName().replace(logIssuer.getClazz().getPackageName() + ".", "")); + public @NotNull String replace(@NotNull String text) { + return text.replace("%issuer_class%", issuerClass.getName().replace(issuerClass.getPackageName() + ".", "")); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerInfo.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerMetadata.java similarity index 67% rename from base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerInfo.java rename to base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerMetadata.java index ae43bb6..13077f6 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerInfo.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerMetadata.java @@ -20,44 +20,42 @@ package de.staropensource.sosengine.base.internal.placeholders.crashhandler; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** - * Implements the {@code issuer_info} placeholder. + * Implements the {@code issuer_metadata} placeholder. * * @see Placeholder * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public final class IssuerInfo implements Placeholder { +public final class IssuerMetadata implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer metadata to use. * * @since v1-alpha0 */ - @NotNull - private final LogIssuer logIssuer; + private final @Nullable String issuerMetadata; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerMetadata issuer metadata to use * @since v1-alpha0 */ - public IssuerInfo(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public IssuerMetadata(@Nullable String issuerMetadata) { + this.issuerMetadata = issuerMetadata; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { String replacement = "\\"; - if (logIssuer.getAdditionalInformation() != null) - replacement = logIssuer.getAdditionalInformation(); + if (issuerMetadata != null) + replacement = issuerMetadata; - return text.replace("%issuer_info%", replacement); + return text.replace("%issuer_metadata%", replacement); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerCodePart.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerOrigin.java similarity index 68% rename from base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerCodePart.java rename to base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerOrigin.java index dd67338..15382f1 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerCodePart.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerOrigin.java @@ -20,39 +20,38 @@ package de.staropensource.sosengine.base.internal.placeholders.crashhandler; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; +import java.util.Locale; + /** - * Implements the {@code issuer_code_part} placeholder. + * Implements the {@code issuer_origin} placeholder. * * @see Placeholder * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public final class IssuerCodePart implements Placeholder { +public final class IssuerOrigin implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer origin to use. * - * @since v1-alpha0 + * @since v1-alpha2 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull String issuerOrigin; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerOrigin issuer origin to use * @since v1-alpha0 */ - public IssuerCodePart(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public IssuerOrigin(@NotNull String issuerOrigin) { + this.issuerOrigin = issuerOrigin; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%issuer_code_part%", logIssuer.getCodePart().name()); + public @NotNull String replace(@NotNull String text) { + return text.replace("%issuer_origin%", issuerOrigin.toUpperCase(Locale.ROOT)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPackage.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPackage.java index 788af05..8515741 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPackage.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPackage.java @@ -20,7 +20,6 @@ package de.staropensource.sosengine.base.internal.placeholders.crashhandler; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; /** @@ -32,27 +31,25 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class IssuerPackage implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer class to use. * - * @since v1-alpha0 + * @since v1-alpha2 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull Class issuerClass; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerClass issuer class to use * @since v1-alpha0 */ - public IssuerPackage(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public IssuerPackage(@NotNull Class issuerClass) { + this.issuerClass = issuerClass; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%issuer_package%", logIssuer.getClazz().getPackageName()); + public @NotNull String replace(@NotNull String text) { + return text.replace("%issuer_package%", issuerClass.getPackageName()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPath.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPath.java index dc600f5..47c6e93 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPath.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/IssuerPath.java @@ -20,7 +20,6 @@ package de.staropensource.sosengine.base.internal.placeholders.crashhandler; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; /** @@ -32,27 +31,25 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class IssuerPath implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer class to use. * - * @since v1-alpha0 + * @since v1-alpha2 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull Class issuerClass; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerClass issuer class to use * @since v1-alpha0 */ - public IssuerPath(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public IssuerPath(@NotNull Class issuerClass) { + this.issuerClass = issuerClass; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%issuer_path%", logIssuer.getClazz().getName()); + public @NotNull String replace(@NotNull String text) { + return text.replace("%issuer_path%", issuerClass.getName()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/Stacktrace.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/Stacktrace.java index 1e1ef1a..c98bde4 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/Stacktrace.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/Stacktrace.java @@ -40,8 +40,7 @@ public final class Stacktrace implements Placeholder { * * @since v1-alpha0 */ - @Nullable - private final Throwable throwable; + private final @Nullable Throwable throwable; /** * Constructs this class. @@ -54,9 +53,8 @@ public final class Stacktrace implements Placeholder { } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%stacktrace%", throwable == null ? "No stack trace is available." : getFullStackTrace(throwable)); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/StacktraceAll.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/StacktraceAll.java index f745506..408301d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/StacktraceAll.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/StacktraceAll.java @@ -41,9 +41,8 @@ public final class StacktraceAll implements Placeholder { public StacktraceAll() {} /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { StringBuilder output = new StringBuilder(); Map stacktraces = Thread.getAllStackTraces(); diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/package-info.java index 3d9ba95..7f51453 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/crashhandler/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains all placeholders used in the {@link de.staropensource.sosengine.base.logging.CrashHandler}. + * Placeholders used in the {@link de.staropensource.sosengine.base.logging.CrashHandler}. * * @see de.staropensource.sosengine.base.logging.CrashHandler * @since v1-alpha0 diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogClass.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogClass.java index 9709683..04eb7d0 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogClass.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogClass.java @@ -20,7 +20,6 @@ package de.staropensource.sosengine.base.internal.placeholders.logger; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; /** @@ -32,27 +31,25 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class LogClass implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer class to use. * * @since v1-alpha0 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull Class issuerClass; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerClass issuer class to use * @since v1-alpha0 */ - public LogClass(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public LogClass(@NotNull Class issuerClass) { + this.issuerClass = issuerClass; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%log_class%", logIssuer.getClazz().getName().replace(logIssuer.getClazz().getPackageName() + ".", "")); + public @NotNull String replace(@NotNull String text) { + return text.replace("%log_class%", issuerClass.getName().replace(issuerClass.getPackageName() + ".", "")); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorPrimary.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorPrimary.java index 7e3b525..06fb9b4 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorPrimary.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorPrimary.java @@ -50,9 +50,8 @@ public final class LogColorPrimary implements Placeholder { } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { String color; switch (level) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorSecondary.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorSecondary.java index 47fe45a..a428c05 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorSecondary.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogColorSecondary.java @@ -50,9 +50,8 @@ public final class LogColorSecondary implements Placeholder { } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { String color; switch (level) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogLevel.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogLevel.java index 37e4cc0..6b02282 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogLevel.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogLevel.java @@ -49,9 +49,8 @@ public final class LogLevel implements Placeholder { } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { String levelText; switch (level) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMessage.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMessage.java index 9996b2a..698de48 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMessage.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMessage.java @@ -49,9 +49,8 @@ public final class LogMessage implements Placeholder { } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { return text.replace("%log_message%", message); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogInfo.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMetadata.java similarity index 67% rename from base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogInfo.java rename to base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMetadata.java index 6ac41a8..f9cb8fc 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogInfo.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogMetadata.java @@ -20,44 +20,42 @@ package de.staropensource.sosengine.base.internal.placeholders.logger; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** - * Implements the {@code log_info} placeholder. + * Implements the {@code log_metadata} placeholder. * * @see Placeholder * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public final class LogInfo implements Placeholder { +public final class LogMetadata implements Placeholder { /** - * The {@link LogIssuer} to use + * Issuer metadata to use * * @since v1-alpha0 */ - @NotNull - private final LogIssuer logIssuer; + private final @Nullable String issuerMetadata; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerMetadata issuer metadata to use * @since v1-alpha0 */ - public LogInfo(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public LogMetadata(@Nullable String issuerMetadata) { + this.issuerMetadata = issuerMetadata; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { + public @NotNull String replace(@NotNull String text) { String replacement = ""; - if (logIssuer.getAdditionalInformation() != null) - replacement = "/" + logIssuer.getAdditionalInformation(); + if (issuerMetadata != null && !issuerMetadata.isEmpty()) + replacement = "/" + issuerMetadata; - return text.replace("%log_info%", replacement); + return text.replace("%log_metadata%", replacement); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogCodePart.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogOrigin.java similarity index 70% rename from base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogCodePart.java rename to base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogOrigin.java index 7131114..6df6a7f 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogCodePart.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogOrigin.java @@ -20,39 +20,38 @@ package de.staropensource.sosengine.base.internal.placeholders.logger; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; +import java.util.Locale; + /** - * Implements the {@code log_code_part} placeholder. + * Implements the {@code log_origin} placeholder. * * @see Placeholder * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public final class LogCodePart implements Placeholder { +public final class LogOrigin implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer origin to use. * * @since v1-alpha0 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull String issuerOrigin; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerOrigin issuer origin to use * @since v1-alpha0 */ - public LogCodePart(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public LogOrigin(@NotNull String issuerOrigin) { + this.issuerOrigin = issuerOrigin; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%log_code_part%", logIssuer.getCodePart().name()); + public @NotNull String replace(@NotNull String text) { + return text.replace("%log_origin%", issuerOrigin.toUpperCase(Locale.ROOT)); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPackage.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPackage.java index 42747de..3238a91 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPackage.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPackage.java @@ -20,7 +20,6 @@ package de.staropensource.sosengine.base.internal.placeholders.logger; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; /** @@ -32,27 +31,25 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class LogPackage implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer class to use. * * @since v1-alpha0 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull Class issuerClass; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerClass issuer class to use * @since v1-alpha0 */ - public LogPackage(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public LogPackage(@NotNull Class issuerClass) { + this.issuerClass = issuerClass; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%log_package%", logIssuer.getClazz().getPackageName()); + public @NotNull String replace(@NotNull String text) { + return text.replace("%log_package%", issuerClass.getPackageName()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPath.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPath.java index 7b4e462..c429fff 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPath.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/LogPath.java @@ -20,7 +20,6 @@ package de.staropensource.sosengine.base.internal.placeholders.logger; import de.staropensource.sosengine.base.classes.Placeholder; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import org.jetbrains.annotations.NotNull; /** @@ -32,27 +31,26 @@ import org.jetbrains.annotations.NotNull; @SuppressWarnings({ "unused" }) public final class LogPath implements Placeholder { /** - * The {@link LogIssuer} to use. + * Issuer class to use. * * @since v1-alpha0 */ @NotNull - private final LogIssuer logIssuer; + private final Class issuerClass; /** * Constructs this class. * - * @param logIssuer {@link LogIssuer} to use + * @param issuerClass issuer class to use * @since v1-alpha0 */ - public LogPath(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + public LogPath(@NotNull Class issuerClass) { + this.issuerClass = issuerClass; } /** {@inheritDoc} */ - @NotNull @Override - public String replace(@NotNull String text) { - return text.replace("%log_path%", logIssuer.getClazz().getName()); + public @NotNull String replace(@NotNull String text) { + return text.replace("%log_path%", issuerClass.getName()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/package-info.java index f346a2b..7086ebe 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/logger/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains all placeholders used in the {@link de.staropensource.sosengine.base.logging.Logger}. + * Placeholders used in the {@link de.staropensource.sosengine.base.logging.Logger}. * * @see de.staropensource.sosengine.base.logging.Logger * @since v1-alpha0 diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/package-info.java index b861c90..d90e95d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/placeholders/package-info.java @@ -18,7 +18,10 @@ */ /** - * Contains all built-in placeholders used in {@link de.staropensource.sosengine.base.utility.PlaceholderEngine}. + * Built-in placeholders for various things. + *

+ * Placeholder classes in subpackages may only be targeted for + * specific use cases. * * @see de.staropensource.sosengine.base.utility.PlaceholderEngine * @see de.staropensource.sosengine.base.classes.Placeholder diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/ReflectionAccessWidener.java b/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/ReflectionAccessWidener.java index b832f8d..70288a5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/ReflectionAccessWidener.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/ReflectionAccessWidener.java @@ -27,18 +27,26 @@ import de.staropensource.sosengine.base.reflection.ReflectionMethod; import java.lang.reflect.*; /** - * Allows access to fields and methods to be widened. + * Utility class for widening access permissions on reflection objects. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public final class ReflectionAccessWidener { + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public ReflectionAccessWidener() {} + /** * Allows access to an {@link AccessibleObject}. *

* Stolen from the jOOR library. * All credits to them. * + * @param extender of {@link AccessibleObject} * @param accessible object to allow access to */ public static void allowAccess(T accessible) { @@ -58,8 +66,10 @@ public final class ReflectionAccessWidener { * Unlocks modifications to some field. * * @param reflectionField {@link ReflectionField} to unlock - * @return updated modifiers. pass those to {@code lockModifications} after modifying the field - * @see ReflectionAccessWidener#lockModifications(ReflectionField, int) + * @return updated modifiers. pass those to {@link #lockModifications(ReflectionField, int)} to lock the field again + * @throws UnexpectedThrowableException if the {@code modifiers} field is missing + * @throws NoAccessException if access to the field has been denied + * @see #lockModifications(ReflectionField, int) * @since v1-alpha2 */ public static int unlockModifications(ReflectionField reflectionField) throws UnexpectedThrowableException, NoAccessException { @@ -93,8 +103,10 @@ public final class ReflectionAccessWidener { * Unlocks modifications to some method. * * @param reflectionMethod {@link ReflectionMethod} to unlock - * @return updated modifiers. pass those to {@code lockModifications} after modifying the method - * @see ReflectionAccessWidener#lockModifications(ReflectionMethod, int) + * @return updated modifiers. pass those to {@link #lockModifications(ReflectionMethod, int)} to lock the method again + * @throws UnexpectedThrowableException if the {@code modifiers} field is missing + * @throws NoAccessException if access to the method has been denied + * @see #lockModifications(ReflectionMethod, int) * @since v1-alpha2 */ public static int unlockModifications(ReflectionMethod reflectionMethod) throws UnexpectedThrowableException, NoAccessException { @@ -134,10 +146,11 @@ public final class ReflectionAccessWidener { /** * Locks modifications to some field. * - * @param reflectionField {@link ReflectionField} to lock + * @param reflectionField {@link ReflectionField} to lock * @param updatedModifiers original modifiers - * @throws UnexpectedThrowableException if the {@code modifiers} field is not present inside the field - * @see ReflectionAccessWidener#unlockModifications(ReflectionField) + * @throws UnexpectedThrowableException if the {@code modifiers} field is missing + * @throws NoAccessException if access to the field has been denied + * @see #unlockModifications(ReflectionField) * @since v1-alpha2 */ public static void lockModifications(ReflectionField reflectionField, int updatedModifiers) throws UnexpectedThrowableException, NoAccessException { @@ -166,8 +179,9 @@ public final class ReflectionAccessWidener { * * @param reflectionMethod {@link ReflectionMethod} to lock * @param updatedModifiers original modifiers - * @throws UnexpectedThrowableException if the {@code modifiers} field is not present inside the method - * @see ReflectionAccessWidener#unlockModifications(ReflectionMethod) + * @throws UnexpectedThrowableException if the {@code modifiers} field is missing + * @throws NoAccessException if access to the method has been denied + * @see #unlockModifications(ReflectionMethod) * @since v1-alpha2 */ public static void lockModifications(ReflectionMethod reflectionMethod, int updatedModifiers) throws UnexpectedThrowableException, NoAccessException { diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/package-info.java index c979b38..aa19f68 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/reflection/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains utility classes used during reflection. + * Utility classes used during reflection. * * @see de.staropensource.sosengine.base.reflection.Reflect * @since v1-alpha2 diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/types/DependencySubsystemVector.java b/base/src/main/java/de/staropensource/sosengine/base/internal/types/DependencySubsystemVector.java index ba9735f..b287537 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/types/DependencySubsystemVector.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/types/DependencySubsystemVector.java @@ -19,7 +19,7 @@ package de.staropensource.sosengine.base.internal.types; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; +import de.staropensource.sosengine.base.classes.SubsystemClass; import de.staropensource.sosengine.base.classes.VersioningSystem; import de.staropensource.sosengine.base.types.DependencyVector; import lombok.Getter; @@ -29,35 +29,34 @@ import java.util.List; /** * Represents a dependency vector with an additional {@code mainClass} field. - * Used during the subsystem initialization process to easily determine the initialization order - * without much extra code and performance loss. + * Used during the subsystem initialization process to easily determine the + * initialization order without much extra code and performance loss. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class DependencySubsystemVector extends DependencyVector { /** - * Contains the associated {@link SubsystemMainClass}. + * Contains the associated {@link SubsystemClass}. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the associated {@link SubsystemMainClass}. + * Returns the associated {@link SubsystemClass}. * - * @return associated {@link SubsystemMainClass} + * @return associated {@link SubsystemClass} * @since v1-alpha1 */ - private final SubsystemMainClass mainClass; + private final SubsystemClass mainClass; /** - * Creates a new dependency vector. + * Reuses a {@link DependencyVector} instance. * * @param vector existing dependency vector to use - * @param mainClass {@link SubsystemMainClass} to associate + * @param mainClass {@link SubsystemClass} to associate * @since v1-alpha1 */ - public DependencySubsystemVector(@NotNull DependencyVector vector, @NotNull SubsystemMainClass mainClass) { + public DependencySubsystemVector(@NotNull DependencyVector vector, @NotNull SubsystemClass mainClass) { super(mainClass.getName(), vector.getVersioningSystem(), vector.getVersion(), vector.getDependencies()); this.mainClass = mainClass; } @@ -68,10 +67,10 @@ public final class DependencySubsystemVector extends DependencyVector { * @param versioningSystem versioning system to use * @param version version * @param dependencies dependencies in the usual format ({@code dependencyA}, {@code dependencyB=5.1}, {@code dependencyC>3.1}, {@code dependencyD<6.1}) - * @param mainClass {@link SubsystemMainClass} to associate + * @param mainClass {@link SubsystemClass} to associate * @since v1-alpha1 */ - public DependencySubsystemVector(@NotNull Class versioningSystem, @NotNull String version, @NotNull List<@NotNull String> dependencies, @NotNull SubsystemMainClass mainClass) { + public DependencySubsystemVector(@NotNull Class versioningSystem, @NotNull String version, @NotNull List<@NotNull String> dependencies, @NotNull SubsystemClass mainClass) { super(mainClass.getName(), versioningSystem, version, dependencies); this.mainClass = mainClass; } @@ -81,10 +80,10 @@ public final class DependencySubsystemVector extends DependencyVector { * * @param versioningSystem versioning system to use * @param version version - * @param mainClass {@link SubsystemMainClass} to associate + * @param mainClass {@link SubsystemClass} to associate * @since v1-alpha1 */ - public DependencySubsystemVector(@NotNull Class versioningSystem, @NotNull String version, @NotNull SubsystemMainClass mainClass) { + public DependencySubsystemVector(@NotNull Class versioningSystem, @NotNull String version, @NotNull SubsystemClass mainClass) { super(mainClass.getName(), versioningSystem, version); this.mainClass = mainClass; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/types/QueuedLogMessage.java b/base/src/main/java/de/staropensource/sosengine/base/internal/types/QueuedLogMessage.java index d95a3b5..1f3c23d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/types/QueuedLogMessage.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/types/QueuedLogMessage.java @@ -19,72 +19,33 @@ package de.staropensource.sosengine.base.internal.types; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.logging.Logger; import de.staropensource.sosengine.base.types.logging.LogLevel; -import lombok.Getter; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** * Represents a queued log message. * + * @param level Level of the log call. + * @param issuerClass Class of the issuer. + * @param issuerOrigin Origin of the issuer. + * @param issuerMetadata Metadata about the issuer. + * @param message Message of the log call. + * @see Logger#startLoggingThread() * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) -@Getter -public final class QueuedLogMessage { - /** - * The log message's issuer. - * - * @since v1-alpha1 - * - * -- GETTER -- - * Returns the log message's issuer. - * - * @return issuer - * @since v1-alpha1 - */ - @NotNull - private final LogIssuer issuer; - - /** - * The log message's level. - * - * @since v1-alpha1 - * - * -- GETTER -- - * Returns the log message's level. - * - * @return level - * @since v1-alpha1 - */ - @NotNull - private final LogLevel level; - - /** - * The log message. - * - * @since v1-alpha1 - * - * -- GETTER -- - * Returns the log message. - * - * @return message - * @since v1-alpha1 - */ - @NotNull - private final String message; - +@SuppressWarnings({ "unused" }) +public record QueuedLogMessage(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { /** * Creates a new queued log message. * - * @param issuer log message issuer - * @param level log message level - * @param message log message + * @param level level + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha1 */ - public QueuedLogMessage(@NotNull LogIssuer issuer, @NotNull LogLevel level, @NotNull String message) { - this.issuer = issuer; - this.level = level; - this.message = message; - } + public QueuedLogMessage {} } diff --git a/base/src/main/java/de/staropensource/sosengine/base/internal/types/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/internal/types/package-info.java index d60f6e5..f4b194a 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/internal/types/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/internal/types/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains engine-internal data types, usually for passing + * Engine-internal data types, usually for passing * data around classes more efficiently. * * @since v1-alpha1 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 8040473..99d3e5d 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 @@ -25,7 +25,6 @@ import de.staropensource.sosengine.base.classes.Placeholder; import de.staropensource.sosengine.base.events.EngineCrashEvent; import de.staropensource.sosengine.base.events.EngineSoftCrashEvent; import de.staropensource.sosengine.base.internal.placeholders.crashhandler.*; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; import de.staropensource.sosengine.base.utility.PlaceholderEngine; import lombok.Getter; @@ -42,33 +41,29 @@ import java.util.List; * * @see Logger * @see LoggerInstance - * @see LogIssuer * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public final class CrashHandler { /** * Contains the template used to print a crash report. * * @since v1-alpha0 - * * -- GETTER -- * Gets the template used to print a crash report. * * @return crash report template * @since v1-alpha0 - * * -- SETTER -- * Sets the template used to print a crash report. * * @param crashTemplate new crash template * @since v1-alpha0 */ - @NotNull @Getter @Setter - private static String crashTemplate = """ + private static @NotNull String crashTemplate = """ %handled% ------------------------ @@ -94,16 +89,14 @@ Dear developer: FIX YOUR GODDAMN SHIT! Please check if your code or 3rd party su * Contains nested {@link LinkedHashMap}s that contain the content printed at the time of a crash. * * @since v1-alpha0 - * * -- GETTER -- * Returns the nested {@link LinkedHashMap}s that contain the content printed at the time of a crash. * * @return crash content * @since v1-alpha0 */ - @NotNull @Getter - private static final LinkedHashMap<@NotNull Object, @NotNull Object> crashContent = new LinkedHashMap<>(); + private static final @NotNull LinkedHashMap<@NotNull Object, @NotNull Object> crashContent = new LinkedHashMap<>(); /** * Constructs this class. @@ -115,35 +108,38 @@ Dear developer: FIX YOUR GODDAMN SHIT! Please check if your code or 3rd party su /** * Handles a crash. * - * @param logIssuer information about the class that caused the crash - * @param message crash error detail - * @param throwable simply to provide stacktrace and further insight into the crash, can be set to {@code null} + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message crash error detail + * @param throwable simply to provide stacktrace and further insight into the crash, can be set to {@code null} + * @param throwableHandled declares the throwable has handled, not causing the engine to shutdown * @since v1-alpha0 */ - public static synchronized void handleCrash(@NotNull LogIssuer logIssuer, @NotNull String message, @Nullable Throwable throwable, boolean throwableHandled) { + public static synchronized void handleCrash(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @Nullable Throwable throwable, boolean throwableHandled) { if (throwable == null) throwableHandled = false; - String base = crashTemplate; - // This is so simple we don't need the PlaceholderEngine to do it for us - base = base + String base = crashTemplate .replace("%content%", processCrashContent()) .replace("%handled%", throwableHandled ? "!!! This throwable is declared as handled and has been passed down the execution chain !!!" : ""); // Invoke LoggerImpl#prePlaceholder - base = Logger.getLoggerImplementation().prePlaceholder(LogLevel.CRASH, logIssuer, base); + String temp = Logger.getLoggerImplementation().prePlaceholder(LogLevel.CRASH, issuerClass, issuerOrigin, issuerMetadata, message, base); + if (temp != null) + base = temp; // Create list of temporary placeholders List<@NotNull Placeholder> temporaryPlaceholders = new ArrayList<>(); - temporaryPlaceholders.add(new IssuerMessage(message)); // log_message is out of order to allow for placeholder usage + temporaryPlaceholders.add(new CrashMessage(message)); // log_message is out of order to allow for placeholder usage // issuer_* - temporaryPlaceholders.add(new IssuerClass(logIssuer)); - temporaryPlaceholders.add(new IssuerCodePart(logIssuer)); - temporaryPlaceholders.add(new IssuerInfo(logIssuer)); - temporaryPlaceholders.add(new IssuerPackage(logIssuer)); - temporaryPlaceholders.add(new IssuerPath(logIssuer)); + temporaryPlaceholders.add(new IssuerClass(issuerClass)); + temporaryPlaceholders.add(new IssuerOrigin(issuerOrigin)); + temporaryPlaceholders.add(new IssuerMetadata(issuerMetadata)); + temporaryPlaceholders.add(new IssuerPackage(issuerClass)); + temporaryPlaceholders.add(new IssuerPath(issuerClass)); // stacktrace* temporaryPlaceholders.add(new Stacktrace(throwable)); temporaryPlaceholders.add(new StacktraceAll()); @@ -152,10 +148,10 @@ Dear developer: FIX YOUR GODDAMN SHIT! Please check if your code or 3rd party su base = PlaceholderEngine.getInstance().process(base, temporaryPlaceholders); // Invoke LoggerImpl#postPlaceholder - base = Logger.getLoggerImplementation().postPlaceholder(LogLevel.CRASH, logIssuer, base); + base = Logger.getLoggerImplementation().postPlaceholder(LogLevel.CRASH, issuerClass, issuerOrigin, issuerMetadata, message, base); // Print log message by invoking LoggerImpl#print - Logger.getLoggerImplementation().print(LogLevel.CRASH, logIssuer, base); + Logger.getLoggerImplementation().print(LogLevel.CRASH, issuerClass, issuerOrigin, issuerMetadata, message, base); // Emit event if (throwableHandled) @@ -163,7 +159,7 @@ Dear developer: FIX YOUR GODDAMN SHIT! Please check if your code or 3rd party su else new EngineCrashEvent().callEvent(); - // Shutdown (engine &) JVM + // Shutdown engine/JVM if (!throwableHandled) if (EngineConfiguration.getInstance().isLoggerImmediateShutdown()) Runtime.getRuntime().halt(69); @@ -177,7 +173,7 @@ Dear developer: FIX YOUR GODDAMN SHIT! Please check if your code or 3rd party su * @param map {@link LinkedHashMap} to process * @param indentationSize indentation level * @return crash content string - * @see CrashHandler#processCrashContent() + * @see #processCrashContent() * @since v1-alpha0 */ /* @@ -190,8 +186,7 @@ Dear developer: FIX YOUR GODDAMN SHIT! Please check if your code or 3rd party su * * But hey, if someone breaks this method (which may be possible idk didn't test it) then congrats! */ - @NotNull - private static synchronized String processCrashContent(@NotNull LinkedHashMap map, int indentationSize) { + private static synchronized @NotNull String processCrashContent(@NotNull LinkedHashMap map, int indentationSize) { StringBuilder content = new StringBuilder(); for (Object key : map.keySet()) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/Logger.java b/base/src/main/java/de/staropensource/sosengine/base/logging/Logger.java index f67a90b..a3bf048 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/logging/Logger.java +++ b/base/src/main/java/de/staropensource/sosengine/base/logging/Logger.java @@ -21,14 +21,13 @@ package de.staropensource.sosengine.base.logging; import de.staropensource.sosengine.base.Engine; import de.staropensource.sosengine.base.EngineConfiguration; -import de.staropensource.sosengine.base.classes.LoggerImpl; +import de.staropensource.sosengine.base.classes.LoggerImplementation; import de.staropensource.sosengine.base.classes.Placeholder; import de.staropensource.sosengine.base.classes.helpers.EventHelper; import de.staropensource.sosengine.base.events.LogEvent; import de.staropensource.sosengine.base.internal.placeholders.logger.*; import de.staropensource.sosengine.base.internal.types.QueuedLogMessage; -import de.staropensource.sosengine.base.logging.implementation.PlainLoggerImpl; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.logging.implementation.PlainLoggerImplementation; import de.staropensource.sosengine.base.types.logging.LogLevel; import de.staropensource.sosengine.base.types.logging.LogRule; import de.staropensource.sosengine.base.types.logging.LogRuleType; @@ -43,57 +42,53 @@ import java.util.LinkedList; import java.util.List; /** - * Provides the engine's logging infrastructure except for the {@link CrashHandler}. + * Provides the engine's logging infrastructure, + * except for crash handling, which the + * {@link CrashHandler} does. * * @see CrashHandler * @see LoggerInstance - * @see LogIssuer * @see LogLevel */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public final class Logger { /** - * Refers to the active {@link LoggerImpl} that is used to process and print log messages. + * Refers to the active {@link LoggerImplementation} that is used to process and print log messages. * - * @see LoggerImpl + * @see LoggerImplementation * @since v1-alpha0 - * * -- GETTER -- - * Returns the active {@link LoggerImpl}. + * Returns the active {@link LoggerImplementation}. * - * @return active {@link LoggerImpl} - * @see LoggerImpl + * @return active {@link LoggerImplementation} + * @see LoggerImplementation * @since v1-alpha0 - * * -- SETTER -- - * Sets the active {@link LoggerImpl}. + * Sets the active {@link LoggerImplementation}. * - * @param loggerImplementation new active {@link LoggerImpl} - * @see LoggerImpl + * @param loggerImplementation new active {@link LoggerImplementation} + * @see LoggerImplementation * @since v1-alpha0 */ - @NotNull @Getter @Setter - private static LoggerImpl loggerImplementation = new PlainLoggerImpl(); + private static @NotNull LoggerImplementation loggerImplementation = new PlainLoggerImplementation(); /** - * Refers to the logging thread. + * Contains a reference to the logging thread. * * @since v1-alpha1 - * * -- GETTER -- - * Returns the logging thread. + * Returns a reference the logging thread. * - * @return logging thread + * @return logging thread reference * @since v1-alpha1 */ @Getter - @Nullable - private static Thread loggingThread; + private static @Nullable Thread loggingThread; /** - * A list of {@link QueuedLogMessage}s. + * Contains a list of {@link QueuedLogMessage}s. * * @since v1-alpha1 */ @@ -103,7 +98,6 @@ public final class Logger { * Contains all active {@link LogRule}s. * * @since v1-alpha1 - * * -- GETTER -- * Returns all active {@link LogRule}s. * @@ -124,7 +118,7 @@ public final class Logger { * Starts the logging thread. * * @since v1-alpha1 - * @see Logger#loggingThread + * @see #getLoggingThread() */ public static void startLoggingThread() { if (loggingThread == null) { @@ -175,7 +169,7 @@ public final class Logger { // Invoke processLogMessage method for every queued message for (QueuedLogMessage queuedLogMessage : queuedMessagesCloned) { - processLogMessage(queuedLogMessage.getIssuer(), queuedLogMessage.getLevel(), queuedLogMessage.getMessage()); + processLogMessage(queuedLogMessage.level(), queuedLogMessage.issuerClass(), queuedLogMessage.issuerOrigin(), queuedLogMessage.issuerMetadata(), queuedLogMessage.message()); } } } @@ -183,25 +177,26 @@ public final class Logger { /** * Processes a log message. * - * @param issuer log issuer - * @param level log level - * @param message log message + * @param level level + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha1 */ - private static void processLogMessage(@NotNull LogIssuer issuer, @NotNull LogLevel level, @NotNull String message) { + private static void processLogMessage(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { // Evaluate all active rules for (LogRule rule : activeRules) { - if (rule.evaluate(issuer, level, message)) { + if (rule.evaluate(level, issuerClass, issuerOrigin, issuerMetadata, message)) { if (rule.getType() == LogRuleType.WHITELIST) break; // Continue processing if (rule.getType() == LogRuleType.BLACKLIST) return; // Cancel processing } } - // Template for now, final log message later - String base = EngineConfiguration.getInstance().getLoggerTemplate(); - // Invoke LoggerImpl#prePlaceholder - base = loggerImplementation.prePlaceholder(level, issuer, base); + String base = loggerImplementation.prePlaceholder(level, issuerClass, issuerOrigin, issuerMetadata, message, EngineConfiguration.getInstance().getLoggerTemplate()); + if (base == null) + base = EngineConfiguration.getInstance().getLoggerTemplate(); // Create list of temporary placeholders List<@NotNull Placeholder> temporaryPlaceholders = new ArrayList<>(); @@ -209,37 +204,39 @@ public final class Logger { temporaryPlaceholders.add(new LogColorPrimary(level)); temporaryPlaceholders.add(new LogColorSecondary(level)); - temporaryPlaceholders.add(new LogClass(issuer)); + temporaryPlaceholders.add(new LogClass(issuerClass)); temporaryPlaceholders.add(new LogColorPrimary(level)); - temporaryPlaceholders.add(new LogInfo(issuer)); + temporaryPlaceholders.add(new LogMetadata(issuerMetadata)); temporaryPlaceholders.add(new de.staropensource.sosengine.base.internal.placeholders.logger.LogLevel(level)); - temporaryPlaceholders.add(new LogPackage(issuer)); - temporaryPlaceholders.add(new LogPath(issuer)); + temporaryPlaceholders.add(new LogPackage(issuerClass)); + temporaryPlaceholders.add(new LogPath(issuerClass)); // Replace placeholders base = PlaceholderEngine.getInstance().process(base, temporaryPlaceholders); // Invoke LoggerImpl#postPlaceholder - base = loggerImplementation.postPlaceholder(level, issuer, base); + base = loggerImplementation.postPlaceholder(level, issuerClass, issuerOrigin, issuerMetadata, message, base); // Call event - if (!(issuer.getClazz().getName().equals("de.staropensource.sosengine.slf4j_compat.CompatibilityLogger") - || issuer.getClazz().equals(EventHelper.class))) - new LogEvent().callEvent(level, issuer, message); + if (!(issuerClass.getName().equals("de.staropensource.sosengine.slf4j_compat.CompatibilityLogger") + || issuerClass.equals(EventHelper.class))) + new LogEvent().callEvent(level, issuerClass, issuerOrigin, issuerMetadata, message); // Print log message by invoking LoggerImpl#print - loggerImplementation.print(level, issuer, base); + loggerImplementation.print(level, issuerClass, issuerOrigin, issuerMetadata, message, base); } /** * Handler for all log messages. * - * @param issuer log issuer - * @param level log level - * @param message log message + * @param level level + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - private static synchronized void log(@NotNull LogIssuer issuer, @NotNull LogLevel level, @NotNull String message) { + private static synchronized void log(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { // Check if engine has initialized if (Engine.getInstance() == null) return; @@ -249,111 +246,129 @@ public final class Logger { if (EngineConfiguration.getInstance().isOptimizeLogging()) // Optimizations enabled, add to message queue - queuedMessages.add(new QueuedLogMessage(issuer, level, message)); + queuedMessages.add(new QueuedLogMessage(level, issuerClass, issuerOrigin, issuerMetadata, message)); else // Optimizations disabled, print right away - processLogMessage(issuer, level, message); + processLogMessage(level, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Prints a diagnostic message. * - * @param logIssuer issuing class - * @param message diagnostic message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void diag(@NotNull LogIssuer logIssuer, @NotNull String message) { - log(logIssuer, LogLevel.DIAGNOSTIC, message); + public static void diag(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + log(LogLevel.DIAGNOSTIC, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Prints a verbose message. * - * @param logIssuer issuing class - * @param message verbose message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void verb(@NotNull LogIssuer logIssuer, @NotNull String message) { - log(logIssuer, LogLevel.VERBOSE, message); + public static void verb(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + log(LogLevel.VERBOSE, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Prints a silent warning message. * - * @param logIssuer issuing class - * @param message silent warning message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void sarn(@NotNull LogIssuer logIssuer, @NotNull String message) { - log(logIssuer, LogLevel.SILENT_WARNING, message); + public static void sarn(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + log(LogLevel.SILENT_WARNING, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Prints an informational message. * - * @param logIssuer issuing class - * @param message informational message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void info(@NotNull LogIssuer logIssuer, @NotNull String message) { - log(logIssuer, LogLevel.INFORMATIONAL, message); + public static void info(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + log(LogLevel.INFORMATIONAL, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Prints a warning message. * - * @param logIssuer issuing class - * @param message warning message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void warn(@NotNull LogIssuer logIssuer, @NotNull String message) { - log(logIssuer, LogLevel.WARNING, message); + public static void warn(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + log(LogLevel.WARNING, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Prints an error message. * - * @param logIssuer issuing class - * @param message error message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void error(@NotNull LogIssuer logIssuer, @NotNull String message) { - log(logIssuer, LogLevel.ERROR, message); + public static void error(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + log(LogLevel.ERROR, issuerClass, issuerOrigin, issuerMetadata, message); } /** * Crashes the entire engine. * - * @param logIssuer issuing class - * @param message diagnostic message - * @param throwable the throwable that caused this crash - * @param handled declare the throwable has handled + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message + * @param throwable the throwable that caused this crash + * @param handled declares the throwable has handled, not causing the engine to shutdown * @since v1-alpha0 */ - public static void crash(@NotNull LogIssuer logIssuer, @NotNull String message, @NotNull Throwable throwable, boolean handled) { - CrashHandler.handleCrash(logIssuer, message, throwable, handled); + public static void crash(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull Throwable throwable, boolean handled) { + CrashHandler.handleCrash(issuerClass, issuerOrigin, issuerMetadata, message, throwable, handled); } /** * Crashes the entire engine. * - * @param logIssuer issuing class - * @param message diagnostic message - * @param throwable the throwable that caused this crash + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message + * @param throwable the throwable that caused this crash * @since v1-alpha0 */ - public static void crash(@NotNull LogIssuer logIssuer, @NotNull String message, @NotNull Throwable throwable) { - CrashHandler.handleCrash(logIssuer, message, throwable, false); + public static void crash(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull Throwable throwable) { + CrashHandler.handleCrash(issuerClass, issuerOrigin, issuerMetadata, message, throwable, false); } /** * Crashes the entire engine. * - * @param logIssuer issuing class - * @param message diagnostic message + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message message * @since v1-alpha0 */ - public static void crash(@NotNull LogIssuer logIssuer, @NotNull String message) { - CrashHandler.handleCrash(logIssuer, message, null, false); + public static void crash(@NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + CrashHandler.handleCrash(issuerClass, issuerOrigin, issuerMetadata, message, null, false); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/LoggerInstance.java b/base/src/main/java/de/staropensource/sosengine/base/logging/LoggerInstance.java index cb3edec..ec58257 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/logging/LoggerInstance.java +++ b/base/src/main/java/de/staropensource/sosengine/base/logging/LoggerInstance.java @@ -19,135 +19,290 @@ package de.staropensource.sosengine.base.logging; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import lombok.Getter; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** * Removes the need to add {@code getClass} to all calls to {@link Logger}. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class LoggerInstance { /** - * Contains the class that this {@link LoggerInstance} belongs to. - * - * @since v1-alpha0 + * Contains the {@link Class} of the issuer. * + * @since v1-alpha2 * -- GETTER -- - * Returns the class that this {@link LoggerInstance} belongs to. + * Returns the {@link Class} of the issuer. * - * @return the parent class - * @since v1-alpha0 + * @return class of the issuer + * @since v1-alpha2 */ - @NotNull - private final LogIssuer logIssuer; + private final @NotNull Class clazz; /** - * Creates a logger instance. + * Contains the metadata about the issuer. * - * @param logIssuer information about the parent class + * @since v1-alpha2 + * -- GETTER -- + * Returns the metadata about the issuer. + * + * @return metadata about the issuer + * @since v1-alpha2 + */ + private final @Nullable String metadata; + + /** + * Contains the origin of the issuer. + * + * @since v1-alpha2 + * -- GETTER -- + * Returns the origin of the issuer. + * + * @return origin of the issuer + * @since v1-alpha2 + */ + private final @NotNull String origin; + + /** + * Creates a new logger instance. + * + * @param clazz class of the issuer + * @param origin origin of the issuer + * @param metadata metadata about the issuer * @since v1-alpha0 */ - public LoggerInstance(@NotNull LogIssuer logIssuer) { - this.logIssuer = logIssuer; + private LoggerInstance(@NotNull Class clazz, @NotNull String origin, @Nullable String metadata) { + this.clazz = clazz; + this.origin = origin; + this.metadata = metadata; } /** * Prints a diagnostic message. * - * @param message diagnostic message + * @param message message * @since v1-alpha0 */ public void diag(@NotNull String message) { - Logger.diag(logIssuer, message); + Logger.diag(clazz, origin, metadata, message); } /** * Prints a verbose message. * - * @param message verbose message + * @param message message * @since v1-alpha0 */ public void verb(@NotNull String message) { - Logger.verb(logIssuer, message); + Logger.verb(clazz, origin, metadata, message); } /** * Prints a silent warning message. * - * @param message silent warning message + * @param message message * @since v1-alpha0 */ public void sarn(@NotNull String message) { - Logger.sarn(logIssuer, message); + Logger.sarn(clazz, origin, metadata, message); } /** * Prints an informational message. * - * @param message informational message + * @param message message * @since v1-alpha0 */ public void info(@NotNull String message) { - Logger.info(logIssuer, message); + Logger.info(clazz, origin, metadata, message); } /** * Prints a warning message. * - * @param message warning message + * @param message message * @since v1-alpha0 */ public void warn(@NotNull String message) { - Logger.warn(logIssuer, message); + Logger.warn(clazz, origin, metadata, message); } /** * Prints an error message. * - * @param message error message + * @param message message * @since v1-alpha0 */ public void error(@NotNull String message) { - Logger.error(logIssuer, message); + Logger.error(clazz, origin, metadata, message); } /** * Crashes the entire engine. * - * @param message diagnostic message - * @param throwable throwable that caused this crash - * @param handled declare the throwable has handled + * @param message message + * @param throwable throwable that caused the crash + * @param handled declares the throwable has handled * @see CrashHandler * @since v1-alpha0 */ public void crash(@NotNull String message, @NotNull Throwable throwable, boolean handled) { - Logger.crash(logIssuer, message, throwable, handled); + Logger.crash(clazz, origin, metadata, message, throwable, handled); } /** * Crashes the entire engine. * - * @param message diagnostic message - * @param throwable throwable that caused this crash + * @param message message + * @param throwable throwable that caused the crash * @see CrashHandler * @since v1-alpha0 */ public void crash(@NotNull String message, @NotNull Throwable throwable) { - Logger.crash(logIssuer, message, throwable); + Logger.crash(clazz, origin, metadata, message, throwable); } /** * Crashes the entire engine. * - * @param message diagnostic message + * @param message message * @see CrashHandler * @since v1-alpha0 */ public void crash(@NotNull String message) { - Logger.crash(logIssuer, message); + Logger.crash(clazz, origin, metadata, message); + } + + /** + * Provides an API for building {@link LoggerInstance}s more easily. + * + * @since v1-alpha2 + */ + @SuppressWarnings({ "unused" }) + public static final class Builder { + /** + * Contains the class of the issuer. + * + * @see LoggerInstance#clazz + * @since v1-alpha2 + */ + private @Nullable Class clazz = null; + + /** + * Contains the origin of the issuer. + * + * @see LoggerInstance#origin + * @since v1-alpha2 + */ + private @Nullable String origin = null; + + /** + * Contains metadata about the issuer. + * + * @see LoggerInstance#metadata + * @since v1-alpha2 + */ + private @Nullable String metadata = null; + + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public Builder() {} + + /** + * Builds a new {@link LoggerInstance} instance. + * + * @return new {@link LoggerInstance} + * @throws IllegalStateException if the class or origin is unset + * @since v1-alpha2 + */ + public LoggerInstance build() throws IllegalStateException { + // Check for required fields + if (clazz == null) + throw new IllegalStateException("The class is unset."); + + // Set defaults + if (origin == null || origin.isEmpty()) + origin = "APPLICATION"; + if (metadata == null || metadata.isEmpty()) + metadata = null; + + return new LoggerInstance(clazz, origin, metadata); + } + + /** + * Returns the class of the issuer. + * + * @return class of the issuer + * @see LoggerInstance#clazz + * @since v1-alpha2 + */ + public @Nullable Class getClazz() { + return clazz; + } + + /** + * Returns the origin of the issuer. + * + * @return origin of the issuer + * @see LoggerInstance#origin + * @since v1-alpha2 + */ + public @Nullable String getOrigin() { + return origin; + } + + /** + * Returns metadata about the issuer. + * + * @return metadata about the issuer + * @see LoggerInstance#metadata + * @since v1-alpha2 + */ + public @Nullable String getMetadata() { + return metadata; + } + + /** + * Sets the class of the issuer. + * + * @param clazz new class of the issuer + * @return builder instance + * @since v1-alpha2 + */ + public @NotNull Builder setClazz(@Nullable Class clazz) { + this.clazz = clazz; + return this; + } + + /** + * Sets the origin of the issuer. + * + * @param origin new origin of the issuer + * @return builder instance + * @since v1-alpha2 + */ + public @NotNull Builder setOrigin(@Nullable String origin) { + this.origin = origin; + return this; + } + + /** + * Sets the metadata about the issuer. + * + * @param metadata new metadata about the issuer + * @return builder instance + * @since v1-alpha2 + */ + public @NotNull Builder setMetadata(@Nullable String metadata) { + this.metadata = metadata; + return this; + } } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/PlainLoggerImpl.java b/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/PlainLoggerImplementation.java similarity index 69% rename from base/src/main/java/de/staropensource/sosengine/base/logging/implementation/PlainLoggerImpl.java rename to base/src/main/java/de/staropensource/sosengine/base/logging/implementation/PlainLoggerImplementation.java index d3cad51..33a8a81 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/PlainLoggerImpl.java +++ b/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/PlainLoggerImplementation.java @@ -20,48 +20,46 @@ package de.staropensource.sosengine.base.logging.implementation; import de.staropensource.sosengine.base.EngineConfiguration; -import de.staropensource.sosengine.base.classes.LoggerImpl; +import de.staropensource.sosengine.base.classes.LoggerImplementation; import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; import de.staropensource.sosengine.base.utility.converter.EmptyShortcodeConverter; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** * Prints log messages to the console, without any fancy colors or formatting. * * @see Logger - * @see LoggerImpl + * @see LoggerImplementation * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) -public class PlainLoggerImpl implements LoggerImpl { +public class PlainLoggerImplementation implements LoggerImplementation { /** * Constructs this class. * * @since v1-alpha1 */ - public PlainLoggerImpl() {} + public PlainLoggerImplementation() {} /** {@inheritDoc} */ - @NotNull @Override - public String prePlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String message) { - // No modifications necessary - return message; - } - - /** {@inheritDoc} */ - @NotNull - @Override - public String postPlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format) { + public @NotNull String prePlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { // No modifications necessary return format; } /** {@inheritDoc} */ @Override - public void print(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format) { + public @NotNull String postPlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { + // No modifications necessary + return format; + } + + /** {@inheritDoc} */ + @Override + public void print(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { format = new EmptyShortcodeConverter(format, true).getClean(); if (level == LogLevel.ERROR || level == LogLevel.CRASH) if (EngineConfiguration.getInstance().isLoggerForceStandardOutput()) diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/RawLoggerImpl.java b/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/RawLoggerImplementation.java similarity index 66% rename from base/src/main/java/de/staropensource/sosengine/base/logging/implementation/RawLoggerImpl.java rename to base/src/main/java/de/staropensource/sosengine/base/logging/implementation/RawLoggerImplementation.java index d65f10b..f42cf52 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/RawLoggerImpl.java +++ b/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/RawLoggerImplementation.java @@ -20,48 +20,46 @@ package de.staropensource.sosengine.base.logging.implementation; import de.staropensource.sosengine.base.EngineConfiguration; -import de.staropensource.sosengine.base.classes.LoggerImpl; +import de.staropensource.sosengine.base.classes.LoggerImplementation; import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** * Prints log messages to the console, without performing any message changes. - * Does reveal shortcodes as they are not automatically replaced. + * Will reveal shortcodes as they will not be replaced. * * @see Logger - * @see LoggerImpl + * @see LoggerImplementation * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) -public class RawLoggerImpl implements LoggerImpl { +public class RawLoggerImplementation implements LoggerImplementation { /** * Constructs this class. * * @since v1-alpha1 */ - public RawLoggerImpl() {} + public RawLoggerImplementation() {} /** {@inheritDoc} */ - @NotNull @Override - public String prePlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String message) { - // No modifications necessary - return message; - } - - /** {@inheritDoc} */ - @NotNull - @Override - public String postPlaceholder(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format) { + public @NotNull String prePlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { // No modifications necessary return format; } /** {@inheritDoc} */ @Override - public void print(@NotNull LogLevel level, @NotNull LogIssuer logIssuer, @NotNull String format) { + public @NotNull String postPlaceholder(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { + // No modifications necessary + return format; + } + + /** {@inheritDoc} */ + @Override + public void print(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message, @NotNull String format) { if (level == LogLevel.ERROR || level == LogLevel.CRASH) if (EngineConfiguration.getInstance().isLoggerForceStandardOutput()) System.out.println(format); diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/package-info.java index f7e6305..1413de0 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/logging/implementation/package-info.java @@ -18,8 +18,7 @@ */ /** - * Contains a set of built-in logger implementations - * that all print log output a bit differently. + * A set of built-in {@link de.staropensource.sosengine.base.classes.LoggerImplementation}s. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/logging/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/logging/package-info.java index 8f89a15..7433b8d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/logging/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/logging/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains sos!engine's logging infrastructure. + * The engine's custom logging infrastructure. * * @see de.staropensource.sosengine.base.logging.Logger * @see de.staropensource.sosengine.base.logging.LoggerInstance diff --git a/base/src/main/java/de/staropensource/sosengine/base/reflection/ClasspathAccess.java b/base/src/main/java/de/staropensource/sosengine/base/reflection/ClasspathAccess.java index 3e67b63..4b9b126 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/reflection/ClasspathAccess.java +++ b/base/src/main/java/de/staropensource/sosengine/base/reflection/ClasspathAccess.java @@ -19,9 +19,7 @@ package de.staropensource.sosengine.base.reflection; -import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.logging.LoggerInstance; import org.jetbrains.annotations.NotNull; import java.io.File; @@ -42,14 +40,28 @@ import java.util.Map; */ @SuppressWarnings({ "unused" }) public final class ClasspathAccess { + /** + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha2 + */ + private static final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(ClasspathAccess.class).setOrigin("ENGINE").build(); + + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public ClasspathAccess() {} + /** * Returns the classpath as a collection of {@link URL}s. * * @return collection of classpath urls * @since v1-alpha2 */ - @NotNull - public static Collection getClasspathURLs() { + public static @NotNull Collection getClasspathURLs() { Collection urls = new ArrayList<>(); String javaClassPath = System.getProperty("java.class.path"); @@ -58,7 +70,7 @@ public final class ClasspathAccess { try { urls.add(new File(path).toURI().toURL()); } catch (Exception exception) { - Logger.crash(new LogIssuer(ClasspathAccess.class, CodePart.ENGINE), "Failed converting classpath to URL", exception); + logger.crash("Failed converting classpath to URL", exception); } return fixURLs(urls); @@ -73,8 +85,7 @@ public final class ClasspathAccess { * @return fixed urls * @since v1-alpha2 */ - @NotNull - private static Collection fixURLs(@NotNull Collection urls) { + private static @NotNull Collection fixURLs(@NotNull Collection urls) { Map distinct = new LinkedHashMap<>(urls.size()); for (URL url : urls) { distinct.put(url.toExternalForm(), url); diff --git a/base/src/main/java/de/staropensource/sosengine/base/reflection/Reflect.java b/base/src/main/java/de/staropensource/sosengine/base/reflection/Reflect.java index f43f7a3..5332911 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/reflection/Reflect.java +++ b/base/src/main/java/de/staropensource/sosengine/base/reflection/Reflect.java @@ -32,38 +32,42 @@ import java.lang.reflect.Method; @SuppressWarnings({ "unused" }) public final class Reflect { /** - * Allows reflecting on some class. + * Constructs this class. + * + * @since v1-alpha2 + */ + public Reflect() {} + + /** + * Reflect on a {@link Class}. * * @param clazz class to reflect on * @return new {@link ReflectionClass} * @since v1-alpha2 */ - @NotNull - public static ReflectionClass reflectOn(@NotNull Class clazz) { + public static @NotNull ReflectionClass reflectOn(@NotNull Class clazz) { return new ReflectionClass(clazz); } /** - * Allows reflecting on some method. + * Reflect on a {@link Method}. * * @param method method to reflect on * @return new {@link ReflectionMethod} * @since v1-alpha2 */ - @NotNull public static ReflectionMethod reflectOn(@NotNull Method method) { return new ReflectionMethod(method); } /** - * Allows reflecting on some field. + * Reflect on a {@link Field}. * * @param field field to reflect on * @return new {@link ReflectionField} * @since v1-alpha2 */ - @NotNull - public static ReflectionField reflectOn(@NotNull Field field) { + public static @NotNull ReflectionField reflectOn(@NotNull Field field) { return new ReflectionField(field); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionClass.java b/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionClass.java index 6490155..7dd7210 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionClass.java +++ b/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionClass.java @@ -25,33 +25,19 @@ import de.staropensource.sosengine.base.exceptions.reflection.InvalidFieldExcept import de.staropensource.sosengine.base.exceptions.reflection.InvalidMethodException; import de.staropensource.sosengine.base.types.reflection.ClassType; import de.staropensource.sosengine.base.types.reflection.VisibilityModifier; -import lombok.Getter; import org.jetbrains.annotations.NotNull; import java.lang.annotation.Annotation; import java.lang.reflect.Modifier; /** - * Allows reflection on classes. + * Reflection helper for {@link Class}es. * + * @param clazz class to reflect on * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) -@Getter -public final class ReflectionClass { - /** - * The class to reflect on. - * - * @since v1-alpha2 - * - * -- GETTER -- - * Returns the class to reflect on. - * - * @return class reference - * @since v1-alpha2 - */ - private final Class clazz; - +@SuppressWarnings({ "unused" }) +public record ReflectionClass(Class clazz) { /** * Constructs this class. * @@ -112,9 +98,10 @@ public final class ReflectionClass { try { if ((boolean) clazz.getMethod("isUnnamedClass").invoke(clazz)) return ClassType.CLASS; - } catch (Exception ignored) {} + } catch (Exception ignored) { + } } - return ClassType.UNKNOWN; + return ClassType.UNKNOWN; } /** @@ -155,7 +142,7 @@ public final class ReflectionClass { */ public boolean isAbstract() throws IncompatibleTypeException { if (getType() != ClassType.CLASS) - throw new IncompatibleTypeException("isAbstract", getType(), new ClassType[]{ClassType.CLASS}); + throw new IncompatibleTypeException("isAbstract", getType(), new ClassType[]{ ClassType.CLASS }); return Modifier.isAbstract(clazz.getModifiers()); } @@ -183,7 +170,8 @@ public final class ReflectionClass { /** * Returns the specified method. * - * @param methodName name of the method + * @param methodName name of the method + * @param methodArguments arguments of the method * @return new {@link ReflectionMethod} instance * @throws InvalidMethodException if the method does not exist * @since v1-alpha2 diff --git a/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionField.java b/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionField.java index 2978aae..6ff69d8 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionField.java +++ b/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionField.java @@ -26,45 +26,44 @@ import de.staropensource.sosengine.base.internal.reflection.ReflectionAccessWide import de.staropensource.sosengine.base.types.reflection.VisibilityModifier; import lombok.Getter; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import java.lang.annotation.Annotation; import java.lang.reflect.Field; import java.lang.reflect.Modifier; /** - * Allows reflection on methods. + * Reflection helper for {@link Field}s. * * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class ReflectionField { /** - * The class the method is contained in. + * Contains a reference to the parent class. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the class the method is contained in. + * Returns a reference to the parent class. * - * @return parent class + * @return parent class reference * @since v1-alpha2 */ - private final Class parentClass; + private final @Nullable Class parentClass; /** - * The field to reflect on. + * Contains a reference to the field to reflect on. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the field to reflect on. + * Returns a reference to the field to reflect on. * * @return field reference * @since v1-alpha2 */ - private final Field field; + private final @NotNull Field field; /** * Constructs this class. @@ -79,7 +78,7 @@ public final class ReflectionField { /** * Constructs this class. * - * @param parentClass clazz this field is contained in + * @param parentClass parent class of field * @param field field to reflect on */ public ReflectionField(@NotNull Class parentClass, @NotNull Field field) { @@ -160,7 +159,7 @@ public final class ReflectionField { * * @param newValue new presence of the {@code final} modifier * @throws UnexpectedThrowableException if the {@code modifiers} field is missing - * @throws NoAccessException if access to the {@code modifiers} field has been denied + * @throws NoAccessException if access to the {@code modifiers} field has been denied * @since v1-alpha2 */ public void setFinal(boolean newValue) throws UnexpectedThrowableException, NoAccessException { @@ -195,7 +194,7 @@ public final class ReflectionField { * * @param newValue new presence of the {@code static} modifier * @throws UnexpectedThrowableException if the {@code modifiers} field is missing - * @throws NoAccessException if access to the {@code modifiers} field has been denied + * @throws NoAccessException if access to the {@code modifiers} field has been denied * @since v1-alpha2 */ public void setStatic(boolean newValue) throws UnexpectedThrowableException, NoAccessException { @@ -230,7 +229,7 @@ public final class ReflectionField { * * @param newValue new presence of the {@code transient} modifier * @throws UnexpectedThrowableException if the {@code modifiers} field is missing - * @throws NoAccessException if access to the {@code modifiers} field has been denied + * @throws NoAccessException if access to the {@code modifiers} field has been denied * @since v1-alpha2 */ public void setTransient(boolean newValue) throws UnexpectedThrowableException, NoAccessException { @@ -265,7 +264,7 @@ public final class ReflectionField { * * @param newValue new presence of the {@code volatile} modifier * @throws UnexpectedThrowableException if the {@code modifiers} field is missing - * @throws NoAccessException if access to the {@code modifiers} field has been denied + * @throws NoAccessException if access to the {@code modifiers} field has been denied * @since v1-alpha2 */ public void setVolatile(boolean newValue) throws UnexpectedThrowableException, NoAccessException { @@ -342,6 +341,7 @@ public final class ReflectionField { * Updates the field with a new value. * * @param newValue new value + * @throws NoAccessException if access to the field has been denied * @since v1-alpha2 */ public void setValue(Object newValue) throws NoAccessException { @@ -356,6 +356,7 @@ public final class ReflectionField { * Updates the field with a new value. * * @return field's value + * @throws NoAccessException if access to the field has been denied * @since v1-alpha2 */ public Object getValue() throws NoAccessException { diff --git a/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionMethod.java b/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionMethod.java index 657f963..9e1c26c 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionMethod.java +++ b/base/src/main/java/de/staropensource/sosengine/base/reflection/ReflectionMethod.java @@ -38,33 +38,31 @@ import java.lang.reflect.Method; import java.lang.reflect.Modifier; /** - * Allows reflection on methods. + * Reflection helper for {@link Method}s. * * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public final class ReflectionMethod { /** - * The class the method is contained in. + * Contains a reference to the parent class. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the class the method is contained in. + * Returns a reference to the parent class. * - * @return parent class + * @return parent class reference * @since v1-alpha2 */ private final Class parentClass; /** - * The method to reflect on. + * Contains a reference to the method to reflect on. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the method to reflect on. + * Returns a reference to the method to reflect on. * * @return method reference * @since v1-alpha2 @@ -84,7 +82,7 @@ public final class ReflectionMethod { /** * Constructs this class. * - * @param parentClass clazz this method is contained in + * @param parentClass parent class of method * @param method method to reflect on */ public ReflectionMethod(@NotNull Class parentClass, @NotNull Method method) { @@ -328,8 +326,7 @@ public final class ReflectionMethod { * @return method return type * @since v1-alpha2 */ - @NotNull - public Class getReturnType() { + public @NotNull Class getReturnType() { return method.getReturnType(); } @@ -357,14 +354,14 @@ public final class ReflectionMethod { * @throws StaticInitializerException when an the static initializer fails * @since v1-alpha2 */ - @Nullable - public Object invoke() throws UnexpectedThrowableException, NoAccessException, InvalidMethodSignature, InvocationTargetException, InstanceMethodFromStaticContextException, StaticInitializerException { + public @Nullable Object invoke() throws UnexpectedThrowableException, NoAccessException, InvalidMethodSignature, InvocationTargetException, InstanceMethodFromStaticContextException, StaticInitializerException { return invoke(new Object[0]); } /** * Invokes the method. * + * @param args arguments to pass * @return method return value * @throws UnexpectedThrowableException if the {@code modifiers} field could not be found * @throws NoAccessException if access to the method has been denied @@ -374,8 +371,7 @@ public final class ReflectionMethod { * @throws StaticInitializerException when an the static initializer fails * @since v1-alpha2 */ - @Nullable - public Object invoke(Object... args) throws UnexpectedThrowableException, NoAccessException, InvalidMethodSignature, InvocationTargetException, InstanceMethodFromStaticContextException, StaticInitializerException { + public @Nullable Object invoke(Object... args) throws UnexpectedThrowableException, NoAccessException, InvalidMethodSignature, InvocationTargetException, InstanceMethodFromStaticContextException, StaticInitializerException { Object returnValue; // Allow access to method diff --git a/base/src/main/java/de/staropensource/sosengine/base/reflection/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/reflection/package-info.java index ef015d2..c20aaa6 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/reflection/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/reflection/package-info.java @@ -18,8 +18,8 @@ */ /** - * Contains classes which can be used for - * easy reflection on classes, methods and fields. + * Reflection classes, which make reflection + * on classes, methods and fields easy. * * @see de.staropensource.sosengine.base.reflection.Reflect * @since v1-alpha2 diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/DependencyVector.java b/base/src/main/java/de/staropensource/sosengine/base/types/DependencyVector.java index dda385d..c46d6ba 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/DependencyVector.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/DependencyVector.java @@ -20,6 +20,7 @@ package de.staropensource.sosengine.base.types; import de.staropensource.sosengine.base.classes.VersioningSystem; +import de.staropensource.sosengine.base.utility.DependencyResolver; import lombok.Getter; import org.jetbrains.annotations.NotNull; @@ -27,73 +28,65 @@ import java.util.ArrayList; import java.util.List; /** - * Represents a dependency vector, used for dependency management. + * Represents a dependency vector, used by {@link DependencyResolver}. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter public class DependencyVector { /** * Contains the identifier of this vector. * * @since v1-alpha1 - * * -- GETTER -- * Returns the vector identifier. * * @return vector identifier * @since v1-alpha1 */ - @NotNull - protected String identifier; + protected @NotNull String identifier; /** - * Determines which versioning system this vector uses. + * Contains which versioning system this vector uses. * * @since v1-alpha1 - * * -- GETTER -- * Returns the versioning system this vector uses. * * @return versioning system in use * @since v1-alpha1 */ - @NotNull - protected Class versioningSystem; + protected @NotNull Class versioningSystem; /** * Contains the version of this vector. * * @since v1-alpha1 - * * -- GETTER -- * Returns the vector version. * * @return vector version * @since v1-alpha1 */ - @NotNull - protected String version; + protected @NotNull String version; /** * Contains all vectors this vector hard-depends on. * * @since v1-alpha1 - * * -- GETTER -- * Returns all vectors this vector hard-depends on. * * @return hard dependencies * @since v1-alpha1 */ - @NotNull - protected List<@NotNull String> dependencies; + protected @NotNull List<@NotNull String> dependencies; /** * Creates a new dependency vector. * - * @param identifier identifier + * @param identifier identifier (name for example) * @param versioningSystem versioning system to use * @param version version * @param dependencies dependencies in the usual format ({@code dependencyA}, {@code dependencyB=5.1}, {@code dependencyC>3.1}, {@code dependencyD<6.1}) @@ -108,7 +101,7 @@ public class DependencyVector { /** * Creates a new dependency vector. * - * @param identifier identifier + * @param identifier identifier (name for example) * @param versioningSystem versioning system to use * @param version version */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/EventPriority.java b/base/src/main/java/de/staropensource/sosengine/base/types/EventPriority.java index ac11561..2fc5600 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/EventPriority.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/EventPriority.java @@ -22,60 +22,60 @@ package de.staropensource.sosengine.base.types; import de.staropensource.sosengine.base.annotations.EventListener; /** - * Determines in which order events are processed. + * Allows an {@link EventListener} method to specify when it should be invoked. * * @since v1-alpha0 */ @SuppressWarnings("unused") public enum EventPriority { /** - * {@link EventListener}s with this priority are processed first. + * {@link EventListener}s with this priority are processed first, even before {@link #VERY_IMPORTANT}. * This event is exclusive to subsystems and should not be used by applications. * * @since v1-alpha0 */ - EXTREMELY_IMPORTANT, + EXCLUSIVELY_IMPORTANT, /** - * {@link EventListener}s with this priority are executed first. + * {@link EventListener}s with this priority are invoked first. * * @since v1-alpha0 */ VERY_IMPORTANT, /** - * {@link EventListener}s with this priority are executed second. + * {@link EventListener}s with this priority are invoked second. * * @since v1-alpha0 */ IMPORTANT, /** - * The default event priority, {@link EventListener}s with this priority are executed third. + * The default event priority, {@link EventListener}s with this priority are invoked third. * * @since v1-alpha0 */ DEFAULT, /** - * {@link EventListener}s with this priority are executed fourth. + * {@link EventListener}s with this priority are invoked fourth. * * @since v1-alpha0 */ UNIMPORTANT, /** - * {@link EventListener}s with this priority are executed fifth. + * {@link EventListener}s with this priority are invoked last. * * @since v1-alpha0 */ VERY_UNIMPORTANT, /** - * {@link EventListener}s with this priority are processed last. + * {@link EventListener}s with this priority are invoked last, even after {@link #VERY_UNIMPORTANT}. * This event is exclusive to subsystems and should not be used by applications. * * @since v1-alpha0 */ - EXTREMELY_UNIMPORTANT, + EXCLUSIVELY_UNIMPORTANT } diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/Tristate.java b/base/src/main/java/de/staropensource/sosengine/base/types/Tristate.java index 867603c..a8ecde4 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/Tristate.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/Tristate.java @@ -23,38 +23,40 @@ import de.staropensource.sosengine.base.exceptions.TristateConversionException; import org.jetbrains.annotations.NotNull; /** - * tl;dr just a boolean but it can be UNSET too. + * Just a {@link Boolean}, but it can be {@link #UNSET}. * * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) public enum Tristate { /** - * Indicates that something is unset. + * An unset tristate. * * @since v1-alpha1 */ UNSET, /** - * Indicates that something is true. + * A true tristate. * * @since v1-alpha1 */ TRUE, /** - * Indicates that something is false. + * A false tristate. * * @since v1-alpha1 */ FALSE; /** - * Converts a {@link Tristate} into a boolean. + * Converts a {@link Tristate} into a {@link Boolean}. + * Make sure to check for {@link #UNSET} first. * + * @param tristate {@link Tristate} to convert * @return booleanized {@link Tristate} - * @throws TristateConversionException when encountering {@link #UNSET}. + * @throws TristateConversionException when encountering {@link #UNSET} * @since v1-alpha2 */ public static boolean toBoolean(@NotNull Tristate tristate) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/VersionType.java b/base/src/main/java/de/staropensource/sosengine/base/types/VersionType.java index ba22552..c8589ca 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/VersionType.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/VersionType.java @@ -19,14 +19,12 @@ package de.staropensource.sosengine.base.types; -import de.staropensource.sosengine.base.data.info.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; /** * Provides all available version types specified in the StarOpenSource Versioning System v2. * * @see StarOpenSourceVersioningSystem - * @see EngineInformation#versioningType * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) @@ -39,21 +37,21 @@ public enum VersionType { ALPHA, /** - * Indicates that the next version is in development and is experimental. It may contain bugs and issues. + * Indicates that the next version is in development and is experimental. It may contain several bugs and issues. * * @since v1-alpha0 */ BETA, /** - * Indicates that the application is nearing the next release. The application may be stable but needs to be tested before release. + * Indicates that the application is nearing the next release. The application may be stable enough for regular usage but may need some testing to squash all remaining bugs. * * @since v1-alpha0 */ RELEASE_CANDIDATE, /** - * Should be used for tested, stable and working builds. + * Indicates that the application is fully tested, working and stable. * * @since v1-alpha0 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableArrayList.java b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableArrayList.java index 98863cd..8f383a7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableArrayList.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableArrayList.java @@ -49,6 +49,16 @@ public class ImmutableArrayList extends ArrayList { super.addAll(list); } + /** + * Converts the {@link ImmutableArrayList} into a regular {@link ArrayList}. + * + * @return mutable {@link ArrayList} + * @since v1-alpha2 + */ + public @NotNull ArrayList toMutable() { + return new ArrayList<>(this); + } + /** * {@inheritDoc} * diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashMap.java b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashMap.java index e804a09..5e40fe5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashMap.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashMap.java @@ -53,14 +53,23 @@ public class ImmutableHashMap extends HashMap { super.put(key, map.get(key)); } + /** + * Converts the {@link ImmutableHashMap} into a regular {@link HashMap}. + * + * @return mutable {@link HashMap} + * @since v1-alpha2 + */ + public @NotNull HashMap toMutable() { + return new HashMap<>(this); + } + /** * {@inheritDoc} * * @throws UnsupportedOperationException always, hash map is immutable */ - @Nullable @Override - public V put(K key, V value) { + public @Nullable V put(K key, V value) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableHashMap"); } @@ -69,9 +78,8 @@ public class ImmutableHashMap extends HashMap { * * @throws UnsupportedOperationException always, hash map is immutable */ - @Nullable @Override - public V remove(Object key) { + public @Nullable V remove(Object key) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableHashMap"); } @@ -111,9 +119,8 @@ public class ImmutableHashMap extends HashMap { * * @throws UnsupportedOperationException always, hash map is immutable */ - @Nullable @Override - public V putIfAbsent(K key, V value) { + public @Nullable V putIfAbsent(K key, V value) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableHashMap"); } @@ -142,9 +149,8 @@ public class ImmutableHashMap extends HashMap { * * @throws UnsupportedOperationException always, hash map is immutable */ - @Nullable @Override - public V replace(K key, V value) { + public @Nullable V replace(K key, V value) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableHashMap"); } @@ -153,9 +159,8 @@ public class ImmutableHashMap extends HashMap { * * @throws UnsupportedOperationException always, hash map is immutable */ - @Nullable @Override - public V merge(K key, @NotNull V value, @NotNull BiFunction remappingFunction) { + public @Nullable V merge(K key, @NotNull V value, @NotNull BiFunction remappingFunction) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableHashMap"); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashSet.java b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashSet.java index db18eea..68e3fdd 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashSet.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableHashSet.java @@ -51,6 +51,16 @@ public class ImmutableHashSet extends HashSet { super.addAll(set); } + /** + * Converts the {@link ImmutableHashSet} into a regular {@link HashSet}. + * + * @return mutable {@link HashSet} + * @since v1-alpha2 + */ + public @NotNull HashSet toMutable() { + return new HashSet<>(this); + } + /** * {@inheritDoc} * diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedHashMap.java b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedHashMap.java index b6c2cc25..b978178 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedHashMap.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedHashMap.java @@ -53,14 +53,23 @@ public class ImmutableLinkedHashMap extends LinkedHashMap { super.put(key, map.get(key)); } + /** + * Converts the {@link ImmutableLinkedHashMap} into a regular {@link LinkedHashMap}. + * + * @return mutable {@link LinkedHashMap} + * @since v1-alpha2 + */ + public @NotNull LinkedHashMap toMutable() { + return new LinkedHashMap<>(this); + } + /** * {@inheritDoc} * * @throws UnsupportedOperationException always, linked hash map is immutable */ - @Nullable @Override - public V put(K key, V value) { + public @Nullable V put(K key, V value) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableLinkedHashMap"); } @@ -69,9 +78,8 @@ public class ImmutableLinkedHashMap extends LinkedHashMap { * * @throws UnsupportedOperationException always, linked hash map is immutable */ - @Nullable @Override - public V remove(Object key) { + public @Nullable V remove(Object key) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableLinkedHashMap"); } @@ -111,9 +119,8 @@ public class ImmutableLinkedHashMap extends LinkedHashMap { * * @throws UnsupportedOperationException always, linked hash map is immutable */ - @Nullable @Override - public V putIfAbsent(K key, V value) { + public @Nullable V putIfAbsent(K key, V value) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableLinkedHashMap"); } @@ -142,9 +149,8 @@ public class ImmutableLinkedHashMap extends LinkedHashMap { * * @throws UnsupportedOperationException always, linked hash map is immutable */ - @Nullable @Override - public V replace(K key, V value) { + public @Nullable V replace(K key, V value) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableLinkedHashMap"); } @@ -153,9 +159,8 @@ public class ImmutableLinkedHashMap extends LinkedHashMap { * * @throws UnsupportedOperationException always, linked hash map is immutable */ - @Nullable @Override - public V merge(K key, @NotNull V value, @NotNull BiFunction remappingFunction) { + public @Nullable V merge(K key, @NotNull V value, @NotNull BiFunction remappingFunction) { throw new UnsupportedOperationException("This method cannot be executed on an ImmutableLinkedHashMap"); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedList.java b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedList.java index 028bcab..9f3e09d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedList.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/ImmutableLinkedList.java @@ -21,10 +21,7 @@ package de.staropensource.sosengine.base.types.immutable; import org.jetbrains.annotations.NotNull; -import java.util.Collection; -import java.util.Comparator; -import java.util.LinkedList; -import java.util.List; +import java.util.*; import java.util.function.UnaryOperator; /** @@ -52,6 +49,16 @@ public class ImmutableLinkedList extends LinkedList { super.addAll(size(), list); } + /** + * Converts the {@link ImmutableLinkedList} into a regular {@link LinkedList}. + * + * @return mutable {@link LinkedList} + * @since v1-alpha2 + */ + public @NotNull LinkedList toMutable() { + return new LinkedList<>(this); + } + /** * {@inheritDoc} * diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/package-info.java index 0f35a2c..a2aa23f 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/immutable/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/immutable/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains immutable versions of data types. + * Immutable variations of regular Java data types. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogIssuer.java b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogIssuer.java deleted file mode 100644 index 84bca4c..0000000 --- a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogIssuer.java +++ /dev/null @@ -1,128 +0,0 @@ -/* - * 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 . - */ - -package de.staropensource.sosengine.base.types.logging; - -import de.staropensource.sosengine.base.types.CodePart; -import lombok.Getter; -import org.jetbrains.annotations.NotNull; -import org.jetbrains.annotations.Nullable; - -/** - * Used for identifying a log message's origin. - * - * @see de.staropensource.sosengine.base.logging.Logger - * @see de.staropensource.sosengine.base.logging.CrashHandler - * @since v1-alpha0 - */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) -@Getter -public final class LogIssuer { - /** - * Contains the issuing class. - * - * -- GETTER -- - * Returns the issuing class. - * - * @return the issuing class - * @since v1-alpha0 - */ - @NotNull - private final Class clazz; - - /** - * Contains additional information about the issuer. - * - * -- GETTER -- - * Returns additional information about the issuer. - * - * @return additional information about the issuer - * @since v1-alpha0 - */ - @Nullable - private final String additionalInformation; - - /** - * Indicates whether the class belongs to the engine, application or a modification. - * - * @see CodePart - * - * -- GETTER -- - * Returns the {@link CodePart} that indicates whether the class belongs to the engine, application or a modification. - * - * @return the {@link CodePart} - * @since v1-alpha0 - */ - @NotNull - private final CodePart codePart; - - /** - * Creates a new log issuer. - * - * @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 v1-alpha0 - */ - public LogIssuer(@NotNull Class clazz, @NotNull String additionalInformation, @NotNull CodePart codePart) { - this.clazz = clazz; - if (additionalInformation.isEmpty()) this.additionalInformation = null; - else this.additionalInformation = additionalInformation; - this.codePart = codePart; - } - - /** - * Creates a new log issuer. - * - * @param clazz issuing class - * @param additionalInformation additional information about the issuer - * @since v1-alpha0 - */ - public LogIssuer(@NotNull Class clazz, @NotNull String additionalInformation) { - this.clazz = clazz; - if (additionalInformation.isEmpty()) this.additionalInformation = null; - else this.additionalInformation = additionalInformation; - this.codePart = CodePart.APPLICATION; - } - - /** - * Creates a new log issuer. - * - * @param clazz issuing class - * @param codePart identifies to which part of the program the class belongs to - * @since v1-alpha0 - */ - public LogIssuer(@NotNull Class clazz, @NotNull CodePart codePart) { - this.clazz = clazz; - this.additionalInformation = null; - this.codePart = codePart; - } - - /** - * Creates a new log issuer. - * - * @param clazz issuing class - * @since v1-alpha0 - */ - public LogIssuer(@NotNull Class clazz) { - this.clazz = clazz; - this.additionalInformation = null; - this.codePart = CodePart.APPLICATION; - } -} diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogLevel.java b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogLevel.java index 19a55d3..b067bea 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogLevel.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogLevel.java @@ -19,23 +19,25 @@ package de.staropensource.sosengine.base.types.logging; +import de.staropensource.sosengine.base.logging.Logger; + /** - * Used for determining a log message's priority. + * Allows determining a log call priority. * - * @see de.staropensource.sosengine.base.logging.Logger + * @see Logger * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) public enum LogLevel { /** - * Indicates that the log message is diagnostic and solely provides debugging information. It is not important. + * Indicates that the log call is diagnostic and solely provides debugging information. It is not important. * * @since v1-alpha0 */ DIAGNOSTIC, /** - * Indicates that the log message contains more details about some action. It is not important but nice to have. + * Indicates that the log call contains more details about some action. It is not important but nice to have. * * @since v1-alpha0 */ @@ -49,7 +51,7 @@ public enum LogLevel { SILENT_WARNING, /** - * Indicates that the log message provides useful information and is important. + * Indicates that the log call provides useful information and is important. * * @since v1-alpha0 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRule.java b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRule.java index 5d24fdc..52bf48d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRule.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRule.java @@ -21,21 +21,21 @@ package de.staropensource.sosengine.base.types.logging; import lombok.Getter; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** * Defines a rule used during logging to allow or prevent certain log calls. * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter -public final class LogRule { +public abstract class LogRule { /** - * Determines if the log rule should disallow or permit matching log calls. + * Contains if the log rule should disallow or permit matching log calls. * * @see LogRuleType * @since v1-alpha1 - * * -- GETTER -- * Returns if the log rule should disallow or permit matching log calls. * @@ -43,8 +43,7 @@ public final class LogRule { * @see LogRuleType * @since v1-alpha1 */ - @NotNull - private final LogRuleType type; + private final @NotNull LogRuleType type; /** * Creates a new log rule. @@ -58,12 +57,12 @@ public final class LogRule { /** * Evaluates the rule and returns if the rule matches. * - * @param issuer issuer - * @param level log level - * @param message raw message + * @param level level + * @param issuerClass class of the issuer + * @param issuerOrigin origin of the issuer + * @param issuerMetadata metadata about the issuer + * @param message raw message * @return if the rule matches */ - public boolean evaluate(@NotNull LogIssuer issuer, @NotNull LogLevel level, @NotNull String message) { - return false; - } + public abstract boolean evaluate(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRuleType.java b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRuleType.java index d3159ca..06c0e17 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRuleType.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/logging/LogRuleType.java @@ -29,6 +29,7 @@ public enum LogRuleType { /** * Indicates that log calls matching this rule will always be allowed, even if blacklisted. * + * @see #BLACKLIST * @since v1-alpha1 */ WHITELIST, @@ -36,7 +37,7 @@ public enum LogRuleType { /** * Indicates that log calls matching this will always be disallowed except when whitelisted. * - * @see LogRuleType#WHITELIST + * @see #WHITELIST * @since v1-alpha1 */ BLACKLIST diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/logging/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/types/logging/package-info.java index 950bdf9..41e6cca 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/logging/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/logging/package-info.java @@ -18,8 +18,9 @@ */ /** - * Contains logging-related data types. + * Data types related to logging. * + * @see de.staropensource.sosengine.base.logging * @since v1-alpha1 */ package de.staropensource.sosengine.base.types.logging; diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/types/package-info.java index 67cb42e..17cbd89 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains data types in form of enums and classes. + * Data types in form of enums and classes. * * @since v1-alpha0 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/reflection/ClassType.java b/base/src/main/java/de/staropensource/sosengine/base/types/reflection/ClassType.java index 264cdc8..f29879c 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/reflection/ClassType.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/reflection/ClassType.java @@ -55,7 +55,7 @@ public enum ClassType { RECORD, /** - * Identifies the class as some unknown class the engine does not yet know of. + * Identifies the class as an unknown type the engine does not yet know of. * * @since v1-alpha2 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/reflection/VisibilityModifier.java b/base/src/main/java/de/staropensource/sosengine/base/types/reflection/VisibilityModifier.java index 603d853..411346b 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/reflection/VisibilityModifier.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/reflection/VisibilityModifier.java @@ -24,7 +24,7 @@ import de.staropensource.sosengine.base.exceptions.UnexpectedCheckEndException; import java.lang.reflect.Modifier; /** - * Determines which visibility a class, method or field has. + * Contains which visibility a class, method or field has. * * @since v1-alpha2 */ @@ -68,9 +68,7 @@ public enum VisibilityModifier { case PRIVATE -> { return Modifier.PRIVATE; } - case null, default -> { - throw new UnexpectedCheckEndException("converting the visibility into a modifier"); - } + case null, default -> throw new UnexpectedCheckEndException("converting the visibility into a modifier"); } } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/reflection/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/types/reflection/package-info.java index 453cfa3..fd06d55 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/reflection/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/reflection/package-info.java @@ -18,9 +18,9 @@ */ /** - * Contains types used during reflection. + * Data types related to reflection. * - * @see de.staropensource.sosengine.base.reflection.Reflect + * @see de.staropensource.sosengine.base.reflection * @since v1-alpha2 */ package de.staropensource.sosengine.base.types.reflection; diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2d.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2d.java new file mode 100644 index 0000000..a164701 --- /dev/null +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2d.java @@ -0,0 +1,107 @@ +/* + * 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 . + */ + +package de.staropensource.sosengine.base.types.vectors; + +import de.staropensource.sosengine.base.EngineConfiguration; +import lombok.Getter; +import lombok.Setter; +import lombok.SneakyThrows; +import org.jetbrains.annotations.NotNull; + +/** + * Represents a 2D double Vector. + * + * @since v1-alpha0 + */ +@SuppressWarnings({ "unused", "JavadocDeclaration" }) +@Getter +@Setter +public class Vec2d { + /** + * The X axis value. + * + * @since v1-alpha0 + * -- GETTER -- + * Returns the X axis value. + * + * @return X axis value + * @since v1-alpha0 + * -- SETTER -- + * Sets the X axis value. + * + * @param x X axis value + * @since v1-alpha0 + */ + private double x; + + /** + * The Y axis value. + * + * @since v1-alpha0 + * -- GETTER -- + * Returns the Y axis value. + * + * @return Y axis value + * @since v1-alpha0 + * -- SETTER -- + * Sets the Y axis value. + * + * @param y Y axis value + * @since v1-alpha0 + */ + private double y; + + /** + * Creates a new 2D vector. + * + * @param x X axis value + * @param y Y axis value + * @since v1-alpha0 + */ + public Vec2d(double x, double y) { + this.x = x; + this.y = y; + } + + /** + * Creates an identical copy of this vector. + * + * @return identical copy + * @since v1-alpha2 + */ + @SneakyThrows + public @NotNull Vec2d clone() { + return (Vec2d) super.clone(); + } + + /** + * Returns a string representation of this vector. + * + * @return string representation + * @since v1-alpha2 + */ + @Override + public @NotNull String toString() { + return (EngineConfiguration.getInstance().isHideFullTypePath() + ? getClass().getName().replace(getClass().getPackage() + ".", "") + : getClass().getName()) + + "(x=" + x + " y=" + y + ")"; + } +} diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2f.java similarity index 90% rename from base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2.java rename to base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2f.java index 63d4285..5c14b00 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2f.java @@ -30,21 +30,19 @@ import org.jetbrains.annotations.NotNull; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter @Setter -public class Vec2 { +public class Vec2f { /** * The X axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the X axis value. * * @return X axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the X axis value. * @@ -57,13 +55,11 @@ public class Vec2 { * The Y axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the Y axis value. * * @return Y axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the Y axis value. * @@ -79,7 +75,7 @@ public class Vec2 { * @param y Y axis value * @since v1-alpha0 */ - public Vec2(float x, float y) { + public Vec2f(float x, float y) { this.x = x; this.y = y; } @@ -91,9 +87,8 @@ public class Vec2 { * @since v1-alpha2 */ @SneakyThrows - @NotNull - public Vec2 clone() { - return (Vec2) super.clone(); + public @NotNull Vec2f clone() { + return (Vec2f) super.clone(); } /** @@ -102,9 +97,8 @@ public class Vec2 { * @return string representation * @since v1-alpha2 */ - @NotNull @Override - public String toString() { + public @NotNull String toString() { return (EngineConfiguration.getInstance().isHideFullTypePath() ? getClass().getName().replace(getClass().getPackage() + ".", "") : getClass().getName()) diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2i.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2i.java index 700ab41..5ba66c9 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2i.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec2i.java @@ -30,7 +30,7 @@ import org.jetbrains.annotations.NotNull; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter @Setter public class Vec2i implements Cloneable { @@ -38,13 +38,11 @@ public class Vec2i implements Cloneable { * The X axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the X axis value. * * @return the X axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the X axis value. * @@ -57,13 +55,11 @@ public class Vec2i implements Cloneable { * The Y axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the Y axis value. * * @return Y axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the Y axis value. * @@ -91,8 +87,7 @@ public class Vec2i implements Cloneable { * @since v1-alpha2 */ @SneakyThrows - @NotNull - public Vec2i clone() { + public @NotNull Vec2i clone() { return (Vec2i) super.clone(); } @@ -102,9 +97,8 @@ public class Vec2i implements Cloneable { * @return string representation * @since v1-alpha2 */ - @NotNull @Override - public String toString() { + public @NotNull String toString() { return (EngineConfiguration.getInstance().isHideFullTypePath() ? getClass().getName().replace(getClass().getPackage() + ".", "") : getClass().getName()) diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3d.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3d.java new file mode 100644 index 0000000..7b6cd9b --- /dev/null +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3d.java @@ -0,0 +1,126 @@ +/* + * 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 . + */ + +package de.staropensource.sosengine.base.types.vectors; + +import de.staropensource.sosengine.base.EngineConfiguration; +import lombok.Getter; +import lombok.Setter; +import lombok.SneakyThrows; +import org.jetbrains.annotations.NotNull; + +/** + * Represents a 3D double Vector. + * + * @since v1-alpha0 + */ +@SuppressWarnings({ "unused", "JavadocDeclaration" }) +@Getter +@Setter +public class Vec3d { + /** + * The X axis value. + * + * @since v1-alpha0 + * -- GETTER -- + * Returns the X axis value. + * + * @return X axis value + * @since v1-alpha0 + * -- SETTER -- + * Sets the X axis value. + * + * @param x X axis value + * @since v1-alpha0 + */ + private double x; + + /** + * The Y axis value. + * + * @since v1-alpha0 + * -- GETTER -- + * Returns the Y axis value. + * + * @return Y axis value + * @since v1-alpha0 + * -- SETTER -- + * Sets the Y axis value. + * + * @param y Y axis value + * @since v1-alpha0 + */ + private double y; + + /** + * The Z axis value. + * + * @since v1-alpha0 + * -- GETTER -- + * Returns the Z axis value. + * + * @return Z axis value + * @since v1-alpha0 + * -- SETTER -- + * Sets the Z axis value. + * + * @param z Z axis value + * @since v1-alpha0 + */ + private double z; + + /** + * Constructs this 3D vector. + * + * @param x X axis value + * @param y Y axis value + * @param z Z axis value + * @since v1-alpha0 + */ + public Vec3d(double x, double y, double z) { + this.x = x; + this.y = y; + this.z = z; + } + + /** + * Creates an identical copy of this vector. + * + * @return identical copy + * @since v1-alpha2 + */ + @SneakyThrows + public @NotNull Vec3d clone() { + return (Vec3d) super.clone(); + } + + /** + * Returns a string representation of this vector. + * + * @return string representation + * @since v1-alpha2 + */ + @Override + public @NotNull String toString() { + return (EngineConfiguration.getInstance().isHideFullTypePath() + ? getClass().getName().replace(getClass().getPackage() + ".", "") + : getClass().getName()) + + "(x=" + x + " y=" + y + ")"; + } +} diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3f.java similarity index 90% rename from base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3.java rename to base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3f.java index e4dcf19..0209c59 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3f.java @@ -30,21 +30,19 @@ import org.jetbrains.annotations.NotNull; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter @Setter -public class Vec3 { +public class Vec3f { /** * The X axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the X axis value. * * @return X axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the X axis value. * @@ -57,13 +55,11 @@ public class Vec3 { * The Y axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the Y axis value. * * @return Y axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the Y axis value. * @@ -76,13 +72,11 @@ public class Vec3 { * The Z axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the Z axis value. * * @return Z axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the Z axis value. * @@ -99,7 +93,7 @@ public class Vec3 { * @param z Z axis value * @since v1-alpha0 */ - public Vec3(float x, float y, float z) { + public Vec3f(float x, float y, float z) { this.x = x; this.y = y; this.z = z; @@ -112,9 +106,8 @@ public class Vec3 { * @since v1-alpha2 */ @SneakyThrows - @NotNull - public Vec3 clone() { - return (Vec3) super.clone(); + public @NotNull Vec3f clone() { + return (Vec3f) super.clone(); } /** @@ -123,9 +116,8 @@ public class Vec3 { * @return string representation * @since v1-alpha2 */ - @NotNull @Override - public String toString() { + public @NotNull String toString() { return (EngineConfiguration.getInstance().isHideFullTypePath() ? getClass().getName().replace(getClass().getPackage() + ".", "") : getClass().getName()) diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3i.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3i.java index fb5dd8c..c5475c1 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3i.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/Vec3i.java @@ -30,7 +30,7 @@ import org.jetbrains.annotations.NotNull; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter @Setter public class Vec3i { @@ -38,13 +38,11 @@ public class Vec3i { * The X axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the X axis value. * * @return X axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the X axis value. * @@ -57,13 +55,11 @@ public class Vec3i { * The Y axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the Y axis value. * * @return Y axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the Y axis value. * @@ -76,13 +72,11 @@ public class Vec3i { * The Z axis value. * * @since v1-alpha0 - * * -- GETTER -- * Returns the Z axis value. * * @return Z axis value * @since v1-alpha0 - * * -- SETTER -- * Sets the Z axis value. * @@ -112,8 +106,7 @@ public class Vec3i { * @since v1-alpha2 */ @SneakyThrows - @NotNull - public Vec3i clone() { + public @NotNull Vec3i clone() { return (Vec3i) super.clone(); } @@ -123,9 +116,8 @@ public class Vec3i { * @return string representation * @since v1-alpha2 */ - @NotNull @Override - public String toString() { + public @NotNull String toString() { return (EngineConfiguration.getInstance().isHideFullTypePath() ? getClass().getName().replace(getClass().getPackage() + ".", "") : getClass().getName()) diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/package-info.java index 522a406..93c3118 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/vectors/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/vectors/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains data types operating with numbers. + * Data types operating with sets of numbers. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/DependencyResolver.java b/base/src/main/java/de/staropensource/sosengine/base/utility/DependencyResolver.java index 7a346d7..df3c173 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/DependencyResolver.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/DependencyResolver.java @@ -35,7 +35,7 @@ import java.util.*; * * @since v1-alpha1 */ -@SuppressWarnings({ "unused", "UnusedReturnValue" }) +@SuppressWarnings({ "unused", "UnusedReturnValue", "JavadocDeclaration" }) public final class DependencyResolver { /** * A list of {@link DependencyVector}s. @@ -45,14 +45,13 @@ public final class DependencyResolver { List vectors = new ArrayList<>(); /** - * {@code true} if the current dependency vector list has been resolved successfully. + * {@code true} if the current {@link DependencyVector} list has been resolved successfully. * * @since v1-alpha1 - * * -- GETTER -- - * Returns {@code true} if the current dependency vector list has been resolved successfully. + * Returns {@code true} if the current {@link DependencyVector} list has been resolved successfully. * - * @return if the current dependency vector list has been resolved + * @return resolved status * @since v1-alpha1 */ @Getter @@ -60,13 +59,15 @@ public final class DependencyResolver { /** * Constructs this class. + * + * @since v1-alpha1 */ public DependencyResolver() {} /** - * Adds a dependency vector. + * Adds a {@link DependencyVector}. * - * @param vector dependency vector to add + * @param vector {@link DependencyVector} to add * @return itself * @since v1-alpha1 */ @@ -79,7 +80,7 @@ public final class DependencyResolver { /** * Adds multiple dependency vectors. * - * @param vectors dependency vectors to add + * @param vectors {@link DependencyVector}s to add * @return itself * @since v1-alpha1 */ @@ -92,7 +93,7 @@ public final class DependencyResolver { /** * Adds multiple dependency vectors. * - * @param vectors dependency vectors to add + * @param vectors {@link DependencyVector}s to add * @return itself * @since v1-alpha1 */ @@ -266,8 +267,6 @@ public final class DependencyResolver { if (!resolved) throw new IllegalStateException("The current dependency vector list has not been resolved yet"); - LinkedList list = new LinkedList<>(); - - return list; + return new LinkedList<>(); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/ListFormatter.java b/base/src/main/java/de/staropensource/sosengine/base/utility/ListFormatter.java index 22ab54d..d212683 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/ListFormatter.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/ListFormatter.java @@ -47,8 +47,7 @@ public final class ListFormatter { * @return formatted string */ @ApiStatus.Experimental() // TODO - @NotNull - public static String formatArray(@NotNull Object[] array) { + public static @NotNull String formatArray(@NotNull Object[] array) { return Arrays.toString(array); } @@ -59,8 +58,7 @@ public final class ListFormatter { * @return formatted string */ @ApiStatus.Experimental() // TODO - @NotNull - public static String formatSet(@NotNull Set set) { + public static @NotNull String formatSet(@NotNull Set set) { return set.toString(); } @@ -71,8 +69,7 @@ public final class ListFormatter { * @return formatted string */ @ApiStatus.Experimental() // TODO - @NotNull - public static String formatList(@NotNull List list) { + public static @NotNull String formatList(@NotNull List list) { return list.toString(); } @@ -83,8 +80,7 @@ public final class ListFormatter { * @return formatted string */ @ApiStatus.Experimental() // TODO - @NotNull - public static String formatMap(@NotNull Map map) { + public static @NotNull String formatMap(@NotNull Map map) { return map.toString(); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/Math.java b/base/src/main/java/de/staropensource/sosengine/base/utility/Math.java index 6bba65a..d27d636 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/Math.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/Math.java @@ -24,20 +24,31 @@ import org.jetbrains.annotations.NotNull; import java.util.Collection; import java.util.LinkedList; +/** + * Utility class for math operations. + * + * @since v1-alpha2 + */ // All mean and double methods have been sourced // from https://stackoverflow.com/a/4191729, tysm @SuppressWarnings({ "unused" }) public final class Math { + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public Math() {} + /** * Adds padding zeros to a number. * * @param number number * @param length length * @return the padded number - * @since v1-alpha0 + * @since v1-alpha2 */ - @NotNull - public static String padNumbers(long number, int length) { + public static @NotNull String padNumbers(long number, int length) { return String.format("%0" + length + "d", number); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/Miscellaneous.java b/base/src/main/java/de/staropensource/sosengine/base/utility/Miscellaneous.java index cb3bdd6..569dc90 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/Miscellaneous.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/Miscellaneous.java @@ -47,6 +47,8 @@ public final class Miscellaneous { /** * Converts a boolean into an integer. * + * @param bool boolean to convert + * @return converted integer * @since v1-alpha2 */ @Range(from = 0, to = 1) @@ -57,7 +59,8 @@ public final class Miscellaneous { /** * Converts an integer into a {@link Tristate}. * - * @return the expected boolean result, except if neither {@code 0} or {@code 1}, in which case {@link Tristate#UNSET} is returned + * @param integer integer to convert + * @return expected boolean result, except if neither {@code 0} or {@code 1}, in which case {@link Tristate#UNSET} is returned * @since v1-alpha2 */ public static Tristate getTristatedInteger(@Range(from = 0, to = 1) int integer) { @@ -71,6 +74,7 @@ public final class Miscellaneous { /** * Converts an integer into a {@link Tristate} and then into a boolean. * + * @param integer integer to convert * @return booleanized integer * @throws TristateConversionException when encountering {@link Tristate#UNSET}. * @since v1-alpha2 @@ -115,8 +119,7 @@ public final class Miscellaneous { * @return separator to use or {@code null} * @since v1-alpha1 */ - @Nullable - public static String getSeparator(@NotNull String string, String[] separators, int requiredOccurrences) { + public static @Nullable String getSeparator(@NotNull String string, String[] separators, int requiredOccurrences) { if (string.isBlank() || separators.length == 0 || requiredOccurrences == 0) return null; @@ -135,8 +138,7 @@ public final class Miscellaneous { * @return separator to use or {@code null} * @since v1-alpha1 */ - @Nullable - public static String getSeparator(@NotNull String string, List separators, Integer minimumOccurrences) { + public static @Nullable String getSeparator(@NotNull String string, List separators, Integer minimumOccurrences) { for (String separator : separators) if (countOccurrences(string, separator) >= minimumOccurrences) return separator; @@ -176,7 +178,7 @@ public final class Miscellaneous { * Forcefully invokes the garbage collector * and blocks execution until finished. * If you want to run it in parallel to your - * program, consider running it in a {@link VirtualThread}. + * program, consider running it in a {@code VirtualThread}. *

* This method does not guarantee full garbage collection, * as the JVM only hints the garbage collector to do it's job. @@ -210,8 +212,7 @@ public final class Miscellaneous { * @return converted stacktrace string * @since v1-alpha2 */ - @NotNull - public static String stringifyStackTrace(@NotNull StackTraceElement[] stacktrace, boolean indent) { + public static @NotNull String stringifyStackTrace(@NotNull StackTraceElement[] stacktrace, boolean indent) { StringBuilder output = new StringBuilder(); for (StackTraceElement element : stacktrace) { diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/PlaceholderEngine.java b/base/src/main/java/de/staropensource/sosengine/base/utility/PlaceholderEngine.java index 9c1790d..aece2f7 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/PlaceholderEngine.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/PlaceholderEngine.java @@ -22,9 +22,7 @@ package de.staropensource.sosengine.base.utility; import de.staropensource.sosengine.base.Engine; import de.staropensource.sosengine.base.classes.Placeholder; import de.staropensource.sosengine.base.internal.placeholders.*; -import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.logging.LoggerInstance; import lombok.Getter; import org.jetbrains.annotations.NotNull; @@ -37,13 +35,12 @@ import java.util.List; * @see Placeholder * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public final class PlaceholderEngine { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -53,6 +50,14 @@ public final class PlaceholderEngine { @Getter private static PlaceholderEngine instance; + /** + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha1 + */ + private final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); + /** * Contains all global placeholders. * @@ -66,8 +71,7 @@ public final class PlaceholderEngine { */ @SuppressWarnings("FieldMayBeFinal") @Getter - @NotNull - private List<@NotNull Placeholder> placeholders = new ArrayList<>(); + private @NotNull List<@NotNull Placeholder> placeholders = new ArrayList<>(); /** * Constructs this class. @@ -79,7 +83,7 @@ public final class PlaceholderEngine { if (instance == null) instance = this; else { - Logger.crash(new LogIssuer(getClass(), CodePart.ENGINE), "Tried reinitializing " + getClass().getName() + " twice"); + logger.crash("Tried reinitializing " + getClass().getName() + " twice"); return; } @@ -138,8 +142,7 @@ public final class PlaceholderEngine { * @return the processed text * @since v1-alpha0 */ - @NotNull - public String process(@NotNull String text, List<@NotNull Placeholder> temporaryPlaceholders) { + public @NotNull String process(@NotNull String text, List<@NotNull Placeholder> temporaryPlaceholders) { // Process temporary placeholders for (Placeholder temporaryPlaceholder : temporaryPlaceholders) text = temporaryPlaceholder.replace(text); @@ -158,8 +161,7 @@ public final class PlaceholderEngine { * @return the processed text * @since v1-alpha0 */ - @NotNull - public String process(@NotNull String text) { + public @NotNull String process(@NotNull String text) { return process(text, new ArrayList<>()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/converter/EmptyShortcodeConverter.java b/base/src/main/java/de/staropensource/sosengine/base/utility/converter/EmptyShortcodeConverter.java index dd94e3e..9f713e5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/converter/EmptyShortcodeConverter.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/converter/EmptyShortcodeConverter.java @@ -34,9 +34,9 @@ public final class EmptyShortcodeConverter extends ShortcodeParserSkeleton { /** * Constructs this class. * - * @param string string to convert - * @param ignoreInvalidEscapes will ignore invalid escapes and print treat them like regular text - * @throws ParserException when parsing failed + * @param string string to parse + * @param ignoreInvalidEscapes if {@code true}, will ignore and treat invalid escapes as text + * @throws ParserException on error * @since v1-alpha1 */ public EmptyShortcodeConverter(@NotNull String string, boolean ignoreInvalidEscapes) throws ParserException { @@ -49,8 +49,7 @@ public final class EmptyShortcodeConverter extends ShortcodeParserSkeleton { * @return cleaned input string * @since v1-alpha1 */ - @NotNull - public String getClean() { + public @NotNull String getClean() { StringBuilder output = new StringBuilder(); for (String component : components) diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/converter/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/utility/converter/package-info.java index f60ccab..fb2c8de 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/converter/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/converter/package-info.java @@ -18,7 +18,7 @@ */ /** - * Classes in the package convert data to some other data. + * Classes which convert data. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/parser/PropertyParser.java b/base/src/main/java/de/staropensource/sosengine/base/utility/parser/PropertyParser.java index 77f6517..fa15585 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/parser/PropertyParser.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/parser/PropertyParser.java @@ -20,74 +20,68 @@ package de.staropensource.sosengine.base.utility.parser; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.Tristate; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import lombok.Getter; import org.jetbrains.annotations.NotNull; import java.util.Properties; /** - * Allows parsing various data types against a set of {@link Properties}. + * Allows parsing and converting properties into various other data types. * * @see Properties * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @NotNull public final class PropertyParser { /** - * Contains an instance providing access to the JVM-wide properties. + * Contains an instance providing access to the system properties. * * @see System#getProperties() * @since v1-alpha0 - * * -- GETTER -- - * Returns an instance providing access to the JVM-wide properties. + * Returns an instance providing access to the system properties. * * @return instance using the JVM-wide properties * @see System#getProperties() * @since v1-alpha0 */ - @NotNull @Getter - private static final PropertyParser instance = new PropertyParser(System.getProperties()); + private static final @NotNull PropertyParser instance = new PropertyParser(System.getProperties()); + /** - * The {@link Properties} in use by this instance. + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha0 + */ + private final @NotNull LoggerInstance logger; + + /** + * Contains the {@link Properties} used by this parser instance to read properties. * * @see Properties * @since v1-alpha0 - * * -- GETTER -- - * Returns the {@link Properties} in use by this instance. + * Returns the {@link Properties} used by this parser instance to read properties. * - * @return the {@link Properties} in use by this instance + * @return {@link Properties} associated with this parser instance * @see Properties * @since v1-alpha0 */ @Getter private final @NotNull Properties properties; - /** - * Logger instance, - * - * @see LoggerInstance - * @since v1-alpha0 - */ - @NotNull - private final LoggerInstance logger; - - /** - * Creates a new {@link Properties} parser. + * Creates a new {@link PropertyParser} instance. * * @param properties {@link Properties} to use * @since v1-alpha0 */ public PropertyParser(@NotNull Properties properties) { this.properties = properties; - this.logger = new LoggerInstance(new LogIssuer(getClass(), String.valueOf(properties.hashCode()), CodePart.ENGINE)); + this.logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").setMetadata(String.valueOf(properties.hashCode())).build(); } /** @@ -99,8 +93,7 @@ public final class PropertyParser { * @see String * @since v1-alpha0 */ - @NotNull - public String getString(@NotNull String name) throws NullPointerException { + public @NotNull String getString(@NotNull String name) throws NullPointerException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get String from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get String from property '" + name + "': Property does not exist"); @@ -117,8 +110,7 @@ public final class PropertyParser { * @see Boolean * @since v1-alpha0 */ - @NotNull - public Boolean getBoolean(@NotNull String name) { + public boolean getBoolean(@NotNull String name) { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Boolean from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Boolean from property '" + name + "': Property does not exist"); @@ -143,8 +135,7 @@ public final class PropertyParser { * @see Tristate * @since v1-alpha1 */ - @NotNull - public Tristate getTristate(@NotNull String name) { + public @NotNull Tristate getTristate(@NotNull String name) { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Tristate from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Tristate from property '" + name + "': Property does not exist"); @@ -173,8 +164,7 @@ public final class PropertyParser { * @see Byte * @since v1-alpha0 */ - @NotNull - public Byte getByte(@NotNull String name) throws NullPointerException, NumberFormatException { + public byte getByte(@NotNull String name) throws NullPointerException, NumberFormatException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Byte from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Byte from property '" + name + "': Property does not exist"); @@ -198,8 +188,7 @@ public final class PropertyParser { * @see Short * @since v1-alpha0 */ - @NotNull - public Short getShort(@NotNull String name) throws NumberFormatException { + public short getShort(@NotNull String name) throws NumberFormatException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Short from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Short from property '" + name + "': Property does not exist"); @@ -224,8 +213,7 @@ public final class PropertyParser { * @see Integer * @since v1-alpha0 */ - @NotNull - public Integer getInteger(@NotNull String name, boolean unsigned) throws NumberFormatException { + public int getInteger(@NotNull String name, boolean unsigned) throws NumberFormatException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Integer from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Integer from property '" + name + "': Property does not exist"); @@ -253,8 +241,7 @@ public final class PropertyParser { * @see Long * @since v1-alpha0 */ - @NotNull - public Long getLong(@NotNull String name, boolean unsigned) throws NumberFormatException { + public long getLong(@NotNull String name, boolean unsigned) throws NumberFormatException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Long from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Long from property '" + name + "': Property does not exist"); @@ -281,8 +268,7 @@ public final class PropertyParser { * @see Float * @since v1-alpha0 */ - @NotNull - public Float getFloat(@NotNull String name) throws NullPointerException, NumberFormatException { + public float getFloat(@NotNull String name) throws NullPointerException, NumberFormatException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Float from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Float from property '" + name + "': Property does not exist"); @@ -306,8 +292,7 @@ public final class PropertyParser { * @see Double * @since v1-alpha0 */ - @NotNull - public Double getDouble(@NotNull String name) throws NullPointerException, NumberFormatException { + public double getDouble(@NotNull String name) throws NullPointerException, NumberFormatException { if (properties.getProperty(name) == null) { logger.sarn("Unable to get Double from property '" + name + "': Property does not exist"); throw new NullPointerException("Unable to get Double from property '" + name + "': Property does not exist"); diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/parser/StackTraceParser.java b/base/src/main/java/de/staropensource/sosengine/base/utility/parser/StackTraceParser.java index 4822edb..345b6b6 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/parser/StackTraceParser.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/parser/StackTraceParser.java @@ -25,21 +25,21 @@ import lombok.Getter; import org.jetbrains.annotations.NotNull; /** - * Parses the {@link StackTraceElement}s of an {@link Throwable} for use in {@link String}. + * Parses the stacktrace of a {@link Throwable} for use in {@link String}s. * * @see Throwable * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocBlankLines" }) +@SuppressWarnings({ "unused" }) +// TODO deprecate """parser""" and move getHeader() to Miscellaneous class public final class StackTraceParser { /** - * The throwable to use. + * Contains the {@link Throwable} to parse. * * @see Throwable * @since v1-alpha0 - * * -- GETTER -- - * Returns the throwable to use. + * Returns the {@link Throwable} to parse. * * @see Throwable * @since v1-alpha0 @@ -50,7 +50,7 @@ public final class StackTraceParser { /** * Constructs this class. * - * @param throwable throwable to use + * @param throwable throwable to parse * @since v1-alpha0 */ public StackTraceParser(@NotNull Throwable throwable) { @@ -58,28 +58,23 @@ public final class StackTraceParser { } /** - * Returns the stack trace header.
+ * Returns the stack trace header. * It looks like this: {@code Caused by java.lang.NullPointerThrowable: This application can crash!} * - * @return the stack trace header + * @return stack trace header * @since v1-alpha0 */ - @NotNull - public String getHeader() { - if (throwable.getMessage() == null) - return "Caused by: " + throwable.getClass().getName(); - else - return "Caused by: " + throwable.getClass().getName() + ": " + throwable.getMessage(); + public @NotNull String getHeader() { + return "Caused by: " + throwable.getClass().getName() + (throwable.getMessage() == null ? "" : ": " + throwable.getMessage()); } /** * Returns the stack trace. * - * @return the stack trace + * @return stack trace * @since v1-alpha0 */ - @NotNull - public String getStackTrace() { + public @NotNull String getStackTrace() { return Miscellaneous.stringifyStackTrace(throwable.getStackTrace(), true); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/utility/parser/package-info.java b/base/src/main/java/de/staropensource/sosengine/base/utility/parser/package-info.java index b3f8cc9..3ec15cb 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/utility/parser/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/base/utility/parser/package-info.java @@ -18,8 +18,7 @@ */ /** - * Classes in this package handle parsing data - * and providing that parsed data in simple ways. + * Classes which parse data and providing that data in simple ways. * * @since v1-alpha1 */ diff --git a/base/src/main/java/de/staropensource/sosengine/unittests/UnitConfig.java b/base/src/main/java/de/staropensource/sosengine/unittests/UnitConfig.java index 28099ae..be8f811 100644 --- a/base/src/main/java/de/staropensource/sosengine/unittests/UnitConfig.java +++ b/base/src/main/java/de/staropensource/sosengine/unittests/UnitConfig.java @@ -22,7 +22,7 @@ package de.staropensource.sosengine.unittests; import de.staropensource.sosengine.base.types.logging.LogLevel; /** - * Static configuration for the sos!engine unit testing helpers. + * Static configuration for unit test classes. * * @since v1-alpha0 */ @@ -35,7 +35,8 @@ public class UnitConfig { public UnitConfig() {} /** - * Configures the {@link LogLevel} for the {@link UnitLogger}.
+ * Configures the {@link LogLevel} for the {@link UnitLogger}. + *

* Note: The log level {@code SILENT_WARNING} has been repurposed for printing test calls. * * @see UnitLogger diff --git a/base/src/main/java/de/staropensource/sosengine/unittests/UnitLogger.java b/base/src/main/java/de/staropensource/sosengine/unittests/UnitLogger.java index 991d71f..a555c42 100644 --- a/base/src/main/java/de/staropensource/sosengine/unittests/UnitLogger.java +++ b/base/src/main/java/de/staropensource/sosengine/unittests/UnitLogger.java @@ -19,21 +19,20 @@ package de.staropensource.sosengine.unittests; +import de.staropensource.sosengine.base.logging.LoggerInstance; import de.staropensource.sosengine.base.types.logging.LogLevel; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; -import java.util.List; - /** - * Provides a extremely dead simple logging system for unit tests. + * Provides an extremely dead simple logging system for unit tests. * * @since v1-alpha0 */ @SuppressWarnings("unused") public class UnitLogger { /** - * The parent class. + * The parent class, similar to {@link LoggerInstance}. * * @since v1-alpha0 */ @@ -42,7 +41,7 @@ public class UnitLogger { /** * Creates a new unit logger. * - * @param clazz parent class + * @param clazz parent class, similar to {@link LoggerInstance} * @since v1-alpha0 */ public UnitLogger(Class clazz) { @@ -52,12 +51,12 @@ public class UnitLogger { /** * Prints a log message. * - * @param level log level - * @param message log message + * @param level level + * @param message message * @param additionalStuff additional arguments * @since v1-alpha0 */ - private void log(@NotNull LogLevel level, @NotNull String message, List<@Nullable Object> additionalStuff) { + private void log(@NotNull LogLevel level, @NotNull String message, @Nullable Object... additionalStuff) { String messageSingle = message; String levelName; @@ -99,61 +98,61 @@ public class UnitLogger { /** * Prints a diagnostic message. * - * @param message diagnostic log message + * @param message message * @since v1-alpha0 */ public void diag(@NotNull String message) { - log(LogLevel.DIAGNOSTIC, message, null); + log(LogLevel.DIAGNOSTIC, message); } /** * Prints a verbose message. * - * @param message verbose log message + * @param message message * @since v1-alpha0 */ public void verb(@NotNull String message) { - log(LogLevel.VERBOSE, message, null); + log(LogLevel.VERBOSE, message); } /** * Prints a test call message. * - * @param methodName name of the test method called - * @param methodArgs arguments of the test method called + * @param methodName name of the test method + * @param methodArgs arguments of the test method * @since v1-alpha0 */ - public void testCall(@NotNull String methodName, @Nullable Object ... methodArgs) { - log(LogLevel.SILENT_WARNING, methodName, List.of(methodArgs)); + public void testCall(@NotNull String methodName, @Nullable Object... methodArgs) { + log(LogLevel.SILENT_WARNING, methodName, methodArgs); } /** * Prints a informational message. * - * @param message informational log message + * @param message message * @since v1-alpha0 */ public void info(@NotNull String message) { - log(LogLevel.INFORMATIONAL, message, null); + log(LogLevel.INFORMATIONAL, message); } /** * Prints a warning message. * - * @param message warning log message + * @param message message * @since v1-alpha0 */ public void warn(@NotNull String message) { - log(LogLevel.WARNING, message, null); + log(LogLevel.WARNING, message); } /** * Prints a error message. * - * @param message error log message + * @param message message * @since v1-alpha0 */ public void error(@NotNull String message) { - log(LogLevel.ERROR, message, null); + log(LogLevel.ERROR, message); } } diff --git a/base/src/main/java/de/staropensource/sosengine/unittests/package-info.java b/base/src/main/java/de/staropensource/sosengine/unittests/package-info.java index ec7ccd8..1c2b5f0 100644 --- a/base/src/main/java/de/staropensource/sosengine/unittests/package-info.java +++ b/base/src/main/java/de/staropensource/sosengine/unittests/package-info.java @@ -18,7 +18,9 @@ */ /** - * Classes in this package are designed to be used within unit tests. + * Classes targeted at unit tests. * They aim at simplifying certain aspects of unit testing. + * + * @since v1-alpha0 */ package de.staropensource.sosengine.unittests; diff --git a/base/src/main/java/module-info.java b/base/src/main/java/module-info.java index f884ca1..bba09b1 100644 --- a/base/src/main/java/module-info.java +++ b/base/src/main/java/module-info.java @@ -1,5 +1,5 @@ /** - * Defines the core of the StarOpenSource Engine. + * The core of the StarOpenSource Engine. * * @since v1-alpha1 */ @@ -15,7 +15,7 @@ module sosengine.base { exports de.staropensource.sosengine.base.annotations; exports de.staropensource.sosengine.base.classes; exports de.staropensource.sosengine.base.classes.helpers; - exports de.staropensource.sosengine.base.data.info; + exports de.staropensource.sosengine.base.data.information; exports de.staropensource.sosengine.base.data.versioning; exports de.staropensource.sosengine.base.events; exports de.staropensource.sosengine.base.exceptions; @@ -43,7 +43,7 @@ module sosengine.base { opens de.staropensource.sosengine.base.annotations; opens de.staropensource.sosengine.base.classes; opens de.staropensource.sosengine.base.classes.helpers; - opens de.staropensource.sosengine.base.data.info; + opens de.staropensource.sosengine.base.data.information; opens de.staropensource.sosengine.base.data.versioning; opens de.staropensource.sosengine.base.events; opens de.staropensource.sosengine.base.exceptions; diff --git a/base/src/test/java/de/staropensource/sosengine/base/srctests/EngineConfigurationTest.java b/base/src/test/java/de/staropensource/sosengine/base/srctests/EngineConfigurationTest.java index a773514..96a284a 100644 --- a/base/src/test/java/de/staropensource/sosengine/base/srctests/EngineConfigurationTest.java +++ b/base/src/test/java/de/staropensource/sosengine/base/srctests/EngineConfigurationTest.java @@ -37,11 +37,6 @@ import static org.junit.jupiter.api.Assertions.*; @SuppressWarnings("unused") @DisplayName("EngineConfiguration") class EngineConfigurationTest extends TestBase { - /** - * The property group for the base engine. - */ - private final String group = EngineConfiguration.getGroup(); - /** * Tests the method {@code loadConfiguration}. */ @@ -83,7 +78,7 @@ class EngineConfigurationTest extends TestBase { Properties properties = new Properties(); for (String setting : settings.keySet()) - properties.setProperty(group + setting, (String) settings.get(setting)[0]); + properties.setProperty(EngineConfiguration.getInstance().getGroup() + setting, (String) settings.get(setting)[0]); EngineConfiguration.getInstance().loadConfiguration(properties); diff --git a/base/src/test/java/de/staropensource/sosengine/base/srctests/TestBase.java b/base/src/test/java/de/staropensource/sosengine/base/srctests/TestBase.java index b121d45..944ab28 100644 --- a/base/src/test/java/de/staropensource/sosengine/base/srctests/TestBase.java +++ b/base/src/test/java/de/staropensource/sosengine/base/srctests/TestBase.java @@ -47,7 +47,7 @@ public class TestBase { private final UnitLogger logger = new UnitLogger(getClass()); /** - * Determines whether the engine should be automatically initialized or not. + * Contains whether the engine should be automatically initialized or not. */ protected boolean doInitialization = true; diff --git a/build.gradle b/build.gradle index 2f8dd7d..cb375e3 100644 --- a/build.gradle +++ b/build.gradle @@ -27,8 +27,14 @@ plugins { // Register task for Javadoc generation for all subsystems tasks.register("javadocAll", Javadoc) { // Subprojects to exclude - def nodoc = [ - ":testapp", + def subprojects = [ + ":base", + ":ansi", + ":slf4j-compat", + ":graphics", + ":graphics:glfw", + ":graphics:opengl", + ":graphics:vulkan", ] // Task metadata @@ -36,23 +42,8 @@ tasks.register("javadocAll", Javadoc) { setGroup("documentation") // Make sure the source is delomboked first - boolean match - for (Project subproject : getSubprojects()) { - match = false - - // Check if name is in 'nodoc' list - for (String name : nodoc) - if (subproject.getName() == name) - match = true - - if (match) - continue - - // Add dependsOn if delombok task is found - try { - dependsOn(subproject.getTasks().named("delombok")) - } catch(UnknownTaskException ignored) {} - } + for (String subproject : subprojects) + dependsOn(project(subproject).getTasks().named("delombok")) // Set output directory, source and classpath setSource(subprojects.collect({ project(it).projectDir.getPath() + "/build/generated/sources/delombok/java/main/" })) @@ -103,7 +94,7 @@ tasks.register("javadocAll", Javadoc) { // Set group, version and repositories for all projects allprojects { group = project.group - version = project.versioningVersion + "-" + project.versioningType + project.versioningTyperelease + project.versioningFork + version = "v" + project.versioningVersion + "-" + project.versioningType + project.versioningTyperelease + project.versioningFork repositories { mavenCentral() diff --git a/docs/docs/getting-started/initializing.md b/docs/docs/getting-started/initializing.md index 516d23d..cc7051d 100644 --- a/docs/docs/getting-started/initializing.md +++ b/docs/docs/getting-started/initializing.md @@ -54,43 +54,57 @@ There are eight log levels you can use: Here's an example: ```java -Logger.info(new LogIssuer(Main.class), "Hello World!"); +Logger.info(getClass(), "APPLICATION", null, "Hello World!"); +// ^ ^ ^ ^ +// | | | | +// | | | --- The message you want to print. +// | | -------- Metadata string (can be null). If your class/method processes data or something, you can include it here. +// | ---------------------- Origin of the message. It identifies from which part of your application the message came. +// -------------------------------------- Log priority/type. In this case, we want to emit an informational message ``` -Now, what is this `LogIssuer` garbage? It's simple: It describes the class issuing the log call. You can for example pass along information about the data you are handling to easily distinguish instances: +Now, why do I need to supply so many arguments just for a simple "Hello World!"? +It's simple: It describes the class issuing the log call. + +Here's an example: ```java class ExampleClass() { - @NotNull - private String string; + private @NotNull String string; public ExampleClass(@NotNull String string) { this.string = string; } public boolean checkForEscapes() { - Logger.diag(new LogIssuer(getClass(), string), "Checking for escapes"); + Logger.diag(getClass(), "APPLICATION", string, "Checking for escapes"); return string.contains("\\"); } public boolean checkIfEmpty() { - Logger.diag(new LogIssuer(getClass(), string), "Checking if empty"); + Logger.diag(getClass(), "APPLICATION", string, "Checking if empty"); return string.isEmpty(); } } ``` -But it's lame to always pass that to every log call you make. For that reason `LoggerInstance` exists. -Here's the class from before but with `LoggerInstance`: +Now that's nice and all, but it's annoying to pass three arguments describing your class to log methods +and will – over time – make log messages unorganized and unmaintainable. That's not good. That's why +the `LoggerInstance` class exists. It's purpose is to pass these to every log call you make. The only +thing you need to do it to is to pass it some data about your class and it does the job for you. + +Here's an example of the code before, but with `LoggerInstance`: ```java class ExampleClass() { - @NotNull - private LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), string)); - - @NotNull - private String string; + private @NotNull LoggerInstance logger; + private @NotNull String string; public ExampleClass(@NotNull String string) { this.string = string; + logger = LoggerInstance.Builder() + .setClass(getClass()) + .setOrigin("APPLICATION") // If you intend on 'origin' being set to "APPLICATION", you can leave this out. This has just been included for completeness. + .setMetadata(string) // Include the string we are doing stuff with as metadata + .build(); } public boolean checkForEscapes() { diff --git a/gradle.properties b/gradle.properties index 135b5d7..54c328a 100644 --- a/gradle.properties +++ b/gradle.properties @@ -18,6 +18,7 @@ # # Versioning +versioningCodename=Sugarcookie versioningVersion=1 versioningType=alpha versioningTyperelease=2 diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystem.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystem.java index 455fb20..48b11e2 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystem.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystem.java @@ -20,13 +20,11 @@ package de.staropensource.sosengine.graphics.glfw; import de.staropensource.sosengine.base.annotations.EngineSubsystem; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.classes.SubsystemClass; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.DependencyVector; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.Miscellaneous; import de.staropensource.sosengine.graphics.events.GraphicsErrorEvent; import de.staropensource.sosengine.graphics.glfw.exceptions.GlfwInitializationException; @@ -41,18 +39,17 @@ import java.util.Arrays; import static org.lwjgl.glfw.GLFW.*; /** - * The main object of the GLFW subsystem. + * The main class of the GLFW subsystem. * * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public final class GlfwSubsystem implements SubsystemMainClass { +public final class GlfwSubsystem extends SubsystemClass { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -63,12 +60,12 @@ public final class GlfwSubsystem implements SubsystemMainClass { private static GlfwSubsystem instance = null; /** - * Logger instance. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance - * @since v1-alpha0 + * @since v1-alpha1 */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); /** * The {@link GLFWErrorCallback} to use. @@ -112,9 +109,8 @@ public final class GlfwSubsystem implements SubsystemMainClass { } /** {@inheritDoc} */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector(getName(), StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString(), Arrays.stream(new String[]{ "graphics" }).toList()); } diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystemConfiguration.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystemConfiguration.java index b4cc9dc..9ef8d5e 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystemConfiguration.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/GlfwSubsystemConfiguration.java @@ -19,31 +19,25 @@ package de.staropensource.sosengine.graphics.glfw; -import de.staropensource.sosengine.base.classes.SubsystemConfiguration; -import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.classes.Configuration; import de.staropensource.sosengine.base.utility.parser.PropertyParser; import de.staropensource.sosengine.graphics.glfw.types.GlfwPlatform; import lombok.Getter; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; -import java.util.Properties; - /** - * Provides the subsystem configuration for all classes in a centralized place. + * Provides the GLFW subsystem configuration. * - * @since v1-alpha0 + * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter -public final class GlfwSubsystemConfiguration implements SubsystemConfiguration { +public final class GlfwSubsystemConfiguration extends Configuration { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -54,25 +48,22 @@ public final class GlfwSubsystemConfiguration implements SubsystemConfiguration private static GlfwSubsystemConfiguration instance; /** - * Defines the group every property must start with to be recognized as a subsystem configuration setting. + * Defines the group in which setting overrides must begin with. * * @since v1-alpha0 - * * -- GETTER -- - * Returns the group that every property must start with to be recognized as a subsystem configuration setting. + * Returns the group in which setting overrides must begin with. * * @return property group * @since v1-alpha0 */ - @NotNull @Getter - private static final String group = "sosengine.graphics.glfw."; + private final @NotNull String group = "sosengine.graphics.glfw."; /** * Contains the platform GLFW will try to initialize with. * * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #platform}. * @@ -89,9 +80,8 @@ public final class GlfwSubsystemConfiguration implements SubsystemConfiguration * Only affects the {@link GlfwPlatform#WAYLAND} platform. * * @since v1-alpha2 - * * -- GETTER -- - * Gets the value for {@#link disableLibdecor}. + * Gets the value for {@link #disableLibdecor}. * * @return variable value * @see #disableLibdecor @@ -106,57 +96,46 @@ public final class GlfwSubsystemConfiguration implements SubsystemConfiguration * @since v1-alpha0 */ public GlfwSubsystemConfiguration() { + super("ENGINE"); // TODO Wait for flexible constructor bodies (JEP 482) to be implemented into the JVM as a stable feature. We don't want to use preview features in production code. + // Only allow one instance if (instance == null) instance = this; else - Logger.crash(new LogIssuer(getClass(), CodePart.ENGINE), "Tried initializing " + getClass().getName() + " twice"); + logger.crash("Only one instance of this class is allowed, use getInstance() instead of creating a new instance"); loadDefaultConfiguration(); } /** {@inheritDoc} */ - public void loadConfiguration(@NotNull Properties properties) { - // Define variables - PropertyParser parser = new PropertyParser(properties); - - for (String property : properties.stringPropertyNames()) { - // Check if property name starts with group - if (!property.startsWith(group)) continue; - - // Skip to important stuff - property = property.substring(group.length()); - - // Match settings - try { - switch (property) { - case "platform" -> { - try { - platform = GlfwPlatform.valueOf(parser.getString(group + property).toUpperCase()); - } catch (IllegalArgumentException ignored) { - System.out.println("Platform " + parser.getString(group + property) + " is not valid"); - } - } - case "disableLibdecor" -> disableLibdecor = parser.getBoolean(group + property); + @Override + protected void matchProperty(@NotNull PropertyParser parser, @NotNull String property) { + switch (property) { + case "platform" -> { + try { + platform = GlfwPlatform.valueOf(parser.getString(group + property).toUpperCase()); + } catch (IllegalArgumentException ignored) { + System.out.println("Platform " + parser.getString(group + property) + " is not valid"); } - } catch (NullPointerException ignored) {} + } + case "disableLibdecor" -> disableLibdecor = parser.getBoolean(group + property); } } /** {@inheritDoc} */ - public void loadConfiguration() { - loadConfiguration(System.getProperties()); - } + @Override + protected void processSettings(@NotNull PropertyParser parser) {} /** {@inheritDoc} */ + @Override public void loadDefaultConfiguration() { platform = GlfwPlatform.ANY; disableLibdecor = false; } /** {@inheritDoc} */ - @Nullable - public Object getSetting(@NotNull String setting) { + @Override + public @Nullable Object getSetting(@NotNull String setting) { switch (setting) { case "platform" -> { return platform; } case "disableLibdecor" -> { return disableLibdecor; } diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/KeyCallback.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/KeyCallback.java index 8ae33fa..29a79f5 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/KeyCallback.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/KeyCallback.java @@ -30,20 +30,20 @@ import org.lwjgl.glfw.GLFWKeyCallbackI; import static org.lwjgl.glfw.GLFW.*; /** - * A {@link GLFWKeyCallbackI} implementation. + * A {@link GLFWKeyCallbackI} implementation, which forward them to {@link InputEvent}. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public final class KeyCallback extends WindowCallback implements GLFWKeyCallbackI { /** - * A {@link InputEvent} instance, to avoid creating too many objects + * An {@link InputEvent} instance, to avoid creating too many objects * and making too many allocations, which would potentially decrease * performance. * * @since v1-alpha2 */ - private final InputEvent event = new InputEvent(); + private static final InputEvent event = new InputEvent(); /** * Constructs this class. diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/MouseButtonCallback.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/MouseButtonCallback.java index 42d5832..378a5e0 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/MouseButtonCallback.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/MouseButtonCallback.java @@ -30,20 +30,20 @@ import org.lwjgl.glfw.GLFWMouseButtonCallbackI; import static org.lwjgl.glfw.GLFW.*; /** - * A {@link GLFWMouseButtonCallbackI} implementation. + * A {@link GLFWMouseButtonCallbackI} implementation, which forward them to {@link InputEvent}. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public final class MouseButtonCallback extends WindowCallback implements GLFWMouseButtonCallbackI { /** - * A {@link InputEvent} instance, to avoid creating too many objects + * An {@link InputEvent} instance, to avoid creating too many objects * and making too many allocations, which would potentially decrease * performance. * * @since v1-alpha2 */ - private final InputEvent event = new InputEvent(); + private static final InputEvent event = new InputEvent(); /** * Constructs this class. diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/package-info.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/package-info.java new file mode 100644 index 0000000..65e4f8e --- /dev/null +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/callbacks/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Callbacks, which emit {@link de.staropensource.sosengine.base.classes.Event}s. + * + * @since v1-alpha2 + */ +package de.staropensource.sosengine.graphics.glfw.callbacks; diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwInternalClass.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwInternalClass.java index 1d3ffd8..3239e15 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwInternalClass.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwInternalClass.java @@ -19,30 +19,55 @@ package de.staropensource.sosengine.graphics.glfw.classes; -import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.logging.LoggerInstance; import de.staropensource.sosengine.graphics.classes.Monitor; import de.staropensource.sosengine.graphics.classes.api.ApiInternalClass; import de.staropensource.sosengine.graphics.exceptions.NoMonitorsFoundException; +import lombok.Getter; import org.jetbrains.annotations.NotNull; import org.lwjgl.PointerBuffer; import java.lang.reflect.InvocationTargetException; import java.util.LinkedHashSet; -import static org.lwjgl.glfw.GLFW.*; +import static org.lwjgl.glfw.GLFW.glfwGetMonitors; -@SuppressWarnings({ "unused" }) +/** + * The internal API class for GLFW-powered Graphics APIs. + * + * @since v1-alpha2 + */ +@Getter +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class GlfwInternalClass implements ApiInternalClass { + /** + * Contains the {@link LoggerInstance} for this instance. + * + * @see LoggerInstance + * @since v1-alpha2 + * -- GETTER -- + * Returns the {@link LoggerInstance} for this instance. + * + * @return logger instance + * @see LoggerInstance + * @since v1-alpha2 + */ + private final LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); + + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public GlfwInternalClass() {} + /** * Returns the {@link Monitor} class. * * @return {@link Monitor} class * @since v1-alpha2 */ - @NotNull - public abstract Class getMonitorClass(); + public abstract @NotNull Class getMonitorClass(); /** * Returns all connected monitors. @@ -61,7 +86,7 @@ public abstract class GlfwInternalClass implements ApiInternalClass { try { output.add(getMonitorClass().getDeclaredConstructor(Long.TYPE).newInstance(monitors.get())); } catch (NoSuchMethodException | InstantiationException | IllegalAccessException | InvocationTargetException exception) { - Logger.crash(new LogIssuer(getClass(), CodePart.ENGINE), "Unable to create new Monitor instance: Threw an exception", exception); + logger.crash("Unable to create new Monitor instance: Threw an exception", exception); } return output; diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwManagementClass.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwManagementClass.java index 548907d..b16a7e2 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwManagementClass.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwManagementClass.java @@ -20,8 +20,6 @@ package de.staropensource.sosengine.graphics.glfw.classes; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.Miscellaneous; import de.staropensource.sosengine.graphics.classes.api.ApiManagementClass; import de.staropensource.sosengine.graphics.classes.Window; @@ -33,6 +31,11 @@ import java.util.*; import static org.lwjgl.glfw.GLFW.*; +/** + * The abstract management class for GLFW-powered Graphics APIs. + * + * @since v1-alpha2 + */ @Getter public abstract class GlfwManagementClass extends ApiManagementClass { /** @@ -40,7 +43,14 @@ public abstract class GlfwManagementClass extends ApiManagementClass { * * @since v1-alpha2 */ - protected LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + protected LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); + + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public GlfwManagementClass() {} /** {@inheritDoc} */ @Override @@ -49,9 +59,8 @@ public abstract class GlfwManagementClass extends ApiManagementClass { } /** {@inheritDoc} */ - @NotNull @Override - public LinkedHashMap<@NotNull Window, @NotNull Throwable> runRenderLoop() { + public @NotNull LinkedHashMap<@NotNull Window, @NotNull Throwable> runRenderLoop() { // Ensure running on the main thread if (!Miscellaneous.onMainThread()) throw new NotOnMainThreadException(); @@ -76,9 +85,8 @@ public abstract class GlfwManagementClass extends ApiManagementClass { } /** {@inheritDoc} */ - @NotNull @Override - public LinkedHashMap<@NotNull Window, @NotNull Throwable> runRenderLoopContinuously(@NotNull Runnable frameCode) { + public @NotNull LinkedHashMap<@NotNull Window, @NotNull Throwable> runRenderLoopContinuously(@NotNull Runnable frameCode) { // Ensure running on the main thread if (!Miscellaneous.onMainThread()) throw new NotOnMainThreadException(); diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwMonitor.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwMonitor.java index c0e5d87..149360c 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwMonitor.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwMonitor.java @@ -30,13 +30,17 @@ import java.util.Objects; import static org.lwjgl.glfw.GLFW.*; -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +/** + * Represents a monitor. A GLFW-powered monitor. Wait... aren't monitors powered by... power? + * + * @since v1-alpha2 + */ +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public class GlfwMonitor extends Monitor { /** * Contains the {@link #identifier} as a long. * * @since v1-alpha2 - * * -- GETTER -- * Returns the monitor identifier as a long. * diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwWindow.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwWindow.java index aaafa2a..759dc4f 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwWindow.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/GlfwWindow.java @@ -47,24 +47,23 @@ import java.util.Objects; import static org.lwjgl.glfw.GLFW.*; /** - * A window on your screen. + * Abstract class for implementing GLFW-powered windows in a Graphics API. * - * @since v1-alpha0 + * @since v1-alpha2 */ -@Getter -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class GlfwWindow extends Window { /** - * Contains the {@link #identifier} as a long. + * Contains the {@link #identifier} used by GLFW. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the window identifier as a long. + * Returns the window identifier used by GLFW. * - * @return window identifier as a long + * @return GLFW identifier * @since v1-alpha2 */ + @Getter private long identifierLong; /** @@ -102,7 +101,7 @@ public abstract class GlfwWindow extends Window { * @throws UnexpectedThrowableException stuff thrown by the {@link #initializeWindow()} and {@link #render()} methods of the implementing Graphics API * @since v1-alpha2 */ - public GlfwWindow(@NotNull String name, @NotNull String title, @NotNull Vec2i size, @NotNull Vec2i minimumSize, @NotNull Vec2i maximumSize, @NotNull Vec2i position, @NotNull WindowMode windowMode, @NotNull Monitor monitor, boolean resizable, boolean borderless, boolean focusable, boolean onTop, boolean transparent, boolean rendering) throws UnexpectedThrowableException { + protected GlfwWindow(@NotNull String name, @NotNull String title, @NotNull Vec2i size, @NotNull Vec2i minimumSize, @NotNull Vec2i maximumSize, @NotNull Vec2i position, @NotNull WindowMode windowMode, @NotNull Monitor monitor, boolean resizable, boolean borderless, boolean focusable, boolean onTop, boolean transparent, boolean rendering) throws UnexpectedThrowableException { super(name, title, size, minimumSize, maximumSize, position, windowMode, monitor, resizable, borderless, focusable, onTop, transparent, rendering); } @@ -114,7 +113,7 @@ public abstract class GlfwWindow extends Window { } /** - * Initializes the GLFW window. + * Allows the Graphics API to initialize the window. * * @throws Throwable throwable * @since v1-alpha2 @@ -182,6 +181,14 @@ public abstract class GlfwWindow extends Window { setWindowMode(getWindowMode()); } + /** + * Allows the Graphics API to set custom + * window hints during window creation. + * + * @since v1-alpha2 + */ + protected abstract void setWindowHints(); + /** * Closes the associated GLFW window. * @@ -200,13 +207,6 @@ public abstract class GlfwWindow extends Window { glfwDestroyWindow(identifierLong); } - /** - * Sets window hints. - * - * @since v1-alpha2 - */ - public abstract void setWindowHints(); - /** {@inheritDoc} */ public void terminate() { setTerminated(true); @@ -275,7 +275,7 @@ public abstract class GlfwWindow extends Window { } /** - * Updates the state of the GLFW window. + * Allows the Graphics API to update it's state. * * @throws Throwable throwable * @since v1-alpha2 diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/WindowCallback.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/WindowCallback.java index 40e860f..6a402ad 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/WindowCallback.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/WindowCallback.java @@ -30,14 +30,13 @@ import org.jetbrains.annotations.NotNull; * @since v1-alpha2 */ @Getter -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class WindowCallback { /** * Refers to the {@link Window} instance * this callback is tied to. * * @since v1-alpha2 - * * -- GETTER -- * Returns the {@link Window} instance * this callback is tied to. @@ -45,8 +44,7 @@ public abstract class WindowCallback { * @return attached {@link Window} instance * @since v1-alpha2 */ - @NotNull - private final Window attachedWindow; + private final @NotNull Window attachedWindow; /** * Constructs this class. diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/package-info.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/package-info.java new file mode 100644 index 0000000..61b4b2e --- /dev/null +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/classes/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Interfaces and abstract classes which can be used for implementing classes. + *

+ * These are not to be confused with data types. See {@link de.staropensource.sosengine.graphics.glfw.types}. + */ +package de.staropensource.sosengine.graphics.glfw.classes; diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/exceptions/package-info.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/exceptions/package-info.java new file mode 100644 index 0000000..e4b8dde --- /dev/null +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/exceptions/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Exceptions thrown by the GLFW subsystem. + * + * @since v1-alpha2 + */ +package de.staropensource.sosengine.graphics.glfw.exceptions; diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/package-info.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/package-info.java index 926d01f..e3ac231 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/package-info.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains the common GLFW code. + * Code of the GLFW subsystem. * * @since v1-alpha2 */ diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/GlfwPlatform.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/GlfwPlatform.java index 4687b01..4f60619 100644 --- a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/GlfwPlatform.java +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/GlfwPlatform.java @@ -20,15 +20,14 @@ package de.staropensource.sosengine.graphics.glfw.types; /** - * Contains all available platforms - * which GLFW can be initialized with. + * Contains all available platforms which GLFW can be initialized with. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public enum GlfwPlatform { /** - * Allows GLFW to initialize with any platform. + * Allows GLFW to autodetect the platform to use. * * @since v1-alpha2 */ @@ -64,7 +63,6 @@ public enum GlfwPlatform { /** * Prefer initializing without any platform. - * This will disable any functionality. * * @since v1-alpha2 */ diff --git a/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/package-info.java b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/package-info.java new file mode 100644 index 0000000..50e1d4c --- /dev/null +++ b/graphics/glfw/src/main/java/de/staropensource/sosengine/graphics/glfw/types/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Data types in form of enums and classes. + * + * @since v1-alpha2 + */ +package de.staropensource.sosengine.graphics.glfw.types; diff --git a/graphics/glfw/src/main/java/module-info.java b/graphics/glfw/src/main/java/module-info.java index b73ab17..98241e7 100644 --- a/graphics/glfw/src/main/java/module-info.java +++ b/graphics/glfw/src/main/java/module-info.java @@ -1,4 +1,13 @@ -module sosengine.graphics.glfw.main { +import de.staropensource.sosengine.graphics.classes.Window; + +/** + * The {@code glfw} subsystem, which allows Graphics APIs to + * create {@link Window} without any hassle and allows their + * developers to focus on what's important: Graphics API development. + * + * @since v1-alpha2 + */ +module sosengine.graphics.glfw { // Dependencies // -> Subsystems requires transitive sosengine.base; diff --git a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlInternalApi.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlInternalApi.java index daf5f48..353333d 100644 --- a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlInternalApi.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlInternalApi.java @@ -26,11 +26,22 @@ import de.staropensource.sosengine.graphics.glfw.classes.GlfwMonitor; import de.staropensource.sosengine.graphics.opengl.classes.OpenGlWindow; import org.jetbrains.annotations.NotNull; +/** + * The internal API class of the OpenGL Graphics API. + * + * @since v1-alpha2 + */ public final class OpenGlInternalApi extends GlfwInternalClass { + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public OpenGlInternalApi() {} + /** {@inheritDoc} */ @Override - @NotNull - public Class getWindowClass() { + public @NotNull Class getWindowClass() { return OpenGlWindow.class; } diff --git a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlManagement.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlManagement.java index 9846cd7..cd84ff0 100644 --- a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlManagement.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlManagement.java @@ -22,7 +22,7 @@ package de.staropensource.sosengine.graphics.opengl; import de.staropensource.sosengine.graphics.glfw.classes.GlfwManagementClass; /** - * The OpenGL API management class. + * The management class of the OpenGL Graphics API. * * @since v1-alpha0 */ diff --git a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlSubsystem.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlSubsystem.java index 0dacb4c..24602ee 100644 --- a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlSubsystem.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/OpenGlSubsystem.java @@ -21,16 +21,14 @@ package de.staropensource.sosengine.graphics.opengl; import de.staropensource.sosengine.base.annotations.EngineSubsystem; import de.staropensource.sosengine.base.annotations.EventListener; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.DependencyVector; import de.staropensource.sosengine.base.types.EventPriority; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.graphics.GraphicsSubsystem; import de.staropensource.sosengine.graphics.classes.api.ApiInternalClass; -import de.staropensource.sosengine.graphics.classes.api.ApiMainClass; +import de.staropensource.sosengine.graphics.classes.api.ApiClass; import de.staropensource.sosengine.graphics.classes.api.ApiManagementClass; import de.staropensource.sosengine.graphics.events.GraphicsApiErrorEvent; import de.staropensource.sosengine.graphics.events.GraphicsErrorEvent; @@ -44,18 +42,17 @@ import java.util.Locale; import static org.lwjgl.glfw.GLFW.*; /** - * The main object for the OpenGL Graphics API. + * The main class of the OpenGL Graphics API. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public final class OpenGlSubsystem implements ApiMainClass { +public final class OpenGlSubsystem extends ApiClass { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -66,19 +63,18 @@ public final class OpenGlSubsystem implements ApiMainClass { private static OpenGlSubsystem instance = null; /** - * Logger instance. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance - * @since v1-alpha0 + * @since v1-alpha1 */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); /** * The Graphics API's internal API class. * * @see ApiInternalClass * @since v1-alpha0 - * * -- GETTER -- * {@inheritDoc} */ @@ -90,7 +86,6 @@ public final class OpenGlSubsystem implements ApiMainClass { * * @see ApiManagementClass * @since v1-alpha0 - * * -- GETTER -- * {@inheritDoc} */ @@ -112,9 +107,8 @@ public final class OpenGlSubsystem implements ApiMainClass { } /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return getApiName().toLowerCase(Locale.ROOT); } @@ -142,9 +136,8 @@ public final class OpenGlSubsystem implements ApiMainClass { } /** {@inheritDoc} */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector("opengl", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString()); } @@ -179,7 +172,7 @@ public final class OpenGlSubsystem implements ApiMainClass { * @param error graphics error * @since v1-alpha0 */ - @EventListener(event = GraphicsErrorEvent.class, priority = EventPriority.EXTREMELY_IMPORTANT) + @EventListener(event = GraphicsErrorEvent.class, priority = EventPriority.EXCLUSIVELY_IMPORTANT) public static void onGraphicsError(String error) { instance.logger.error("OpenGL returned an error: " + error); } @@ -190,7 +183,7 @@ public final class OpenGlSubsystem implements ApiMainClass { * @param error Graphics API error * @since v1-alpha0 */ - @EventListener(event = GraphicsApiErrorEvent.class, priority = EventPriority.EXTREMELY_IMPORTANT) + @EventListener(event = GraphicsApiErrorEvent.class, priority = EventPriority.EXCLUSIVELY_IMPORTANT) public static void onGraphicsApiError(String error) { instance.logger.error("Graphics API returned an error: " + error); } diff --git a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/OpenGlWindow.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/OpenGlWindow.java index 9e7727c..157255c 100644 --- a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/OpenGlWindow.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/OpenGlWindow.java @@ -32,7 +32,7 @@ import org.lwjgl.opengl.GL; import static org.lwjgl.glfw.GLFW.*; /** - * A window on your screen. + * Implements a window which supports OpenGL. * * @since v1-alpha0 */ @@ -49,6 +49,7 @@ public final class OpenGlWindow extends GlfwWindow { * @param maximumSize maximum size * @param position position * @param windowMode window mode + * @param monitor target monitor * @param resizable resizable flag * @param borderless borderless flag * @param focusable focusable flag @@ -64,18 +65,18 @@ public final class OpenGlWindow extends GlfwWindow { /** {@inheritDoc} */ @Override - public void initializeGlfwWindow() throws WindowCreationFailureException, NotOnMainThreadException { + protected void initializeGlfwWindow() throws WindowCreationFailureException, NotOnMainThreadException { ownContext(); // Own the context GL.createCapabilities(); // Create OpenGL capabilities } /** {@inheritDoc} */ @Override - public void updateGlfwState() throws NotOnMainThreadException {} + protected void updateGlfwState() throws NotOnMainThreadException {} /** {@inheritDoc} */ @Override - public void setWindowHints() { + protected void setWindowHints() { glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 4); glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 0); glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE); @@ -85,9 +86,8 @@ public final class OpenGlWindow extends GlfwWindow { // ------------------------------------------------ [ Information/Action methods ] ------------------------------------------------ // /** {@inheritDoc} */ - @NotNull @Override - public Vec2i getSizeWithDecorations() { + public @NotNull Vec2i getSizeWithDecorations() { // Ensure the window is not terminated if (isTerminated()) return new Vec2i(-1, -1); @@ -96,9 +96,8 @@ public final class OpenGlWindow extends GlfwWindow { } /** {@inheritDoc} */ - @NotNull @Override - public Vec2i getPositionWithDecorations() { + public @NotNull Vec2i getPositionWithDecorations() { // Ensure the window is not terminated if (isTerminated()) return new Vec2i(-1, -1); diff --git a/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/events/GraphicsErrorEvent.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/package-info.java similarity index 60% rename from graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/events/GraphicsErrorEvent.java rename to graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/package-info.java index 8efa4d6..f826f16 100644 --- a/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/events/GraphicsErrorEvent.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/package-info.java @@ -17,26 +17,9 @@ * along with this program. If not, see . */ -package de.staropensource.sosengine.graphics.vulkan.events; - -import org.lwjgl.glfw.GLFWErrorCallbackI; - /** - * Called when a graphics error occurs. + * Interfaces and abstract classes which can be used for implementing classes. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused" }) -public final class GraphicsErrorEvent extends de.staropensource.sosengine.graphics.events.GraphicsErrorEvent implements GLFWErrorCallbackI { - /** - * Constructs this class. - */ - public GraphicsErrorEvent() {} - - - /** {@inheritDoc} */ - @Override - public void invoke(int error, long description) { - callEvent(description + " (" + error + ")"); - } -} +package de.staropensource.sosengine.graphics.opengl.classes; diff --git a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/package-info.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/package-info.java index 9f83649..d0dae05 100644 --- a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/package-info.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains the OpenGL subsystem. + * Code of the OpenGL Graphics API. * * @since v1-alpha0 */ diff --git a/graphics/opengl/src/main/java/module-info.java b/graphics/opengl/src/main/java/module-info.java index 6967285..9d983a2 100644 --- a/graphics/opengl/src/main/java/module-info.java +++ b/graphics/opengl/src/main/java/module-info.java @@ -14,7 +14,7 @@ module sosengine.graphics.opengl { requires org.lwjgl; requires org.lwjgl.glfw; requires org.lwjgl.opengl; - requires sosengine.graphics.glfw.main; + requires sosengine.graphics.glfw; // API access exports de.staropensource.sosengine.graphics.opengl; diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystem.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystem.java index ac6b25d..2c86d34 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystem.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystem.java @@ -21,18 +21,16 @@ package de.staropensource.sosengine.graphics; import de.staropensource.sosengine.base.annotations.EngineSubsystem; import de.staropensource.sosengine.base.annotations.EventListener; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; +import de.staropensource.sosengine.base.classes.SubsystemClass; import de.staropensource.sosengine.base.classes.helpers.EventHelper; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.internal.events.InternalEngineShutdownEvent; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.DependencyVector; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.ListFormatter; import de.staropensource.sosengine.base.utility.Miscellaneous; -import de.staropensource.sosengine.graphics.classes.api.ApiMainClass; +import de.staropensource.sosengine.graphics.classes.api.ApiClass; import de.staropensource.sosengine.graphics.events.GraphicsApiErrorEvent; import de.staropensource.sosengine.graphics.events.GraphicsApiShutdownEvent; import de.staropensource.sosengine.graphics.events.GraphicsErrorEvent; @@ -46,18 +44,17 @@ import java.util.List; import java.util.Map; /** - * The main object for sos!engine's graphics subsystem. + * The main class of the Graphics subsystem. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public final class GraphicsSubsystem implements SubsystemMainClass { +public final class GraphicsSubsystem extends SubsystemClass { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -68,45 +65,34 @@ public final class GraphicsSubsystem implements SubsystemMainClass { private static GraphicsSubsystem instance = null; /** - * Logger instance. + * Contains a list of all registered Graphics APIs. * - * @see LoggerInstance + * @see ApiClass * @since v1-alpha0 - */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); - - /** - * A list of all registered Graphics APIs. - * - * @see ApiMainClass - * @since v1-alpha0 - * * -- GETTER -- * Returns a list of all registered Graphics APIs. * * @return list of all registered Graphics APIs - * @see ApiMainClass + * @see ApiClass * @since v1-alpha0 */ - @NotNull @Getter - private final Map<@NotNull String, @NotNull ApiMainClass> registeredApis = new HashMap<>(); + private final @NotNull Map<@NotNull String, @NotNull ApiClass> registeredApis = new HashMap<>(); /** - * Reference to the active Graphics API main class. + * Contains a reference to the active Graphics API main class. * - * @see ApiMainClass + * @see ApiClass * @since v1-alpha0 - * * -- GETTER -- - * Returns the active Graphics API main class. + * Returns a reference to the active Graphics API main class. * - * @return active Graphics API main class - * @see ApiMainClass + * @return Graphics API main class reference + * @see ApiClass * @since v1-alpha0 */ @Getter - private ApiMainClass api = null; + private ApiClass api = null; /** * Constructs this subsystem. @@ -114,18 +100,16 @@ public final class GraphicsSubsystem implements SubsystemMainClass { * @since v1-alpha0 */ public GraphicsSubsystem() { - // Check if subsystem has already initialized + // Only allow one instance if (instance == null) instance = this; - else { - instance.logger.crash("Graphics subsystem tried to initialize twice"); - } + else + logger.crash("Only one instance of this class is allowed, use getInstance() instead of creating a new instance"); } /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "graphics"; } @@ -133,32 +117,30 @@ public final class GraphicsSubsystem implements SubsystemMainClass { @Override public void initializeSubsystem() { // Initialize GraphicsSubsystemConfiguration and load it - new GraphicsSubsystemConfiguration(); - GraphicsSubsystemConfiguration.getInstance().loadConfiguration(); + new GraphicsSubsystemConfiguration().loadConfiguration(); // Precompute event listeners - precomputeEventListeners(); + cacheEvents(); // Warn about subsystem and API instability - logger.warn("The graphics subsystem is experimental. Subsystem and API stability is not guaranteed."); + logger.warn("The graphics subsystem is experimental. Subsystem and API stability are not guaranteed."); } /** - * Precomputes all graphics subsystem events. + * Caches all graphics subsystem events. * * @since v1-alpha0 */ - public static void precomputeEventListeners() { - EventHelper.precomputeEventListeners(GraphicsApiErrorEvent.class); - EventHelper.precomputeEventListeners(GraphicsApiShutdownEvent.class); - EventHelper.precomputeEventListeners(GraphicsErrorEvent.class); - EventHelper.precomputeEventListeners(InputEvent.class); + public static void cacheEvents() { + EventHelper.cacheEvent(GraphicsApiErrorEvent.class); + EventHelper.cacheEvent(GraphicsApiShutdownEvent.class); + EventHelper.cacheEvent(GraphicsErrorEvent.class); + EventHelper.cacheEvent(InputEvent.class); } /** {@inheritDoc} */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector("graphics", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString()); } @@ -168,7 +150,7 @@ public final class GraphicsSubsystem implements SubsystemMainClass { * @since v1-alpha0 */ @EventListener(event = InternalEngineShutdownEvent.class) - private static void shutdown() { + protected static void shutdownSubsystem() { LoggerInstance logger = instance.logger; logger.verb("Shutting down"); @@ -185,10 +167,10 @@ public final class GraphicsSubsystem implements SubsystemMainClass { /** * Registers a Graphics API. * - * @param mainClass main class of the subsystem + * @param mainClass main class of the Graphics API * @since v1-alpha0 */ - public void registerGraphicsApi(@NotNull ApiMainClass mainClass) { + public void registerGraphicsApi(@NotNull ApiClass mainClass) { logger.verb("Registering Graphics API " + mainClass.getApiName() + " (" + mainClass.getClass().getName() + ")"); Object[] output = Miscellaneous.getMapValues(registeredApis, mainClass).toArray(); @@ -201,7 +183,7 @@ public final class GraphicsSubsystem implements SubsystemMainClass { * Chooses a Graphics API to use automatically based on hardware support. * * @return if a compatible Graphics API has been chosen - * @see GraphicsSubsystem#setGraphicsApi(String) + * @see #setGraphicsApi(String) * @since v1-alpha0 */ public boolean setGraphicsApi() { @@ -243,7 +225,7 @@ public final class GraphicsSubsystem implements SubsystemMainClass { * * @param name name of the Graphics API * @return if the Graphics API has been found - * @see GraphicsSubsystem#setGraphicsApi() + * @see #setGraphicsApi() * @since v1-alpha0 */ public boolean setGraphicsApi(@NotNull String name) { diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystemConfiguration.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystemConfiguration.java index a99c702..cb8b8c9 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystemConfiguration.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/GraphicsSubsystemConfiguration.java @@ -19,10 +19,7 @@ package de.staropensource.sosengine.graphics; -import de.staropensource.sosengine.base.classes.SubsystemConfiguration; -import de.staropensource.sosengine.base.logging.Logger; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.classes.Configuration; import de.staropensource.sosengine.base.utility.parser.PropertyParser; import de.staropensource.sosengine.graphics.events.GraphicsErrorEvent; import de.staropensource.sosengine.graphics.types.window.VsyncMode; @@ -30,21 +27,18 @@ import lombok.Getter; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; -import java.util.Properties; - /** - * Provides the subsystem configuration for all classes in a centralized place. + * Provides the Graphics subsystem configuration. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @Getter -public final class GraphicsSubsystemConfiguration implements SubsystemConfiguration { +public final class GraphicsSubsystemConfiguration extends Configuration { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -58,23 +52,20 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat * Defines the group every property must start with to be recognized as a subsystem configuration setting. * * @since v1-alpha0 - * * -- GETTER -- * Returns the group that every property must start with to be recognized as a subsystem configuration setting. * * @return property group * @since v1-alpha0 */ - @NotNull @Getter - private static final String group = "sosengine.graphics."; + public final @NotNull String group = "sosengine.graphics."; /** * If enabled, allows for unintentional behaviour and excess logging.
* Unless you want to debug or work on a sensitive part of the subsystem, don't enable this! * * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #debug}. * @@ -88,7 +79,6 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat * If enabled, will log all keys being pressed or released. * * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #debugInput}. * @@ -103,7 +93,6 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat * to the console every second. * * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #debugFrames}. * @@ -118,7 +107,6 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat * * @see GraphicsErrorEvent * @since v1-alpha0 - * * -- GETTER -- * Gets the value for {@link #errorGraphicsError}. * @@ -129,14 +117,13 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat private boolean errorGraphicsError; /** - * Determines how many frames can be rendered per second. + * Contains how many frames can be rendered per second. *

* This setting determines if and how V-Sync will operate, which * (if enabled) tries to synchronize the frame rate to the monitor's * refresh rate. See {@link VsyncMode} for more information. * * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #vsyncMode}. * @@ -147,13 +134,12 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat private VsyncMode vsyncMode; /** - * Determines how many frames can be rendered per second. + * Contains how many frames can be rendered per second. *

* This value will have no effect on windows with V-Sync enabled. * Set to {@code 0} for no limit. * * @since v1-alpha2 - * * -- GETTER -- * Gets the value for {@link #maximumFramesPerSecond}. * @@ -170,48 +156,41 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat * @since v1-alpha0 */ public GraphicsSubsystemConfiguration() { + super("ENGINE"); // TODO Wait for flexible constructor bodies (JEP 482) to be implemented into the JVM as a stable feature. We don't want to use preview features in production code. + // Only allow one instance if (instance == null) instance = this; else - Logger.crash(new LogIssuer(getClass(), CodePart.ENGINE), "Tried initializing " + getClass().getName() + " twice"); + logger.crash("Only one instance of this class is allowed, use getInstance() instead of creating a new instance"); loadDefaultConfiguration(); } /** {@inheritDoc} */ - public void loadConfiguration(@NotNull Properties properties) { - // Define variables - PropertyParser parser = new PropertyParser(properties); + @Override + protected void matchProperty(@NotNull PropertyParser parser, @NotNull String property) { + switch (property) { + case "debug" -> debug = parser.getBoolean(group + property); + case "debugInput" -> debugInput = parser.getBoolean(group + property); + case "debugFrames" -> debugFrames = parser.getBoolean(group + property); - for (String property : properties.stringPropertyNames()) { - // Check if property name starts with group - if (!property.startsWith(group)) continue; + case "errorGraphicsError" -> errorGraphicsError = parser.getBoolean(group + property); - // Skip to important stuff - property = property.substring(group.length()); - - // Match settings - try { - switch (property) { - case "debug" -> debug = parser.getBoolean(group + property); - case "debugInput" -> debugInput = parser.getBoolean(group + property); - case "debugFrames" -> debugFrames = parser.getBoolean(group + property); - - case "errorGraphicsError" -> errorGraphicsError = parser.getBoolean(group + property); - - case "vsyncMode" -> { - try { - vsyncMode = VsyncMode.valueOf(parser.getString(group + property).toUpperCase()); - } catch (IllegalArgumentException exception) { - Logger.error(new LogIssuer(getClass(), CodePart.ENGINE), "V-Sync mode " + parser.getString(group + property) + " is not valid"); - } - } - case "maximumFramesPerSecond" -> maximumFramesPerSecond = parser.getInteger(group + property, true); + case "vsyncMode" -> { + try { + vsyncMode = VsyncMode.valueOf(parser.getString(group + property).toUpperCase()); + } catch (IllegalArgumentException exception) { + logger.error("V-Sync mode " + parser.getString(group + property) + " is not valid"); } - } catch (NullPointerException ignored) {} + } + case "maximumFramesPerSecond" -> maximumFramesPerSecond = parser.getInteger(group + property, true); } + } + /** {@inheritDoc} */ + @Override + protected void processSettings(@NotNull PropertyParser parser) { // Disable all debug options if 'debug' is disabled if (!debug) { debugInput = false; @@ -220,11 +199,7 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat } /** {@inheritDoc} */ - public void loadConfiguration() { - loadConfiguration(System.getProperties()); - } - - /** {@inheritDoc} */ + @Override public void loadDefaultConfiguration() { debug = false; debugInput = false; @@ -237,8 +212,8 @@ public final class GraphicsSubsystemConfiguration implements SubsystemConfigurat } /** {@inheritDoc} */ - @Nullable - public Object getSetting(@NotNull String setting) { + @Override + public @Nullable Object getSetting(@NotNull String setting) { switch (setting) { case "debug" -> { return debug; } case "debugInput" -> { return debugInput; } diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Monitor.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Monitor.java index b68811a..9302a86 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Monitor.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Monitor.java @@ -20,8 +20,6 @@ package de.staropensource.sosengine.graphics.classes; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.vectors.Vec2i; import de.staropensource.sosengine.graphics.GraphicsSubsystem; import de.staropensource.sosengine.graphics.exceptions.InvalidMonitorException; @@ -42,33 +40,31 @@ import java.util.UUID; * * @since v1-alpha2 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class Monitor { /** - * The logger instance for this class. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance * @since v1-alpha2 - * * -- GETTER -- - * Returns the logger instance for this class. + * Returns the {@link LoggerInstance} for this instance. * * @return logger instance * @see LoggerInstance * @since v1-alpha2 */ @Getter(value = AccessLevel.PROTECTED) - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final @NotNull LoggerInstance logger; /** - * Contains the unique monitor identifier. + * Contains the unique identifier. *

* This identifier is unique to every monitor and does not change during runtime. * * @since v1-alpha2 - * * -- GETTER -- - * Returns the unique monitor identifier. + * Returns the unique identifier. *

* This identifier is unique to every monitor and does not change during runtime. * @@ -84,7 +80,6 @@ public abstract class Monitor { * This identifier is used by the Graphics API to refer to a monitor and may change during runtime. * * @since v1-alpha1 - * * -- GETTER -- * Returns the monitor identifier. *

@@ -92,7 +87,6 @@ public abstract class Monitor { * * @return monitor identifier * @since v1-alpha2 - * * -- SETTER -- * Sets the monitor identifier. *

@@ -111,6 +105,7 @@ public abstract class Monitor { */ public Monitor() { this.uniqueIdentifier = UUID.randomUUID(); + logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").setMetadata(uniqueIdentifier.toString()).build(); } /** @@ -119,8 +114,7 @@ public abstract class Monitor { * @return connected monitors * @since v1-alpha2 */ - @NotNull - public static LinkedHashSet<@NotNull Monitor> getMonitors() throws NoMonitorsFoundException { + public static @NotNull LinkedHashSet<@NotNull Monitor> getMonitors() throws NoMonitorsFoundException { return GraphicsSubsystem.getInstance().getApi().getInternalApi().getMonitors(); } @@ -149,8 +143,7 @@ public abstract class Monitor { * @return monitor name * @since v1-alpha2 */ - @NotNull - public abstract String getName() throws InvalidMonitorException, NoMonitorsFoundException; + public abstract @NotNull String getName() throws InvalidMonitorException, NoMonitorsFoundException; /** * Returns the monitor size. @@ -158,8 +151,7 @@ public abstract class Monitor { * @return monitor size * @since v1-alpha2 */ - @NotNull - public abstract Vec2i getSize() throws InvalidMonitorException, NoMonitorsFoundException; + public abstract @NotNull Vec2i getSize() throws InvalidMonitorException, NoMonitorsFoundException; /** * Returns the monitor refresh rate. diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Window.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Window.java index c5fd967..cf04f16 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Window.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/Window.java @@ -21,9 +21,7 @@ package de.staropensource.sosengine.graphics.classes; import de.staropensource.sosengine.base.exceptions.UnexpectedThrowableException; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.Tristate; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.vectors.Vec2i; import de.staropensource.sosengine.graphics.GraphicsSubsystem; import de.staropensource.sosengine.graphics.types.window.WindowMode; @@ -41,51 +39,46 @@ import java.util.UUID; * Abstract class for implementing windows in a Graphics API. *

* Note that many window properties may be overridden by any - * window manager or compositor. In almost all cases, that won't happen - * though (except for window size & position in tiling wms/compositors) - * except the user asks for that change directly. + * window manager or compositor. Make sure to poll for changes + * in {@link #updateState()}. * * @since v1-alpha0 */ // TODO monitors @Getter -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class Window implements AutoCloseable { /** * A set of all active windows. * * @since v1-alpha0 */ - @NotNull - private static final Set<@NotNull Window> windows = new HashSet<>(); + private static final @NotNull Set<@NotNull Window> windows = new HashSet<>(); /** - * The logger instance for this class. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance * @since v1-alpha2 - * * -- GETTER -- - * Returns the logger instance for this class. + * Returns the {@link LoggerInstance} for this instance. * * @return logger instance * @see LoggerInstance * @since v1-alpha2 */ @Getter(value = AccessLevel.PROTECTED) - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); /** - * Determines if this window can be interacted with or not. + * Contains if this window can be interacted with or not. * * @since v1-alpha2 - * * -- GETTER -- * Returns if this window can be interacted with or not. * * @return closed flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if this window can be interacted with or not. * @@ -101,7 +94,6 @@ public abstract class Window implements AutoCloseable { * This identifier is unique to every window and does not change during runtime. * * @since v1-alpha2 - * * -- GETTER -- * Returns the unique window identifier. *

@@ -118,7 +110,6 @@ public abstract class Window implements AutoCloseable { * This identifier is used by the Graphics API to refer to a window and may change during runtime. * * @since v1-alpha1 - * * -- GETTER -- * Returns the window identifier. *

@@ -126,7 +117,6 @@ public abstract class Window implements AutoCloseable { * * @return window identifier * @since v1-alpha2 - * * -- SETTER -- * Sets the window identifier. *

@@ -139,7 +129,7 @@ public abstract class Window implements AutoCloseable { private String identifier = null; /** - * Determines the name of this window. + * Contains the name of this window. *

* Window names should: *

    @@ -156,7 +146,6 @@ public abstract class Window implements AutoCloseable { * windows and customize them. * * @since v1-alpha1 - * * -- GETTER -- * Returns the name of this window. *

    @@ -176,7 +165,6 @@ public abstract class Window implements AutoCloseable { * * @return window title * @since v1-alpha2 - * * -- SETTER -- * Sets the name of this window. *

    @@ -194,62 +182,54 @@ public abstract class Window implements AutoCloseable { * managers and compositors can use this information to identify * windows and customize them. * - * @param name new window name + * @param name new name * @since v1-alpha2 */ - @NotNull @Setter - private String name; + private @NotNull String name; /** - * Determines the title of this window. + * Contains the title of this window. * * @since v1-alpha1 - * * -- GETTER -- * Returns the window title. * * @return window title * @since v1-alpha2 - * * -- SETTER -- * Sets the window title. * - * @param title new window title + * @param title new title * @since v1-alpha2 */ - @NotNull @Setter - private String title; + private @NotNull String title; /** - * Determines the size of this window. + * Contains the size of this window. * * @since v1-alpha1 - * * -- GETTER -- * Returns the window size. * * @return window size * @since v1-alpha2 - * * -- SETTER -- * Sets the window size. * - * @param size new window size + * @param size new size * @since v1-alpha2 */ - @NotNull @Setter - private Vec2i size; + private @NotNull Vec2i size; /** - * Determines the minimum size of this window. + * Contains the minimum size of this window. *

    * If set to {@code -1}, will enforce no minimum window size. * * @since v1-alpha1 - * * -- GETTER -- * Returns the minimum window size. *

    @@ -257,26 +237,23 @@ public abstract class Window implements AutoCloseable { * * @return minimum window size * @since v1-alpha2 - * * -- SETTER -- * Sets the minimum window size. *

    * If set to {@code -1}, will enforce no minimum window size. * - * @param size new minimum window size + * @param minimumSize new minimum size * @since v1-alpha2 */ - @NotNull @Setter - private Vec2i minimumSize; + private @NotNull Vec2i minimumSize; /** - * Determines the maximum size of this window. + * Contains the maximum size of this window. *

    * If set to {@code -1}, will enforce no maximum window size. * * @since v1-alpha1 - * * -- GETTER -- * Returns the maximum window size. *

    @@ -284,113 +261,98 @@ public abstract class Window implements AutoCloseable { * * @return maximum window size * @since v1-alpha2 - * * -- SETTER -- * Sets the maximum window size. *

    * If set to {@code -1}, will enforce no maximum window size. * - * @param size new maximum window size + * @param maximumSize new maximum size * @since v1-alpha2 */ - @NotNull @Setter - private Vec2i maximumSize; + private @NotNull Vec2i maximumSize; /** - * Determines the position of this window. + * Contains the position of this window. * * @since v1-alpha2 - * * -- GETTER -- * Returns the window position. * * @return window position * @since v1-alpha2 - * * -- SETTER -- * Sets the window position. * - * @param position new window position + * @param position new position * @since v1-alpha2 */ - @NotNull @Setter - private Vec2i position; + private @NotNull Vec2i position; /** - * Determines in which {@link WindowMode} this window is in. + * Contains in which {@link WindowMode} this window is in. * * @since v1-alpha1 - * * -- GETTER -- * Returns the window mode. * * @return window mode * @since v1-alpha2 - * * -- SETTER -- * Sets the window mode. * - * @param windowMode new window mode + * @param windowMode new mode * @since v1-alpha2 */ - @NotNull @Setter - private WindowMode windowMode; + private @NotNull WindowMode windowMode; /** - * Determines on which {@link Monitor} the window is displayed on. + * Contains on which {@link Monitor} the window is displayed on. * * @since v1-alpha2 - * * -- GETTER -- * Returns the {@link Monitor} the window is displayed on. * * @return target monitor * @since v1-alpha2 - * * -- SETTER -- * Sets the {@link Monitor} the window is displayed on. * * @param monitor new target monitor * @since v1-alpha2 */ - @NotNull @Setter - private Monitor monitor; + private @NotNull Monitor monitor; /** - * Determines how fast the window may update it's contents. + * Contains how fast the window may update it's contents. * * @since v1-alpha1 - * * -- GETTER -- * Returns how fast the window may update it's contents. * * @return new window frame limit * @since v1-alpha2 - * * -- SETTER -- * Sets how fast the window may update it's contents. * - * @param framerate new window frame limit + * @param framerate new frame limit * @since v1-alpha2 */ @Setter private int framerate; /** - * Determines if this window can be resized by the user. + * Contains if this window can be resized by the user. * * @since v1-alpha1 - * * -- GETTER -- * Returns if the window is resizable. * * @return resizable flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if the window is resizable. * @@ -401,16 +363,14 @@ public abstract class Window implements AutoCloseable { private boolean resizable; /** - * Determines if this window should have a border and decorations. + * Contains if this window should have a border and decorations. * * @since v1-alpha1 - * * -- GETTER -- * Returns if the window should be rendered without any decorations. * * @return borderless flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if the window should be rendered without any decorations. * @@ -421,14 +381,12 @@ public abstract class Window implements AutoCloseable { private boolean borderless; /** - * Determines if the window can be focused. - * + * Contains if the window can be focused. * -- GETTER -- * Returns if the window can be focused. * * @return focusable flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if the window can be focused. * @@ -439,16 +397,14 @@ public abstract class Window implements AutoCloseable { private boolean focusable; /** - * Determines if this window should be displayed on top of all other windows. + * Contains if this window should be displayed on top of all other windows. * * @since v1-alpha1 - * * -- GETTER -- * Returns if the window is displayed over regular windows. * * @return on top flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if the window is displayed over regular windows. * @@ -465,7 +421,6 @@ public abstract class Window implements AutoCloseable { * window manager and potentially system settings. * * @since v1-alpha2 - * * -- GETTER -- * Returns if the window can be transparent. *

    @@ -474,7 +429,6 @@ public abstract class Window implements AutoCloseable { * * @return transparency flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if the window can be transparent. *

    @@ -488,16 +442,14 @@ public abstract class Window implements AutoCloseable { private boolean transparent; /** - * Determines if this window should be rendered. + * Contains if this window should be rendered. * * @since v1-alpha2 - * * -- GETTER -- * Returns if the window should be rendered. * * @return rendering flag state * @since v1-alpha2 - * * -- SETTER -- * Sets if the window should be rendered. * @@ -513,8 +465,7 @@ public abstract class Window implements AutoCloseable { * @return active windows * @since v1-alpha2 */ - @NotNull - public static HashSet<@NotNull Window> getWindows() { + public static @NotNull HashSet<@NotNull Window> getWindows() { return new HashSet<>(windows); } @@ -538,7 +489,7 @@ public abstract class Window implements AutoCloseable { * @throws UnexpectedThrowableException stuff thrown by the {@link #initializeWindow()} and {@link #render()} methods of the implementing Graphics API * @since v1-alpha2 */ - public Window(@NotNull String name, @NotNull String title, @NotNull Vec2i size, @NotNull Vec2i minimumSize, @NotNull Vec2i maximumSize, @NotNull Vec2i position, @NotNull WindowMode windowMode, @NotNull Monitor monitor, boolean resizable, boolean borderless, boolean focusable, boolean onTop, boolean transparent, boolean rendering) throws UnexpectedThrowableException { + protected Window(@NotNull String name, @NotNull String title, @NotNull Vec2i size, @NotNull Vec2i minimumSize, @NotNull Vec2i maximumSize, @NotNull Vec2i position, @NotNull WindowMode windowMode, @NotNull Monitor monitor, boolean resizable, boolean borderless, boolean focusable, boolean onTop, boolean transparent, boolean rendering) throws UnexpectedThrowableException { // Initialize variables this.uniqueIdentifier = UUID.randomUUID(); this.name = name; @@ -630,8 +581,7 @@ public abstract class Window implements AutoCloseable { * @return window size including decorations * @since v1-alpha2 */ - @NotNull - public abstract Vec2i getSizeWithDecorations(); + public abstract @NotNull Vec2i getSizeWithDecorations(); /** * Returns the window position including decorations (e.g. title bar). @@ -639,8 +589,7 @@ public abstract class Window implements AutoCloseable { * @return window position including decorations * @since v1-alpha2 */ - @NotNull - public abstract Vec2i getPositionWithDecorations(); + public abstract @NotNull Vec2i getPositionWithDecorations(); /** * Returns if the user, window manager or @@ -680,236 +629,123 @@ public abstract class Window implements AutoCloseable { public abstract void requestAttention(); /** - * Provides an API for building {@link Window} classes more easily. + * Provides an API for building {@link Window}s more easily. * * @since v1-alpha2 */ - @SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) - @Getter + @SuppressWarnings({ "unused" }) public static final class Builder { /** * Contains the window name. * * @see Window#name * @since v1-alpha2 - * - * -- GETTER -- - * Returns the window name. - * - * @return window name - * @see Window#name - * @since v1-alpha2 */ - @Nullable - private String name = null; + private @Nullable String name = null; /** * Contains the window title. * * @see Window#title * @since v1-alpha2 - * - * -- GETTER -- - * Returns the window title. - * - * @return window title - * @see Window#title - * @since v1-alpha2 */ - @Nullable - private String title = null; + private @Nullable String title = null; /** * Contains the window size. * * @see Window#size * @since v1-alpha2 - * - * -- GETTER -- - * Returns the window size. - * - * @return window size - * @see Window#size - * @since v1-alpha2 */ - @Nullable - private Vec2i size = null; + private @Nullable Vec2i size = null; /** * Contains the minimum window size. * * @see Window#minimumSize * @since v1-alpha2 - * - * -- GETTER -- - * Returns the minimum window size. - * - * @return minimum window size - * @see Window#minimumSize - * @since v1-alpha2 */ - @Nullable - private Vec2i minimumSize = null; + private @Nullable Vec2i minimumSize = null; /** * Contains the maximum window size. * * @see Window#maximumSize * @since v1-alpha2 - * - * -- GETTER -- - * Returns the maximum window size. - * - * @return maximum window size - * @see Window#maximumSize - * @since v1-alpha2 */ - @Nullable - private Vec2i maximumSize = null; + private @Nullable Vec2i maximumSize = null; /** * Contains the window position. * * @see Window#position * @since v1-alpha2 - * - * -- GETTER -- - * Returns the window position. - * - * @return window position - * @see Window#position - * @since v1-alpha2 */ - @Nullable - private Vec2i position = null; + private @Nullable Vec2i position = null; /** * Contains the window mode. * * @see Window#windowMode * @since v1-alpha2 - * - * -- GETTER -- - * Returns the window mode. - * - * @return window mode - * @see Window#windowMode - * @since v1-alpha2 */ - @Nullable - private WindowMode windowMode = null; + private @Nullable WindowMode windowMode = null; /** * Contains the target monitor. * * @see Window#monitor * @since v1-alpha2 - * - * -- GETTER -- - * Returns the target monitor. - * - * @return target monitor - * @see Window#monitor - * @since v1-alpha2 */ - @Nullable - private Monitor monitor = null; + private @Nullable Monitor monitor = null; /** * Contains the resizable flag. * * @see Window#resizable * @since v1-alpha2 - * - * -- GETTER -- - * Returns the resizable flag state. - * - * @return resizable flag state - * @see Window#resizable - * @since v1-alpha2 */ - @NotNull - private Tristate resizable = Tristate.UNSET; + private @NotNull Tristate resizable = Tristate.UNSET; /** * Contains the borderless flag. * * @see Window#borderless * @since v1-alpha2 - * - * -- GETTER -- - * Returns the borderless flag state. - * - * @return borderless flag state - * @see Window#borderless - * @since v1-alpha2 */ - @NotNull - private Tristate borderless = Tristate.UNSET; + private @NotNull Tristate borderless = Tristate.UNSET; /** * Contains the focusable flag. * * @see Window#focusable * @since v1-alpha2 - * - * -- GETTER -- - * Returns the focusable flag state. - * - * @return focusable flag state - * @see Window#focusable - * @since v1-alpha2 */ - @NotNull - private Tristate focusable = Tristate.UNSET; + private @NotNull Tristate focusable = Tristate.UNSET; /** * Contains the on top flag. * * @see Window#onTop * @since v1-alpha2 - * - * -- GETTER -- - * Returns the on top flag state. - * - * @return on top flag state - * @see Window#onTop - * @since v1-alpha2 */ - @NotNull - private Tristate onTop = Tristate.UNSET; + private @NotNull Tristate onTop = Tristate.UNSET; /** * Contains the transparency flag. * * @see Window#transparent * @since v1-alpha2 - * - * -- GETTER -- - * Returns the transparency flag state. - * - * @return transparency flag state - * @see Window#transparent - * @since v1-alpha2 */ - @NotNull - private Tristate transparent = Tristate.UNSET; + private @NotNull Tristate transparent = Tristate.UNSET; /** * Contains the rendering flag. * * @see Window#rendering * @since v1-alpha2 - * - * -- GETTER -- - * Returns the rendering flag state. - * - * @return rendering flag state - * @see Window#rendering - * @since v1-alpha2 */ - @NotNull - private Tristate rendering = Tristate.UNSET; + private @NotNull Tristate rendering = Tristate.UNSET; /** * Constructs this class. @@ -919,13 +755,14 @@ public abstract class Window implements AutoCloseable { public Builder() {} /** - * Builds a new {@link Window} class. + * Builds a new {@link Window} instance. * * @throws IllegalStateException if the window title, size or position is unset * @throws UnexpectedThrowableException thrown when creating a new {@link Window} instance fails + * @return {@link Window} instance * @since v1-alpha2 */ - public Window build() throws IllegalStateException, UnexpectedThrowableException { + public @NotNull Window build() throws IllegalStateException, UnexpectedThrowableException { // Booleanized tristates with default values boolean resizableBoolean = true; boolean borderlessBoolean = false; @@ -978,6 +815,160 @@ public abstract class Window implements AutoCloseable { } } + /** + * Returns the window name. + * + * @return window name + * @see Window#name + * @since v1-alpha2 + */ + public @Nullable String getName() { + return name; + } + + /** + * Returns the window title. + * + * @return window title + * @see Window#title + * @since v1-alpha2 + */ + public @Nullable String getTitle() { + return title; + } + + /** + * Returns the window size. + * + * @return window size + * @see Window#size + * @since v1-alpha2 + */ + public @Nullable Vec2i getSize() { + return size; + } + + /** + * Returns the minimum window size. + * + * @return minimum window size + * @see Window#minimumSize + * @since v1-alpha2 + */ + public @Nullable Vec2i getMinimumSize() { + return minimumSize; + } + + /** + * Returns the maximum window size. + * + * @return maximum window size + * @see Window#maximumSize + * @since v1-alpha2 + */ + public @Nullable Vec2i getMaximumSize() { + return maximumSize; + } + + /** + * Returns the window position. + * + * @return window position + * @see Window#position + * @since v1-alpha2 + */ + public @Nullable Vec2i getPosition() { + return position; + } + + /** + * Returns the window mode. + * + * @return window mode + * @see Window#windowMode + * @since v1-alpha2 + */ + public @Nullable WindowMode getWindowMode() { + return windowMode; + } + + /** + * Returns the target monitor. + * + * @return target monitor + * @see Window#monitor + * @since v1-alpha2 + */ + public @Nullable Monitor getMonitor() { + return monitor; + } + + /** + * Returns the resizable flag state. + * + * @return resizable flag state + * @see Window#resizable + * @since v1-alpha2 + */ + public @NotNull Tristate getResizable() { + return resizable; + } + + /** + * Returns the borderless flag state. + * + * @return borderless flag state + * @see Window#borderless + * @since v1-alpha2 + */ + public @NotNull Tristate getBorderless() { + return borderless; + } + + /** + * Returns the focusable flag state. + * + * @return focusable flag state + * @see Window#focusable + * @since v1-alpha2 + */ + public @NotNull Tristate getFocusable() { + return focusable; + } + + /** + * Returns the on top flag state. + * + * @return on top flag state + * @see Window#onTop + * @since v1-alpha2 + */ + public @NotNull Tristate getOnTop() { + return onTop; + } + + /** + * Returns the transparency flag state. + * + * @return transparency flag state + * @see Window#transparent + * @since v1-alpha2 + */ + public @NotNull Tristate getTransparent() { + return transparent; + } + + /** + * Returns the rendering flag state. + * + * @return rendering flag state + * @see Window#rendering + * @since v1-alpha2 + */ + public @NotNull Tristate getRendering() { + return rendering; + } + /** * Sets the window name. * @@ -985,8 +976,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setName(@Nullable String name) { + public @NotNull Builder setName(@Nullable String name) { this.name = name; return this; } @@ -998,8 +988,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setTitle(@Nullable String title) { + public @NotNull Builder setTitle(@Nullable String title) { this.title = title; return this; } @@ -1011,8 +1000,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setSize(@Nullable Vec2i size) { + public @NotNull Builder setSize(@Nullable Vec2i size) { this.size = size; return this; } @@ -1024,8 +1012,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setMinimumSize(@Nullable Vec2i minimumSize) { + public @NotNull Builder setMinimumSize(@Nullable Vec2i minimumSize) { this.minimumSize = minimumSize; return this; } @@ -1037,8 +1024,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setMaximumSize(@Nullable Vec2i maximumSize) { + public @NotNull Builder setMaximumSize(@Nullable Vec2i maximumSize) { this.maximumSize = maximumSize; return this; } @@ -1050,8 +1036,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setPosition(@Nullable Vec2i position) { + public @NotNull Builder setPosition(@Nullable Vec2i position) { this.position = position; return this; } @@ -1063,8 +1048,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setWindowMode(@Nullable WindowMode windowMode) { + public @NotNull Builder setWindowMode(@Nullable WindowMode windowMode) { this.windowMode = windowMode; return this; } @@ -1076,8 +1060,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - private synchronized Builder setMonitor(@Nullable Monitor monitor) { + private synchronized @NotNull Builder setMonitor(@Nullable Monitor monitor) { this.monitor = monitor; return this; } @@ -1089,8 +1072,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setResizable(@NotNull Tristate resizable) { + public @NotNull Builder setResizable(@NotNull Tristate resizable) { this.resizable = resizable; return this; } @@ -1102,8 +1084,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setBorderless(@NotNull Tristate borderless) { + public @NotNull Builder setBorderless(@NotNull Tristate borderless) { this.borderless = borderless; return this; } @@ -1115,8 +1096,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setFocusable(@NotNull Tristate focusable) { + public @NotNull Builder setFocusable(@NotNull Tristate focusable) { this.focusable = focusable; return this; } @@ -1128,8 +1108,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setOnTop(@NotNull Tristate onTop) { + public @NotNull Builder setOnTop(@NotNull Tristate onTop) { this.onTop = onTop; return this; } @@ -1141,8 +1120,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setTransparent(@NotNull Tristate transparent) { + public @NotNull Builder setTransparent(@NotNull Tristate transparent) { this.transparent = transparent; return this; } @@ -1154,8 +1132,7 @@ public abstract class Window implements AutoCloseable { * @return builder instance * @since v1-alpha2 */ - @NotNull - public synchronized Builder setRendering(@NotNull Tristate rendering) { + public @NotNull Builder setRendering(@NotNull Tristate rendering) { this.rendering = rendering; return this; } diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiMainClass.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiClass.java similarity index 81% rename from graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiMainClass.java rename to graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiClass.java index 3292eac..d92820d 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiMainClass.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiClass.java @@ -21,7 +21,7 @@ package de.staropensource.sosengine.graphics.classes.api; import de.staropensource.sosengine.base.Engine; import de.staropensource.sosengine.base.annotations.EventListener; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; +import de.staropensource.sosengine.base.classes.SubsystemClass; import de.staropensource.sosengine.graphics.events.GraphicsErrorEvent; import org.jetbrains.annotations.NotNull; @@ -31,13 +31,20 @@ import org.jetbrains.annotations.NotNull; * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public interface ApiMainClass extends SubsystemMainClass { +public abstract class ApiClass extends SubsystemClass { + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public ApiClass() {} + /** * Initializes the Graphics API. * * @since v1-alpha0 */ - void initializeApi(); + public abstract void initializeApi(); /** * Shuts the Graphics API down. @@ -48,7 +55,7 @@ public interface ApiMainClass extends SubsystemMainClass { * @see Engine#shutdown(int) * @since v1-alpha0 */ - void shutdownApi(); + public abstract void shutdownApi(); /** * Returns the name of the Graphics API. @@ -56,7 +63,7 @@ public interface ApiMainClass extends SubsystemMainClass { * @return Graphics API name * @since v1-alpha0 */ - String getApiName(); + public abstract String getApiName(); /** * Returns the Graphics API's internal API access class. @@ -66,7 +73,7 @@ public interface ApiMainClass extends SubsystemMainClass { * @since v1-alpha2 */ @NotNull - ApiInternalClass getInternalApi(); + public abstract ApiInternalClass getInternalApi(); /** * Returns the Graphics API's management class. @@ -76,7 +83,7 @@ public interface ApiMainClass extends SubsystemMainClass { * @since v1-alpha0 */ @NotNull - ApiManagementClass getManagement(); + public abstract ApiManagementClass getManagement(); /** * Checks if the Graphics API is compatible with the underlying hardware. @@ -84,7 +91,7 @@ public interface ApiMainClass extends SubsystemMainClass { * @return if the Graphics API is compatible * @since v1-alpha0 */ - boolean isCompatible(); + public abstract boolean isCompatible(); /** * Called when a graphics error occurs. @@ -93,5 +100,5 @@ public interface ApiMainClass extends SubsystemMainClass { * @since v1-alpha0 */ @EventListener(event = GraphicsErrorEvent.class) - static void onGraphicsError(String error) {} + public static void onGraphicsError(String error) {} } diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiInternalClass.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiInternalClass.java index cfc10e5..995f703 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiInternalClass.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiInternalClass.java @@ -27,14 +27,14 @@ import org.jetbrains.annotations.NotNull; import java.util.LinkedHashSet; /** - * The interface for internal API access, used by the graphics subsystem. + * The interface for internal API access, used by the Graphics subsystem. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) public interface ApiInternalClass { /** - * Returns the {@link Window} class. + * Returns the {@link Window} class of the Graphics API. * * @return {@link Window} class * @since v1-alpha2 diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiManagementClass.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiManagementClass.java index 0168318..ff7c16f 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiManagementClass.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/ApiManagementClass.java @@ -20,8 +20,6 @@ package de.staropensource.sosengine.graphics.classes.api; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.Math; import de.staropensource.sosengine.base.utility.Miscellaneous; import de.staropensource.sosengine.graphics.GraphicsSubsystemConfiguration; @@ -40,21 +38,27 @@ import java.util.concurrent.atomic.AtomicReference; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public abstract class ApiManagementClass { /** - * Contains the logger instance for this class. + * Contains the {@link LoggerInstance} for this instance. * * @since v1-alpha2 - * - * -- GETTER -- - * Returns the logger instance for this class. + + * Returns the {@link LoggerInstance} for this instance. * * @return logger instance * @since v1-alpha2 */ @Getter(value = AccessLevel.PROTECTED) - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); + + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public ApiManagementClass() {} /** * Returns if this Graphics API must be interacted with on the main thread. diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/package-info.java new file mode 100644 index 0000000..b12619b --- /dev/null +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/api/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Contains classes starting with {@code Api*}. + * + * @since v1-alpha2 + */ +package de.staropensource.sosengine.graphics.classes.api; diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/package-info.java index d650381..053c62a 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/package-info.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/classes/package-info.java @@ -18,7 +18,9 @@ */ /** - * Contains various interfaces and abstract classes. + * Interfaces and abstract classes which can be used for implementing classes. + *

    + * These are not to be confused with data types. See {@link de.staropensource.sosengine.graphics.types}. * * @since v1-alpha0 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiErrorEvent.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiErrorEvent.java index 544207b..20e58fe 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiErrorEvent.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiErrorEvent.java @@ -32,6 +32,8 @@ import org.jetbrains.annotations.NotNull; public final class GraphicsApiErrorEvent implements Event { /** * Constructs this class. + * + * @since v1-alpha0 */ public GraphicsApiErrorEvent() {} @@ -45,7 +47,7 @@ public final class GraphicsApiErrorEvent implements Event { public void callEvent() {} /** - * Calls the event and notifies all annotated methods. + * Emits the event and calls all event listeners. * * @param error graphics error * @since v1-alpha0 diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiShutdownEvent.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiShutdownEvent.java index aa3d38a..a49addc 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiShutdownEvent.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsApiShutdownEvent.java @@ -31,6 +31,8 @@ import de.staropensource.sosengine.base.classes.helpers.EventHelper; public final class GraphicsApiShutdownEvent implements Event { /** * Constructs this class. + * + * @since v1-alpha0 */ public GraphicsApiShutdownEvent() {} diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsErrorEvent.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsErrorEvent.java index ce642a3..48030f3 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsErrorEvent.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/GraphicsErrorEvent.java @@ -21,9 +21,6 @@ package de.staropensource.sosengine.graphics.events; import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; -import de.staropensource.sosengine.base.events.LogEvent; -import de.staropensource.sosengine.base.types.logging.LogIssuer; -import de.staropensource.sosengine.base.types.logging.LogLevel; import org.jetbrains.annotations.NotNull; /** @@ -32,23 +29,25 @@ import org.jetbrains.annotations.NotNull; * @since v1-alpha0 */ @SuppressWarnings({ "unused" }) -public class GraphicsErrorEvent implements Event { +public final class GraphicsErrorEvent implements Event { /** * Constructs this class. + * + * @since v1-alpha0 */ public GraphicsErrorEvent() {} /** * {@inheritDoc} * @deprecated use the {@code callEvent} method with arguments - * @see LogEvent#callEvent(LogLevel, LogIssuer, String) + * @see #callEvent(String) */ @Deprecated @Override public void callEvent() {} /** - * Calls the event and notifies all annotated methods. + * Emits the event and calls all event listeners. * * @param error graphics error * @since v1-alpha0 diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/InputEvent.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/InputEvent.java index 42eb976..7b89dfb 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/InputEvent.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/InputEvent.java @@ -22,8 +22,6 @@ package de.staropensource.sosengine.graphics.events; import de.staropensource.sosengine.base.classes.Event; import de.staropensource.sosengine.base.classes.helpers.EventHelper; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.graphics.GraphicsSubsystemConfiguration; import de.staropensource.sosengine.graphics.classes.Window; import de.staropensource.sosengine.graphics.types.input.Key; @@ -37,13 +35,20 @@ import org.jetbrains.annotations.Nullable; * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) -public class InputEvent implements Event { +public final class InputEvent implements Event { /** * Logger instance for this class. * * @since v1-alpha2 */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(InputEvent.class, CodePart.ENGINE)); + private final LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); + + /** + * Constructs this class. + * + * @since v1-alpha2 + */ + public InputEvent() {} /** * {@inheritDoc} @@ -55,7 +60,7 @@ public class InputEvent implements Event { public void callEvent() {} /** - * Calls the event and notifies all annotated methods. + * Emits the event and calls all event listeners. * * @param window window the input originated from. May be {@code null}, depending on the Graphics API * @param key key diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/package-info.java index f8db619..be3016d 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/events/package-info.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/events/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains events. There's nothing more to say. + * Events. There's nothing more to say. * * @since v1-alpha0 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/InvalidMonitorException.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/InvalidMonitorException.java index bdcfc15..925948e 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/InvalidMonitorException.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/InvalidMonitorException.java @@ -20,8 +20,15 @@ package de.staropensource.sosengine.graphics.exceptions; /** - * Thrown when the specified monitor could not be found. + * Thrown when the specified monitor does not exist. * * @since v1-alpha2 */ -public class InvalidMonitorException extends RuntimeException {} +public final class InvalidMonitorException extends RuntimeException { + /** + * Constructs this exception. + * + * @since v1-alpha2 + */ + public InvalidMonitorException() {} +} diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NoMonitorsFoundException.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NoMonitorsFoundException.java index 8e2ed28..d838c98 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NoMonitorsFoundException.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NoMonitorsFoundException.java @@ -20,9 +20,16 @@ package de.staropensource.sosengine.graphics.exceptions; /** - * Thrown when trying to get one or multiple monitors but none are found. + * Thrown when trying to access one or more monitors but none are found. * * @since v1-alpha2 */ @SuppressWarnings({ "unused" }) -public final class NoMonitorsFoundException extends RuntimeException {} +public final class NoMonitorsFoundException extends RuntimeException { + /** + * Constructs this exception. + * + * @since v1-alpha2 + */ + public NoMonitorsFoundException() {} +} diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NotOnMainThreadException.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NotOnMainThreadException.java index 54edab2..7dcdbf5 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NotOnMainThreadException.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/NotOnMainThreadException.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.graphics.exceptions; /** - * Thrown when trying to communicate with the Graphics API over a non-main thread. + * Thrown when trying to communicate with a Graphics API over a non-main thread. * * @since v1-alpha2 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/WindowCreationFailureException.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/WindowCreationFailureException.java index e637daf..a63a3be 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/WindowCreationFailureException.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/WindowCreationFailureException.java @@ -19,10 +19,11 @@ package de.staropensource.sosengine.graphics.exceptions; +import de.staropensource.sosengine.graphics.classes.Window; import org.jetbrains.annotations.NotNull; /** - * Thrown when a Window cannot be created. + * Thrown when a {@link Window} cannot be created. * * @since v1-alpha2 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/package-info.java new file mode 100644 index 0000000..19a49b3 --- /dev/null +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/exceptions/package-info.java @@ -0,0 +1,28 @@ +/* + * 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 . + */ + +/** + * Exceptions for Graphics APIs. + *

    + * These aren't meant for the Graphics subsystem, + * but instead for Graphics APIs, which may throw them. + * + * @since v1-alpha2 + */ +package de.staropensource.sosengine.graphics.exceptions; diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/package-info.java index 6015dcc..41e709b 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/package-info.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains the code required for drawing things to a screen. + * Code of the Graphics subsystem. * * @since v1-alpha0 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/Key.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/Key.java index b635543..1832676 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/Key.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/Key.java @@ -20,8 +20,7 @@ package de.staropensource.sosengine.graphics.types.input; /** - * Contains a list of keys which - * can be recognized by the engine. + * Contains a list of keys which can be recognized by the engine. * * @since v1-alpha2 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/KeyState.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/KeyState.java index 343864f..c9f040b 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/KeyState.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/KeyState.java @@ -20,7 +20,7 @@ package de.staropensource.sosengine.graphics.types.input; /** - * Indicates how a key is pressed. + * Contains in which state a key is. * * @since v1-alpha2 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/package-info.java new file mode 100644 index 0000000..91e026f --- /dev/null +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/input/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Data types related to input. + * + * @since v1-alpha2 + */ +package de.staropensource.sosengine.graphics.types.input; diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/package-info.java index 53675c1..492ccad 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/package-info.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/package-info.java @@ -18,7 +18,7 @@ */ /** - * Contains data types in form of enums and classes. + * Data types in form of enums and classes. * * @since v1-alpha1 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/VsyncMode.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/VsyncMode.java index abef5e4..4e49c78 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/VsyncMode.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/VsyncMode.java @@ -19,31 +19,28 @@ package de.staropensource.sosengine.graphics.types.window; +import de.staropensource.sosengine.graphics.GraphicsSubsystemConfiguration; + /** - * Used for determining if and how a window's frame rate should be synchronized to the monitor's refresh rate. + * Controls how V-Sync operates. * * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) public enum VsyncMode { /** - * Disables VSync. The frame rate can be uncapped and will allow for processing an unlimited amount of frames. + * Disables V-Sync. The frame rate will be uncapped and will allow + * for processing an unlimited amount of frames (if not limited by + * {@link GraphicsSubsystemConfiguration#maximumFramesPerSecond}). * * @since v1-alpha1 */ OFF, /** - * Enables VSync and will cap the window's frame rate at the refresh rate of the target monitor. + * Enables V-Sync and will cap the window's frame rate at the refresh rate of the target monitor. * * @since v1-alpha1 */ - ON, - - /** - * This mode will disables VSync if the window's frame rate drops below the monitor's refresh rate and enable it otherwise. - * - * @since v1-alpha1 - */ - ADAPTIVE + ON } diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/WindowMode.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/WindowMode.java index 3b135de..a6bff7b 100644 --- a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/WindowMode.java +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/WindowMode.java @@ -20,21 +20,21 @@ package de.staropensource.sosengine.graphics.types.window; /** - * Determines how a window should be displayed. + * Contains how a window should be displayed. * * @since v1-alpha1 */ @SuppressWarnings({ "unused" }) public enum WindowMode { /** - * Marks the window as {@code hidden}, making the window invisible and unable to be interacted with. + * Marks the window as hidden, making it invisible and unable to be interacted with. * * @since v1-alpha2 */ HIDDEN, /** - * Marks the window as {@code windowed}, which + * Marks the window as windowed, which * will allow the user to drag around the window freely. * * @since v1-alpha1 @@ -42,8 +42,9 @@ public enum WindowMode { WINDOWED, /** - * Same as {@link #HIDDEN} mode, but the window can - * be summoned back into {@link #WINDOWED} mode by the user. + * Same as {@link #HIDDEN} mode, but the window can be + * summoned back into {@link #WINDOWED} mode by the user + * by (for example) clicking an icon or {@code ALT+TAB}-ing. * * @since v1-alpha2 */ @@ -51,8 +52,7 @@ public enum WindowMode { /** * Same as {@link #WINDOWED}, but will make the window occupy - * most of the screen space, except for window manager/compositor - * windows/bars/docks. + * most of the screen space, except for windows/bars/docks. * * @since v1-alpha2 */ @@ -72,7 +72,8 @@ public enum WindowMode { *

    * This will increase rendering throughput as the window manager * or compositor does not need to care about other windows occupying - * the same monitor. + * the same monitor. Use (and recommend) this mode if you/your users + * want more frames per second. * * @since v1-alpha1 */ diff --git a/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/package-info.java b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/package-info.java new file mode 100644 index 0000000..a5daa2b --- /dev/null +++ b/graphics/src/main/java/de/staropensource/sosengine/graphics/types/window/package-info.java @@ -0,0 +1,25 @@ +/* + * 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 . + */ + +/** + * Data types related to windows. + * + * @since v1-alpha1 + */ +package de.staropensource.sosengine.graphics.types.window; diff --git a/graphics/src/main/java/module-info.java b/graphics/src/main/java/module-info.java index 7182260..8752cb4 100644 --- a/graphics/src/main/java/module-info.java +++ b/graphics/src/main/java/module-info.java @@ -1,5 +1,6 @@ /** - * Defines the {@code graphics} subsystem, which allows creating windows and drawing pixels onto the screen. + * The {@code graphics} subsystem, which provides abstractions and + * APIs with which graphics can be displayed on a user's screen. * * @since v1-alpha1 */ diff --git a/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/VulkanSubsystem.java b/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/VulkanSubsystem.java index 96ebd4b..712a7c8 100644 --- a/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/VulkanSubsystem.java +++ b/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/VulkanSubsystem.java @@ -20,17 +20,12 @@ package de.staropensource.sosengine.graphics.vulkan; import de.staropensource.sosengine.base.annotations.EngineSubsystem; -import de.staropensource.sosengine.base.annotations.EventListener; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.classes.SubsystemClass; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; import de.staropensource.sosengine.base.types.DependencyVector; -import de.staropensource.sosengine.base.types.EventPriority; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.utility.Miscellaneous; -import de.staropensource.sosengine.graphics.vulkan.events.GraphicsErrorEvent; import lombok.Getter; import org.jetbrains.annotations.NotNull; @@ -38,18 +33,17 @@ import static org.lwjgl.glfw.GLFW.glfwSetErrorCallback; import static org.lwjgl.glfw.GLFW.glfwTerminate; /** - * The main object for the Vulkan Graphics API. + * The main class of the Vulkan Graphics API. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public final class VulkanSubsystem implements SubsystemMainClass { +public final class VulkanSubsystem extends SubsystemClass { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -60,12 +54,12 @@ public final class VulkanSubsystem implements SubsystemMainClass { private static VulkanSubsystem instance = null; /** - * Logger instance. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance - * @since v1-alpha0 + * @since v1-alpha1 */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); /** * Constructs this subsystem. @@ -82,9 +76,8 @@ public final class VulkanSubsystem implements SubsystemMainClass { } /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "vulkan"; } @@ -95,17 +88,6 @@ public final class VulkanSubsystem implements SubsystemMainClass { logger.warn("The Vulkan API is currently a stub and does not provide Vulkan as a Graphics API.\nIf you want to remove this message, remove the Vulkan subsystem from your dependencies."); } - /** - * Called when a graphics error occurs. This method just logs the error and returns. - * - * @param error graphics error - * @since v1-alpha0 - */ - @EventListener(event = GraphicsErrorEvent.class, priority = EventPriority.EXTREMELY_IMPORTANT) - public static void onGraphicsError(String error) { - instance.logger.error("An error occurred: " + error); - } - /** * Shuts the graphics subsystem down. * @@ -126,9 +108,8 @@ public final class VulkanSubsystem implements SubsystemMainClass { } /** {@inheritDoc} */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector("vulkan", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString()); } } diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/CodePart.java b/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/package-info.java similarity index 50% rename from base/src/main/java/de/staropensource/sosengine/base/types/CodePart.java rename to graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/package-info.java index ef6d9f9..e288c7d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/CodePart.java +++ b/graphics/vulkan/src/main/java/de/staropensource/sosengine/graphics/vulkan/package-info.java @@ -17,38 +17,9 @@ * along with this program. If not, see . */ -package de.staropensource.sosengine.base.types; - -import de.staropensource.sosengine.base.types.logging.LogIssuer; - /** - * Indicates whether the class belongs to the engine, application or modification. + * Code of the Vulkan Graphics API. * - * @see LogIssuer - * @see de.staropensource.sosengine.base.logging.Logger - * @see de.staropensource.sosengine.base.logging.CrashHandler * @since v1-alpha0 */ -@SuppressWarnings({ "unused" }) -public enum CodePart { - /** - * Indicates that the specified code or class belongs to the sos!engine. - * - * @since v1-alpha0 - */ - ENGINE, - - /** - * Indicates that the specified code or class belongs to the running application. - * - * @since v1-alpha0 - */ - APPLICATION, - - /** - * Indicates that the specified code or class belongs to a modification to the running application. - * - * @since v1-alpha0 - */ - MODIFICATION -} +package de.staropensource.sosengine.graphics.vulkan; diff --git a/graphics/vulkan/src/main/java/module-info.java b/graphics/vulkan/src/main/java/module-info.java index b759ce8..42feba1 100644 --- a/graphics/vulkan/src/main/java/module-info.java +++ b/graphics/vulkan/src/main/java/module-info.java @@ -15,9 +15,7 @@ module sosengine.graphics.vulkan { // API access exports de.staropensource.sosengine.graphics.vulkan; - exports de.staropensource.sosengine.graphics.vulkan.events; // Reflection access opens de.staropensource.sosengine.graphics.vulkan; - opens de.staropensource.sosengine.graphics.vulkan.events; } diff --git a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLogger.java b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLogger.java index cb138cc..ebec376 100644 --- a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLogger.java +++ b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLogger.java @@ -22,8 +22,6 @@ package de.staropensource.sosengine.slf4j_compat; import de.staropensource.sosengine.base.Engine; import de.staropensource.sosengine.base.EngineConfiguration; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.logging.LogLevel; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; @@ -47,7 +45,7 @@ public class CompatibilityLogger extends LegacyAbstractLogger { * @see LoggerInstance * @since v1-alpha0 */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private final LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).setOrigin("ENGINE").build(); /** * Protected access allows only {@link CompatibilityLoggerFactory} and also derived classes to instantiate @@ -65,9 +63,8 @@ public class CompatibilityLogger extends LegacyAbstractLogger { * @return null * @since v1-alpha0 */ - @Nullable @Override - protected String getFullyQualifiedCallerName() { + protected @Nullable String getFullyQualifiedCallerName() { return null; } @@ -134,7 +131,7 @@ public class CompatibilityLogger extends LegacyAbstractLogger { * @param messagePattern message pattern which will be parsed and formatted * @param arguments array of arguments to be formatted, may be null * @param throwable exception whose stack trace should be logged, may be null - * @see CompatibilityLogger#forwardLogCall(Level, String, Object[], Throwable) + * @see #forwardLogCall(Level, String, Object[], Throwable) * @since v1-alpha0 */ @Override @@ -146,7 +143,7 @@ public class CompatibilityLogger extends LegacyAbstractLogger { * Just redirects to {@code forwardLogCall} * * @param event a {@link LoggingEvent} - * @see CompatibilityLogger#forwardLogCall(Level, String, Object[], Throwable) + * @see #forwardLogCall(Level, String, Object[], Throwable) * @since v1-alpha0 */ @SuppressWarnings("unused") diff --git a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerFactory.java b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerFactory.java index 2c2a601..0007b46 100644 --- a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerFactory.java +++ b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerFactory.java @@ -27,11 +27,11 @@ import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; /** - * A factory for {@link CompatibilityLogger}. + * Factory for {@link CompatibilityLogger}. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocBlankLines" }) +@SuppressWarnings({ "unused" }) public class CompatibilityLoggerFactory implements ILoggerFactory { ConcurrentMap<@NotNull String, @NotNull Logger> loggerMap; @@ -45,11 +45,12 @@ public class CompatibilityLoggerFactory implements ILoggerFactory { } /** - * Return an appropriate {@link CompatibilityLogger} instance by name. - * + * Returns an appropriate {@link CompatibilityLogger} instance by name. + *

    * This method will call {@link #createLogger(String)} if the logger * has not been created yet. * + * @param name name * @since v1-alpha0 */ public Logger getLogger(String name) { @@ -57,8 +58,9 @@ public class CompatibilityLoggerFactory implements ILoggerFactory { } /** - * Actually creates the logger for the given name. + * Actually creates the logger. * + * @param name name * @since v1-alpha0 */ protected Logger createLogger(String name) { diff --git a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerProvider.java b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerProvider.java index 8578a90..20bc7cb 100644 --- a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerProvider.java +++ b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/CompatibilityLoggerProvider.java @@ -19,7 +19,9 @@ package de.staropensource.sosengine.slf4j_compat; +import de.staropensource.sosengine.base.data.information.EngineInformation; import lombok.Getter; +import org.jetbrains.annotations.NotNull; import org.slf4j.ILoggerFactory; import org.slf4j.IMarkerFactory; import org.slf4j.helpers.BasicMarkerFactory; @@ -32,22 +34,9 @@ import org.slf4j.spi.SLF4JServiceProvider; * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocBlankLines" }) +@SuppressWarnings({ "unused" }) @Getter public class CompatibilityLoggerProvider implements SLF4JServiceProvider { - /** - * Declare the version of the SLF4J API this implementation is compiled against. - * The value of this field is modified with each major release. - * - * @since v1-alpha0 - * - * -- GETTER -- - * {@inheritDoc} - * - * @since v1-alpha0 - */ - public String requestedApiVersion = "2.0.99"; - /** * Contains a {@link CompatibilityLoggerFactory}. * @@ -59,7 +48,6 @@ public class CompatibilityLoggerProvider implements SLF4JServiceProvider { * Contains a {@link BasicMarkerFactory}. * * @since v1-alpha0 - * * -- GETTER -- * {@inheritDoc} */ @@ -69,7 +57,6 @@ public class CompatibilityLoggerProvider implements SLF4JServiceProvider { * Contains a {@link NOPMDCAdapter}. * * @since v1-alpha0 - * * -- GETTER -- * {@inheritDoc} * @@ -91,4 +78,9 @@ public class CompatibilityLoggerProvider implements SLF4JServiceProvider { markerFactory = new BasicMarkerFactory(); mDCAdapter = new NOPMDCAdapter(); } + + /** {@inheritDoc} */ + public @NotNull String getRequestedApiVersion() { + return EngineInformation.getDependencySlf4j(); + } } diff --git a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/Slf4jCompatibilitySubsystem.java b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/Slf4jCompatSubsystem.java similarity index 55% rename from slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/Slf4jCompatibilitySubsystem.java rename to slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/Slf4jCompatSubsystem.java index 7d8f1f4..dfc400a 100644 --- a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/Slf4jCompatibilitySubsystem.java +++ b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/Slf4jCompatSubsystem.java @@ -20,32 +20,33 @@ package de.staropensource.sosengine.slf4j_compat; import de.staropensource.sosengine.base.annotations.EngineSubsystem; -import de.staropensource.sosengine.base.classes.SubsystemMainClass; -import de.staropensource.sosengine.base.data.info.EngineInformation; +import de.staropensource.sosengine.base.classes.SubsystemClass; +import de.staropensource.sosengine.base.data.information.EngineInformation; import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioningSystem; import de.staropensource.sosengine.base.events.LogEvent; -import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; +import de.staropensource.sosengine.base.logging.Logger; import de.staropensource.sosengine.base.types.DependencyVector; -import de.staropensource.sosengine.base.types.logging.LogIssuer; +import de.staropensource.sosengine.base.types.logging.LogLevel; +import de.staropensource.sosengine.base.types.logging.LogRule; +import de.staropensource.sosengine.base.types.logging.LogRuleType; import lombok.Getter; import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import org.slf4j.LoggerFactory; /** - * Main object for the SLF4J Compatibility subsystem.
    + * Main class of the SLF4J Compatibility subsystem. * Note: Forwarded SLF4J messages do not trigger {@link LogEvent}s to prevent stack overflows. * * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) @EngineSubsystem -public class Slf4jCompatibilitySubsystem implements SubsystemMainClass { +public class Slf4jCompatSubsystem extends SubsystemClass { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -53,27 +54,38 @@ public class Slf4jCompatibilitySubsystem implements SubsystemMainClass { * @since v1-alpha0 */ @Getter - private static Slf4jCompatibilitySubsystem instance = null; - - /** {@inheritDoc} */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.ENGINE)); + private static Slf4jCompatSubsystem instance = null; /** * Constructs this subsystem. + * + * @since v1-alpha0 */ - public Slf4jCompatibilitySubsystem() { + public Slf4jCompatSubsystem() { // Check if subsystem has already initialized if (instance == null) instance = this; - else { - instance.logger.crash("The subsystem tried to initialize twice"); - } + else + logger.crash("Only one instance of this class is allowed, use getInstance() instead of creating a new instance"); + + // Create log rules to prevent excessive log messages from the Reflections library + Logger.getActiveRules().add(new LogRule(LogRuleType.BLACKLIST) { + @Override + public boolean evaluate(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + return issuerClass.equals(CompatibilityLogger.class) && message.contains("Reflections took "); + } + }); + Logger.getActiveRules().add(new LogRule(LogRuleType.BLACKLIST) { + @Override + public boolean evaluate(@NotNull LogLevel level, @NotNull Class issuerClass, @NotNull String issuerOrigin, @Nullable String issuerMetadata, @NotNull String message) { + return issuerClass.equals(CompatibilityLogger.class) && message.contains("could not create Vfs.Dir"); + } + }); } /** {@inheritDoc} */ - @NotNull @Override - public String getName() { + public @NotNull String getName() { return "slf4j-compat"; } @@ -84,9 +96,8 @@ public class Slf4jCompatibilitySubsystem implements SubsystemMainClass { } /** {@inheritDoc} */ - @NotNull @Override - public DependencyVector getDependencyVector() { + public @NotNull DependencyVector getDependencyVector() { return new DependencyVector("slf4j-compat", StarOpenSourceVersioningSystem.class, EngineInformation.getVersioningString()); } } diff --git a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/package-info.java b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/package-info.java index 1c1540a..a2cee7d 100644 --- a/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/package-info.java +++ b/slf4j-compat/src/main/java/de/staropensource/sosengine/slf4j_compat/package-info.java @@ -18,9 +18,8 @@ */ /** - * Contains code for the SLF4J Compatibility Logger.
    - * Simply add it as a dependency and run the constructor! + * Code of the SLF4J Compatibility subsystem. * - * @see de.staropensource.sosengine.slf4j_compat.Slf4jCompatibilitySubsystem#Slf4jCompatibilitySubsystem() + * @see de.staropensource.sosengine.slf4j_compat.Slf4jCompatSubsystem#Slf4jCompatSubsystem() */ package de.staropensource.sosengine.slf4j_compat; diff --git a/slf4j-compat/src/main/java/module-info.java b/slf4j-compat/src/main/java/module-info.java index d9fabcf..5df284f 100644 --- a/slf4j-compat/src/main/java/module-info.java +++ b/slf4j-compat/src/main/java/module-info.java @@ -1,5 +1,6 @@ /** - * Defines the {@code slf4j-compat} subsystem, which helps bridging the gap between SLF4J and the sos!engine by forwarding all SLF4J calls to the engine you love. + * The {@code slf4j-compat} subsystem, which helps bridging the gap between SLF4J and + * the StarOpenSource Engine by forwarding all SLF4J calls to the engine you love. * * @since v1-alpha1 */ diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html index 86d9f4b..23b474a 100644 --- a/src/main/javadoc/overview.html +++ b/src/main/javadoc/overview.html @@ -18,7 +18,8 @@ -->

    Welcome to the sos!engine API documentation!
    - You are currently in the documentation for the core engine and all official subsystems.

    + You are currently viewing the API documentation of the StarOpenSource Engine and it's official subsystems.

    +

    For a simplified documentation, see the sos!engine documentation.
    - For the engine source code, visit sos!git.

    + For the engine source code, visit sos!git.

    diff --git a/testapp/src/main/java/de/staropensource/sosengine/testapp/Main.java b/testapp/src/main/java/de/staropensource/sosengine/testapp/Main.java index e2f5f8d..a41cf14 100644 --- a/testapp/src/main/java/de/staropensource/sosengine/testapp/Main.java +++ b/testapp/src/main/java/de/staropensource/sosengine/testapp/Main.java @@ -23,15 +23,13 @@ import de.staropensource.sosengine.base.Engine; import de.staropensource.sosengine.base.annotations.EventListener; import de.staropensource.sosengine.base.events.ThrowableCatchEvent; import de.staropensource.sosengine.base.logging.LoggerInstance; -import de.staropensource.sosengine.base.types.CodePart; -import de.staropensource.sosengine.base.types.logging.LogIssuer; import de.staropensource.sosengine.base.types.vectors.Vec2i; import de.staropensource.sosengine.base.utility.Miscellaneous; import de.staropensource.sosengine.base.utility.parser.StackTraceParser; import de.staropensource.sosengine.graphics.GraphicsSubsystem; -import de.staropensource.sosengine.graphics.classes.api.ApiMainClass; -import de.staropensource.sosengine.graphics.classes.api.ApiManagementClass; import de.staropensource.sosengine.graphics.classes.Window; +import de.staropensource.sosengine.graphics.classes.api.ApiClass; +import de.staropensource.sosengine.graphics.classes.api.ApiManagementClass; import de.staropensource.sosengine.graphics.events.InputEvent; import de.staropensource.sosengine.graphics.types.input.Key; import de.staropensource.sosengine.graphics.types.input.KeyState; @@ -43,15 +41,16 @@ import org.jetbrains.annotations.Nullable; import java.util.LinkedHashMap; /** - * The initialization class for sos!engine's development application. + * The main class of the sos!engine development application. + * + * @since v1-alpha0 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) +@SuppressWarnings({ "unused", "JavadocDeclaration" }) public final class Main { /** * Contains the class instance. * * @since v1-alpha0 - * * -- GETTER -- * Returns the class instance. * @@ -65,7 +64,6 @@ public final class Main { * Reference to the main engine object. * * @see Engine - * * -- GETTER -- * Returns the main engine object. * @@ -76,11 +74,12 @@ public final class Main { private Engine engine; /** - * Logger instance. + * Contains the {@link LoggerInstance} for this instance. * * @see LoggerInstance + * @since v1-alpha1 */ - private final LoggerInstance logger = new LoggerInstance(new LogIssuer(getClass(), CodePart.APPLICATION)); + private final @NotNull LoggerInstance logger = new LoggerInstance.Builder().setClazz(getClass()).build(); /** * Used for terminating the render loop. @@ -91,6 +90,8 @@ public final class Main { /** * Constructs this class. + * + * @since v1-alpha0 */ public Main() {} @@ -98,8 +99,9 @@ public final class Main { * The program's entrypoint. * Calls {@link #run(String[])} after invocation. * - * @see Main#run(String[]) + * @see #run(String[]) * @param args program's command line arguments + * @since v1-alpha0 */ public static void main(String[] args) { getInstance().run(args); @@ -109,8 +111,9 @@ public final class Main { * The program's entrypoint except it's not static. * Here's where the "real magic" happens. * - * @see Main#main(String[]) + * @see #main(String[]) * @param args program's command line arguments + * @since v1-alpha0 */ @SneakyThrows public void run(String[] args) { @@ -126,7 +129,7 @@ public final class Main { logger.crash("No Graphics API is compatible"); // Define 'api' & 'management' variables - ApiMainClass api = GraphicsSubsystem.getInstance().getApi(); + ApiClass api = GraphicsSubsystem.getInstance().getApi(); ApiManagementClass management = api.getManagement(); // Create window diff --git a/testapp/src/main/java/de/staropensource/sosengine/testapp/package-info.java b/testapp/src/main/java/de/staropensource/sosengine/testapp/package-info.java index 532d611..f827600 100644 --- a/testapp/src/main/java/de/staropensource/sosengine/testapp/package-info.java +++ b/testapp/src/main/java/de/staropensource/sosengine/testapp/package-info.java @@ -18,7 +18,9 @@ */ /** - * Contains the code for the engine development application. + * Code for the sos!engine development application. * You can always safely ignore everything in this package. + * + * @since v1-alpha0 */ package de.staropensource.sosengine.testapp; diff --git a/testapp/src/main/java/module-info.java b/testapp/src/main/java/module-info.java index ff96361..0133a06 100644 --- a/testapp/src/main/java/module-info.java +++ b/testapp/src/main/java/module-info.java @@ -1,5 +1,5 @@ /** - * Defines the sos!engine test application, used by engine developers to test their changes. + * The sos!engine test application, used by engine developers to test their changes. * This module is very uninteresting for non-engine developers. * * @since v1-alpha1