From 9c1f5711a7ced58d5f3f0932e03ecb69e19de3a4 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Thu, 11 Jul 2024 04:17:03 +0200 Subject: [PATCH] Update Javadoc and apply a few code fixes --- .../staropensource/sosengine/base/Engine.java | 4 ++ .../base/classes/SubsystemMainClass.java | 3 +- ...IncompatibleVersioningSystemException.java | 7 ++++ .../InvalidVersionStringException.java | 4 +- .../UnmetDependenciesException.java | 13 ++++++ .../base/types/ShortcodeParserSkeleton.java | 7 ++++ .../types/immutable/ImmutableArrayList.java | 2 +- .../types/immutable/ImmutableHashMap.java | 3 +- .../immutable/ImmutableLinkedHashMap.java | 3 +- .../types/immutable/ImmutableLinkedList.java | 2 +- .../types/versioning/VersioningSystem.java | 2 + .../base/utility/DependencyResolver.java | 40 ++++++++++++++++++- .../graphics/opengl/classes/Window.java | 2 +- 13 files changed, 83 insertions(+), 9 deletions(-) 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 d2c64f2..dc3c6d5 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/Engine.java +++ b/base/src/main/java/de/staropensource/sosengine/base/Engine.java @@ -28,6 +28,7 @@ import de.staropensource.sosengine.base.data.versioning.StarOpenSourceVersioning import de.staropensource.sosengine.base.events.EngineCrashEvent; import de.staropensource.sosengine.base.events.EngineShutdownEvent; import de.staropensource.sosengine.base.events.LogEvent; +import de.staropensource.sosengine.base.exceptions.UnmetDependenciesException; import de.staropensource.sosengine.base.internal.events.InternalEngineShutdownEvent; import de.staropensource.sosengine.base.logging.CrashHandler; import de.staropensource.sosengine.base.logging.Logger; @@ -93,6 +94,7 @@ public final class Engine implements SubsystemMainClass { * Returns a list of all registered subsystems. * The list is sorted after initialization order. * + * @return subsystem list * @since 1-alpha1 */ @NotNull @@ -304,6 +306,8 @@ public final class Engine implements SubsystemMainClass { for (DependencyVector vector : resolver.resolve().getOrder()) // smol workaround order.add((DependencySubsystemVector) vector); } catch (Throwable throwable) { + if (throwable instanceof UnmetDependenciesException) + ((UnmetDependenciesException) throwable).getUnmetDependencies(); logger.crash("An error occurred trying to resolve subsystem dependencies: " + throwable.getClass().getName() + (throwable.getMessage() == null ? "" : ": " + throwable.getMessage())); throw throwable; } diff --git a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java b/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java index c750935..b9bbc06 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java +++ b/base/src/main/java/de/staropensource/sosengine/base/classes/SubsystemMainClass.java @@ -51,8 +51,9 @@ public interface SubsystemMainClass { /** * Returns the {@link DependencyVector} for this subsystem. * - * @see DependencyVector + * @return {@link DependencyVector} for this subsystem * @since 1-alpha1 + * @see DependencyVector */ @NotNull DependencyVector getDependencyVector(); diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/IncompatibleVersioningSystemException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/IncompatibleVersioningSystemException.java index 6aef17b..ef841e9 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/IncompatibleVersioningSystemException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/IncompatibleVersioningSystemException.java @@ -28,6 +28,13 @@ import de.staropensource.sosengine.base.types.versioning.VersioningSystem; */ @SuppressWarnings({ "unused" }) public class IncompatibleVersioningSystemException extends Exception { + /** + * Constructs this exception. + * + * @param required required versioning system ie. the versioning system throwing this error + * @param found found versioning system ie. the incompatible one + * @since 1-alpha1 + */ public IncompatibleVersioningSystemException(VersioningSystem required, VersioningSystem found) { super("The versioning system " + required + " is incompatible with " + found); } diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/InvalidVersionStringException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/InvalidVersionStringException.java index 7ff5191..d57765d 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/InvalidVersionStringException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/InvalidVersionStringException.java @@ -30,8 +30,8 @@ import org.jetbrains.annotations.Nullable; * * @since 1-alpha1 */ -@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) @Getter +@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) public class InvalidVersionStringException extends Exception { /** * Contains the throwable supplied to the constructor. @@ -45,7 +45,7 @@ public class InvalidVersionStringException extends Exception { * @since 1-alpha1 */ @Nullable - Throwable throwable; + private final Throwable throwable; /** * Constructs this exception. diff --git a/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnmetDependenciesException.java b/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnmetDependenciesException.java index 8537cb9..d324cda 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnmetDependenciesException.java +++ b/base/src/main/java/de/staropensource/sosengine/base/exceptions/UnmetDependenciesException.java @@ -35,11 +35,17 @@ import java.util.Map; 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. * * @since 1-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. * * @return unmet dependencies list * @since 1-alpha1 @@ -47,6 +53,13 @@ public class UnmetDependenciesException extends Exception { @NotNull private final Map<@NotNull DependencyVector, @NotNull String> unmetDependencies; + /** + * Constructs this exception. + * + * @param unmetDependencies map of unmet dependencies + * @since 1-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/types/ShortcodeParserSkeleton.java b/base/src/main/java/de/staropensource/sosengine/base/types/ShortcodeParserSkeleton.java index da7b17b..9ffcbf0 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/ShortcodeParserSkeleton.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/ShortcodeParserSkeleton.java @@ -47,6 +47,7 @@ import java.util.List; * * @since 1-alpha1 */ +@SuppressWarnings({ "unused", "JavadocDeclaration", "JavadocBlankLines" }) public abstract class ShortcodeParserSkeleton { /** * Logger instance. @@ -60,6 +61,12 @@ public abstract class ShortcodeParserSkeleton { * A list of components the parsed string is made out of. * * @since 1-alpha1 + * + * -- GETTER -- + * Returns a list of components the parsed string is made out of. + * + * @return component list of the parsed string + * @since 1-alpha1 */ @NotNull @Getter 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 f88440f..bce9cc0 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 @@ -26,8 +26,8 @@ import java.util.function.UnaryOperator; /** * An unmodifiable {@link ArrayList}. - * {@inheritDoc} * + * @param contained type * @since 1-alpha1 */ @SuppressWarnings({ "unused" }) 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 8cab490..ea74471 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 @@ -28,8 +28,9 @@ import java.util.function.BiFunction; /** * An unmodifiable {@link Map}. - * {@inheritDoc} * + * @param contained key type + * @param contained value type * @since 1-alpha1 */ @SuppressWarnings({ "unused" }) 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 c9f216a..f56033a 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 @@ -28,8 +28,9 @@ import java.util.function.BiFunction; /** * An unmodifiable {@link Map}. - * {@inheritDoc} * + * @param contained key type + * @param contained value type * @since 1-alpha1 */ @SuppressWarnings({ "unused" }) 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 6656600..3b86d93 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 @@ -29,8 +29,8 @@ import java.util.function.UnaryOperator; /** * An unmodifiable {@link LinkedList}. - * {@inheritDoc} * + * @param contained type * @since 1-alpha1 */ @SuppressWarnings({ "unused" }) diff --git a/base/src/main/java/de/staropensource/sosengine/base/types/versioning/VersioningSystem.java b/base/src/main/java/de/staropensource/sosengine/base/types/versioning/VersioningSystem.java index dbb70ca..6a91c44 100644 --- a/base/src/main/java/de/staropensource/sosengine/base/types/versioning/VersioningSystem.java +++ b/base/src/main/java/de/staropensource/sosengine/base/types/versioning/VersioningSystem.java @@ -33,6 +33,7 @@ public interface VersioningSystem { /** * Returns the name of this versioning system. * + * @return name of this versioning system * @since 1-alpha1 */ @NotNull @@ -43,6 +44,7 @@ public interface VersioningSystem { * * @param version the version 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 * @since 1-alpha1 */ @Range(from = 0, to = 2) 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 9a30b74..3542002 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 @@ -24,6 +24,7 @@ import de.staropensource.sosengine.base.exceptions.UnmetDependenciesException; import de.staropensource.sosengine.base.types.dependency.DependencyVector; import de.staropensource.sosengine.base.types.immutable.ImmutableArrayList; import de.staropensource.sosengine.base.types.immutable.ImmutableLinkedList; +import lombok.Getter; import org.jetbrains.annotations.NotNull; import java.util.*; @@ -42,6 +43,20 @@ public final class DependencyResolver { */ List vectors = new ArrayList<>(); + /** + * {@code true} if the current dependency vector list has been resolved successfully. + * + * @since 1-alpha1 + * + * -- GETTER -- + * Returns {@code true} if the current dependency vector list has been resolved successfully. + * + * @return if the current dependency vector list has been resolved + * @since 1-alpha1 + */ + @Getter + private boolean resolved = false; + /** * Constructs this class. */ @@ -51,10 +66,12 @@ public final class DependencyResolver { * Adds a dependency vector. * * @param vector dependency vector to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVector(@NotNull DependencyVector vector) { vectors.add(vector); + resolved = false; return this; } @@ -62,10 +79,12 @@ public final class DependencyResolver { * Adds multiple dependency vectors. * * @param vectors dependency vectors to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVectors(@NotNull DependencyVector[] vectors) { addVectors(Arrays.stream(vectors).toList()); + resolved = false; return this; } @@ -73,10 +92,12 @@ public final class DependencyResolver { * Adds multiple dependency vectors. * * @param vectors dependency vectors to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVectors(@NotNull Collection vectors) { this.vectors.addAll(vectors); + resolved = false; return this; } @@ -84,10 +105,12 @@ public final class DependencyResolver { * Adds multiple dependency vectors. * * @param vectors dependency vectors to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVectors(@NotNull List vectors) { this.vectors.addAll(vectors); + resolved = false; return this; } @@ -95,10 +118,12 @@ public final class DependencyResolver { * Adds multiple dependency vectors. * * @param vectors dependency vectors to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVectors(@NotNull ImmutableArrayList vectors) { this.vectors.addAll(vectors); + resolved = false; return this; } @@ -106,10 +131,12 @@ public final class DependencyResolver { * Adds multiple dependency vectors. * * @param vectors dependency vectors to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVectors(@NotNull ImmutableLinkedList vectors) { this.vectors.addAll(vectors); + resolved = false; return this; } @@ -117,10 +144,12 @@ public final class DependencyResolver { * Adds multiple dependency vectors. * * @param vectors dependency vectors to add + * @return itself * @since 1-alpha1 */ public DependencyResolver addVectors(@NotNull Set vectors) { this.vectors.addAll(vectors); + resolved = false; return this; } @@ -128,11 +157,15 @@ public final class DependencyResolver { * Resolves all dependency vectors. * Throws an exception when detecting an unmet dependency or a dependency cycle. * + * @return itself + * @throws UnmetDependenciesException when dependencies are unmet + * @throws UnexpectedThrowableException when some unknown error occurs * @since 1-alpha1 */ @SuppressWarnings("JavaReflectionInvocation") public DependencyResolver resolve() throws UnmetDependenciesException, UnexpectedThrowableException { Map unmetDependencies = new HashMap<>(); + resolved = false; try { for (DependencyVector vector : vectors) @@ -216,6 +249,7 @@ public final class DependencyResolver { if (!unmetDependencies.isEmpty()) throw new UnmetDependenciesException(unmetDependencies); + resolved = true; return this; } @@ -223,9 +257,13 @@ public final class DependencyResolver { * Returns the correct order which stuff needs to be loaded/done in. * * @return {@link LinkedList} with dependencies first and dependents last + * @throws IllegalStateException when the current dependency vector list has not been resolved yet. in this case, just invoke {@code resolve()} * @since 1-alpha1 */ - public LinkedList getOrder() { + public LinkedList getOrder() throws IllegalStateException { + if (!resolved) + throw new IllegalStateException("The current dependency vector list has not been resolved yet"); + LinkedList list = new LinkedList<>(); return list; diff --git a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/Window.java b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/Window.java index 36be063..6a04f05 100644 --- a/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/Window.java +++ b/graphics/opengl/src/main/java/de/staropensource/sosengine/graphics/opengl/classes/Window.java @@ -49,7 +49,7 @@ public class Window implements de.staropensource.sosengine.graphics.classes.Wind * -- GETTER -- * Returns a set of all active windows. * - * @return set of all active windows + * @return set of all windows * @since 1-alpha0 */ @Getter